How To: Set a custom icon for an Outlook folder in the Navigation Pane

Dear reader, today I want to show you one of the new features Outlook 2010 brought to programmers. Now Outlook allows setting custom icons the Navigation pane folders. The Outlook Object Model provides a special method for this task – SetCustomIcon. So, let’s start our journey into the Outlook programming world ;-)

Setting custom icons in Outlook – a bit of theory

The SetCustomIcon method is available at the MAPIFolder class level. This class also provides the opposite method for getting a custom icon – GetCustomIcon. However, today we will focus our attention on the setting a custom icon. The SetCustomIcon method accepts an instance of the IPictureDisp interface and doesn’t return anything. The VBA help reference (as well as the Outlook Object Model reference) provides a code to convert instances of .Net based classes to the IPictureDisp interface. Also you can find the sample solution (available for download at the end of article) which contains the entire code needed to get the job done.

Allowed types of images are icons and bitmaps. The size can be 32×32, 24×24 and 16×16. An appropriate size will be used depending on the DPI (Dots Per Inch) mode set on the PC. Outlook can scale up icons if a small image was set and Outlook is running in high DPI mode.

Not all Outlook folders accept custom icons

Not all folders allow you to set a custom icon. For example, I have tried to set a custom icon for the Inbox folder and immediately got the “Custom folder icon is not allowed…” exception:

A custom icon cannot be added to the following groups of folders in Outlook:

• Default folders (see the OlDefaultFolders enumeration)
• Special folders (see the OlSpecialFolders enumeration)
• Exchange public folders
• Exchange Root folders
• Hidden folders

As you might have noticed there are no search folders on the list, which means you can set custom icons for Search folders. The same technique is used for solutions module folders.

Only in-process callers are allowed

The Outlook Object Model doesn’t allow setting a custom icon for a folder from another application (using the OLE Automation technology). Only the in-process code can be used for such a task. An exception will be thrown in the SetCustomIcon method in this case.

Set an icon each time Outlook is started

I would like to draw your attention to the fact that Outlook doesn’t store the icon set during a previous session. So, if you programmatically set an icon and then close Outlook, there will be no icon when you open it anew. That is why you need to set an icon on each Outlook startup. For example, I created a folder and set a custom icon for it. Here is how it looks in my Outlook 2010:

Then I close Outlook and when I reopen it anew (without the code which was used for creating a folder and setting an icon), no icon is there:

The sample code in full details

Of course, I have prepared a sample code which shows how to set a custom icon for an Outlook folder. There are two main methods:

1. The SetUpFolder method – is used for creating a new folder if no such folder was created earlier. If a folder with the same name already exists we just need to find it. The method accepts an instance of the Outlook Application.
2. The SetCustomIcon method – is used for setting a custom icon for an Outlook folder (the name of our custom folder is “Smiling Folder”). It accepts an instance of the MAPIFolder class for which an icon should be set.

Note that if you try to add a folder and such a folder already exists, you will get an exception saying the folder cannot be created:

So, we need to find a folder first and only then, if there is folder with the same name, create it.

Below you can find a snippet of code developed in C# and VB.NET for VSTO and Add-in Express based add-ins. You can also download a complete solution which contains all the code including auxiliary code needed for converting images into the IPictureDisp interface. Note that I have included an image to the resources of each add-in project, so you won’t need to include it in the setup package manually. The image will be embedded into the add-in assembly automatically.

C# and Add-in Express:

