Eugene Astafiev

How To: Get Outlook e-mail item’s custom properties – C# and VB.NET samples

In my previous article How To: Add a custom property to the UserProperties collection I showed you the way to add a custom property to the UserProperties collection of an e-mail item in Outlook. Now I want to demonstrate you how to iterate over all user properties of an e-mail item. The UserProperties class provides the Item method which returns a single UserProperty entry from the collection. As a parameter, the Item method expects to see either the index number or the name of the property. Please pay special attention to the fact that indexing in Office applications starts from one (not zero).

The code below iterates over all defined user properties and then shows a summary message box to the user. To get the code running, you just need to pass an instance of the MailItem class to the ShowUserProperties method.

C# and Add-in Express:

using System.Text; 
// ... 
private void ShowUserProperties(Outlook.MailItem mail) 
{ 
    Outlook.UserProperties mailUserProperties = null; 
    Outlook.UserProperty mailUserProperty = null; 
    StringBuilder builder = new StringBuilder(); 
    mailUserProperties = mail.UserProperties; 
    try 
    { 
       for (int i = 1; i < = mailUserProperties.Count; i++)
       { 
           mailUserProperty = mailUserProperties.Item(i);
           if (mailUserProperty != null)
           {
              builder.AppendFormat("Name: {0} \tValue: {1} \n\r", 
                  mailUserProperty.Name, mailUserProperty.Value); 
              Marshal.ReleaseComObject(mailUserProperty); 
              mailUserProperty = null; 
           } 
       } 
       if (builder.Length > 0) 
       { 
           System.Windows.Forms.MessageBox.Show(builder.ToString(),
               "The UserProperties collection"); 
       } 
    } 
    catch (Exception ex) 
    { 
        System.Windows.Forms.MessageBox.Show(ex.Message); 
    } 
    finally 
    { 
        if (mailUserProperties != null) 
            Marshal.ReleaseComObject(mailUserProperties); 
    } 
}

VB.NET and Add-in Express:

Imports System.Text 
' ... 
Private Sub ShowUserProperties(mail As Outlook.MailItem) 
    Dim mailUserProperties As Outlook.UserProperties = Nothing 
    Dim mailUserProperty As Outlook.UserProperty = Nothing 
    Dim builder As StringBuilder = New StringBuilder() 
    mailUserProperties = mail.UserProperties 
    Try 
        For i As Integer = 1 To mailUserProperties.Count 
            mailUserProperty = mailUserProperties.Item(i) 
            If Not IsNothing(mailUserProperty) Then 
                builder.AppendFormat("Name: {0} \tValue: {1} \n\r", _
                    mailUserProperty.Name, mailUserProperty.Value) 
                Marshal.ReleaseComObject(mailUserProperty) 
                mailUserProperty = Nothing 
             End If 
         Next 
         If (builder.Length > 0) Then 
             System.Windows.Forms.MessageBox.Show(builder.ToString(), _ 
                 "The UserProperties collection") 
         End If 
    Catch ex As Exception 
        System.Windows.Forms.MessageBox.Show(ex.Message) 
    Finally 
        If Not IsNothing(mailUserProperties) Then 
            Marshal.ReleaseComObject(mailUserProperties) 
        End If 
    End Try 
End Sub

C# and VSTO:

using System.Runtime.InteropServices; 
// ... 
private void ShowUserProperties(Outlook.MailItem mail) 
{
    Outlook.UserProperties mailUserProperties = null; 
    Outlook.UserProperty mailUserProperty = null; 
    StringBuilder builder = new StringBuilder(); 
    mailUserProperties = mail.UserProperties; 
    try 
    { 
        for (int i = 1; i < = mailUserProperties.Count; i++) 
        { 
            mailUserProperty = mailUserProperties[i]; 
            if (mailUserProperty != null) 
            { 
                builder.AppendFormat("Name: {0} \tValue: {1} \n\r", 
                    mailUserProperty.Name, mailUserProperty.Value); 
                Marshal.ReleaseComObject(mailUserProperty); 
                mailUserProperty = null; 
            } 
        } 
        if (builder.Length > 0) 
        { 
            System.Windows.Forms.MessageBox.Show(builder.ToString(), 
                 "The UserProperties collection"); 
        } 
    } 
    catch (Exception ex) 
    { 
        System.Windows.Forms.MessageBox.Show(ex.Message); 
    } 
    finally 
    { 
        if (mailUserProperties != null) 
            Marshal.ReleaseComObject(mailUserProperties); 
    } 
}