using System.Drawing;
//
private void SetUpFolder(Outlook._Application OutlookApp)
{
    Outlook.NameSpace ns = null;
    Outlook.MAPIFolder folderInbox = null;
    Outlook.MAPIFolder parent = null;
    Outlook.Folders rootFolders = null;
    Outlook.MAPIFolder smileFolder = null;
    try
    {
         ns = OutlookApp.GetNamespace("MAPI");
         folderInbox = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox);
         parent = folderInbox.Parent as Outlook.MAPIFolder;
         rootFolders = parent.Folders;
         for (int i = 1; rootFolders.Count >= i; i++)
         {
             smileFolder = rootFolders[i];
             if (smileFolder.Name == "Smiling Folder")
             {
                 break;
             }
             else
             {
                 Marshal.ReleaseComObject(smileFolder);
                 smileFolder = null;
             }
         }
         if (smileFolder == null)
         {
             smileFolder = rootFolders.Add("Smiling Folder");
         }
         SetCustomIcon(smileFolder);
    }
    catch (Exception ex)
    {
        System.Windows.Forms.MessageBox.Show(ex.Message, 
                      "An exception was thrown in the code...");
    }
    finally
    {
        if (smileFolder != null) Marshal.ReleaseComObject(smileFolder);
        if (rootFolders != null) Marshal.ReleaseComObject(rootFolders);
        if (folderInbox != null) Marshal.ReleaseComObject(folderInbox);
        if (ns != null) Marshal.ReleaseComObject(ns);
    }
}
 
private void SetCustomIcon(Outlook.MAPIFolder folder)
{
    Icon icon = null;
    try
    {
        icon = ADX_CSharp.Properties.Resources.SampleIcon1;
        stdole.StdPicture iconPictureDisp = PictureDispConverter.ToIPictureDisp(icon) 
                                                                as stdole.StdPicture;
        folder.SetCustomIcon(iconPictureDisp);
    }
    finally
    {
        icon.Dispose();
    }
}

VB.NET and Add-in Express:

Imports System.Drawing
'
Private Sub SetUpFolder(OutlookApp As Outlook._Application)
    Dim ns As Outlook.NameSpace = Nothing
    Dim folderInbox As Outlook.MAPIFolder = Nothing
    Dim parent As Outlook.MAPIFolder = Nothing
    Dim rootFolders As Outlook.Folders = Nothing
    Dim smileFolder As Outlook.MAPIFolder = Nothing
    Try
        ns = OutlookApp.GetNamespace("MAPI")
        folderInbox = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox)
        parent = CType(folderInbox.Parent, Outlook.MAPIFolder)
        rootFolders = parent.Folders
        For i As Integer = 1 To rootFolders.Count
            smileFolder = rootFolders(i)
            If smileFolder.Name = "Smiling Folder" Then
                Exit For
            Else
                Marshal.ReleaseComObject(smileFolder)
                smileFolder = Nothing
            End If
        Next
        If IsNothing(smileFolder) Then
            smileFolder = rootFolders.Add("Smiling Folder")
        End If
        SetCustomIcon(smileFolder)
    Catch ex As Exception
        System.Windows.Forms.MessageBox.Show(ex.Message, _
                                      "An exception was thrown in the code...")
    Finally
        If Not IsNothing(smileFolder) Then Marshal.ReleaseComObject(smileFolder)
        If Not IsNothing(rootFolders) Then Marshal.ReleaseComObject(rootFolders)
        If Not IsNothing(folderInbox) Then Marshal.ReleaseComObject(folderInbox)
        If Not IsNothing(ns) Then Marshal.ReleaseComObject(ns)
    End Try
End Sub
 
Private Sub SetCustomIcon(folder As Outlook.MAPIFolder)
    Dim icon As Icon = Nothing
    Try
        icon = ADX_VBNET.My.Resources.SampleIcon1
        Dim iconPictureDisp As stdole.StdPicture = _
            CType(PictureDispConverter.ToIPictureDisp(icon), stdole.StdPicture)
        folder.SetCustomIcon(iconPictureDisp)
    Finally
        icon.Dispose()
    End Try
End Sub

C# and VSTO:

using System.Runtime.InteropServices;
using System.Drawing;
//
private void SetUpFolder(Outlook.Application Application)
{
     Outlook.NameSpace ns = null;
     Outlook.MAPIFolder folderInbox = null;
     Outlook.MAPIFolder parent = null;
     Outlook.Folders rootFolders = null;
     Outlook.MAPIFolder smileFolder = null;
     try
     {
         ns = Application.GetNamespace("MAPI");
         folderInbox = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox);
         parent = folderInbox.Parent as Outlook.MAPIFolder;
         rootFolders = parent.Folders;
         for (int i = 1; rootFolders.Count >= i; i++)
         {
             smileFolder = rootFolders[i];
             if (smileFolder.Name == "Smiling Folder")
             {
                 break; 
             }
             else
             {
                 Marshal.ReleaseComObject(smileFolder);
                 smileFolder = null;
             }
         }
         if (smileFolder == null)
         {
             smileFolder = rootFolders.Add("Smiling Folder");
         }
         SetCustomIcon(smileFolder);
     }
     catch (Exception ex)
     {
         System.Windows.Forms.MessageBox.Show(ex.Message,
                              "An exception was thrown in the code...");
     }
     finally
     {
         if (smileFolder != null) Marshal.ReleaseComObject(smileFolder);
         if (rootFolders != null) Marshal.ReleaseComObject(rootFolders);
         if (folderInbox != null) Marshal.ReleaseComObject(folderInbox);
         if (ns != null) Marshal.ReleaseComObject(ns);
     }
}
 
private void SetCustomIcon(Outlook.MAPIFolder folder)
{
    Icon icon = null;
    try
    {
        icon = VSTO_CSharp.Properties.Resources.SampleIcon1;
        stdole.StdPicture iconPictureDisp = PictureDispConverter.ToIPictureDisp(icon) 
                                                                as stdole.StdPicture;
        folder.SetCustomIcon(iconPictureDisp);
    }
    finally
    {
        icon.Dispose();
    }
}

VB.NET and VSTO:

Imports System.Drawing
Imports System.Runtime.InteropServices
'
Private Sub SetUpFolder(Application As Outlook.Application)
    Dim ns As Outlook.NameSpace = Nothing
    Dim folderInbox As Outlook.MAPIFolder = Nothing
    Dim parent As Outlook.MAPIFolder = Nothing
    Dim rootFolders As Outlook.Folders = Nothing
    Dim smileFolder As Outlook.MAPIFolder = Nothing
    Try
        ns = Application.GetNamespace("MAPI")
        folderInbox = ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox)
        parent = CType(folderInbox.Parent, Outlook.MAPIFolder)
        rootFolders = parent.Folders
        For i As Integer = 1 To rootFolders.Count
            smileFolder = rootFolders(i)
            If smileFolder.Name = "Smiling Folder" Then
                Exit For
            Else
                Marshal.ReleaseComObject(smileFolder)
                smileFolder = Nothing
            End If
        Next
        If IsNothing(smileFolder) Then
            smileFolder = rootFolders.Add("Smiling Folder")
        End If
        SetCustomIcon(smileFolder)
    Catch ex As Exception
        System.Windows.Forms.MessageBox.Show(ex.Message, 
                                       "An exception was thrown in the code...")
    Finally
        If Not IsNothing(smileFolder) Then Marshal.ReleaseComObject(smileFolder)
        If Not IsNothing(rootFolders) Then Marshal.ReleaseComObject(rootFolders)
        If Not IsNothing(folderInbox) Then Marshal.ReleaseComObject(folderInbox)
        If Not IsNothing(ns) Then Marshal.ReleaseComObject(ns)
    End Try
End Sub
 
Private Sub SetCustomIcon(folder As Outlook.MAPIFolder)
    Dim icon As Icon = Nothing
    Try
        icon = My.Resources.SampleIcon1
        Dim iconPictureDisp As stdole.StdPicture = CType( _
            PictureDispConverter.ToIPictureDisp(icon), stdole.StdPicture)
        folder.SetCustomIcon(iconPictureDisp)
    Finally
        icon.Dispose()
    End Try
End Sub

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

Available downloads:

These sample COM Add-ins were developed using Add-in Express for Office and .net:

C# Outlook add-ins: VSTO and Add-in Express based
VB.NET Outlook add-ins: VSTO and Add-in Express based

You may also be interested in:

• Special features for Outlook add-in development
• Advanced Outlook view and form regions