VB.NET and VSTO:

Imports System.Text 
Imports System.Runtime.InteropServices 
' ... 
Private Sub ShowUserProperties(mail As Outlook.MailItem)
    Dim mailUserProperties As Outlook.UserProperties = Nothing 
    Dim mailUserProperty As Outlook.UserProperty = Nothing 
    Dim builder As StringBuilder = New StringBuilder() 
    mailUserProperties = mail.UserProperties 
    Try 
        For i As Integer = 1 To mailUserProperties.Count 
            mailUserProperty = mailUserProperties.Item(i) 
            If Not IsNothing(mailUserProperty) Then 
                builder.AppendFormat("Name: {0} \tValue: {1} \n\r", _ 
                    mailUserProperty.Name, mailUserProperty.Value) 
                Marshal.ReleaseComObject(mailUserProperty) 
                mailUserProperty = Nothing 
            End If 
        Next 
        If (builder.Length > 0) Then 
            System.Windows.Forms.MessageBox.Show(builder.ToString(), _ 
                "The UserProperties collection") 
        End If 
    Catch ex As Exception 
        System.Windows.Forms.MessageBox.Show(ex.Message) 
    Finally 
        If Not IsNothing(mailUserProperties) Then 
            Marshal.ReleaseComObject(mailUserProperties) 
        End If 
    End Try 
End Sub

See you on our forums and in the e-mail support!

6 Comments

  • https://secure.gravatar.com/avatar/87cdb84d04abc559f95616b1b88936dc?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G shilpa says:

    how to display the data from xml in the outlook form region in the form of email listing

  • https://secure.gravatar.com/avatar/bbd979ae5b772d0bc1f82065aa4ba146?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Eugene Astafiev says:

    Hi Shilpa,

    Please try to use any .net controls (for example, from the System.Windows.Forms namespace). Also you may try to use the Outlook View Control (please read more about it at http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=4373 ).

  • https://secure.gravatar.com/avatar/70e9cf5aa95f61a785c2d279a453dd8e?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G scott says:

    Here is the same code you have, but for folders instead of mail items. Note the value doesn’t exist on the folder, so that is eliminated. Thanks for your code, exactly what I was looking for.

    public void ShowFolderUserProperties(Outlook.Folder folder)
    {
    Outlook.UserDefinedProperties folderProperties = null;
    Outlook.UserDefinedProperty folderProperty = null;
    StringBuilder builder = new StringBuilder();
    folderProperties = folder.UserDefinedProperties;
    try
    {
    for (int i = 1; i 0)
    {
    System.Windows.Forms.MessageBox.Show(builder.ToString(),
    “Hidden Property Values”);
    }
    else
    {
    System.Windows.Forms.MessageBox.Show(“No Hidden Property values found!”,
    “Notification”);
    }
    }
    catch (Exception ex)
    {
    System.Windows.Forms.MessageBox.Show(ex.Message);
    }
    finally
    {
    if (folderProperties != null)
    Marshal.ReleaseComObject(folderProperties);
    }
    }

  • https://secure.gravatar.com/avatar/bbd979ae5b772d0bc1f82065aa4ba146?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Eugene Astafiev says:

    You are welcome, Scott! ;-)

    FYI It looks like you forgot to paste the rest of the code above (for example, there is no definition for the builder object).

  • https://secure.gravatar.com/avatar/c8c9adc866d2cef24b7f9f2f01706388?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Jesse says:

    Hi Euegene,

    Wouldnt you need to Release the Function Paramater as well if it’s a COM Reference. I.e. in the above example, a ReleaseComObject(mail) in the Finally Block? Please let me know. Thx, Jes

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Jesse,

    The add-in project containing the code fragment above is expected to use the caller-is-responsible convention: a method calling the ShowUserProperties() method above should release the mail item after ShowUserProperties() returns.

Post a comment

Have any questions? Ask us right now!