How to write Outlook COM add-in / plugin in VB.NET, C#, C++.
Create ribbon tabs, menus, buttons for Outlook toolbar.

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home > Add-in Express .NET > Online Guide > Writing Outlook COM add-ins

Outlook COM add-in in C#, C++, VB.NET

All Microsoft Outlook COM add-ins / plug-ins provide two capabilities that developers request most often - extending menus and toolbars at the Explorer and Inspector levels, and extending property pages for folders and the main Options page. That is why Add-in Express provides several Outlook specific classes that allow you to use these features. Also, Add-in Express offers you some unique options for customizing the Navigation pane, Preview pane and Outlook bar. Find more about special features for extending the Outlook plug-in GUI.

Add-in Express provides several Outlook specific toolbar components: ADXOlExplorerCommandBar and ADXOlInspectorCommandBar. The first adds a toolbar to the Outlook Explorer window and solves numerous problems with custom Outlook toolbar. The latter adds a toolbar to the Outlook Inspector window. Both ADXOlExplorerCommandBar and ADXOlInspectorCommandBar have the FolderName, FolderNames, and ItemTypes properties that add context-sensitivity to Outlook command bars. The OlExplorerItemTypes, OlInspectorItemTypes, and OlItemTypeAction properties add context-sensitivity to Outlook command bar controls. There are also two Outlook-specific main menu components: ADXOlExplorerMainMenu and ADXOlInspectorMainMenu. Additionally, Add-in Express supplies the Outlook Property Page component that helps you to add your pages to the Options (Tools | Options menu) and Folder Properties dialogs.

Example of creating an Outlook COM add-in

The example below shows you step-by-step how to write a COM add-in for Outlook 2000 - 2007. It is written in VB.NET, but you can develop your COM add-in projects in C++, C# and Delphi Prism. You may also want to see another sample Outlook 2007 add-in project in VB.NET and download a free Outlook add-in in C# and VB.NET.

Step 1. Creating a new Outlook COM add-in project

To create a new COM add-in project close all opened solutions, choose "File | New | Project...", select the "Other Projects | Extensibility Projects" item, and choose the Add-in Express COM Add-in project template in the Visual Studio IDE.

When you click OK, the COM add-in project wizard starts. In the wizard windows, you choose the programming language (in our sample project it is VB.NET, but you can also develop in C# and C++). Also, you select setup project options, applications supported by your add-in (as you may guess it is Outlook), and PIAs options.

This VB.NET sample shows a project implementing an Outlook COM add-in with the Add-in Express loader as a shim. To understand shims and the Add-in Express loader, see Deploying COM add-in projects. You can download this sample Outlook add-in in VB.NET and C# (VS 2005).

 
When you click the Finish button, the Add-in Express Project wizard creates and opens the COM add-in solution in Visual Studio. The solution includes the COM Add-in project and the setup project for your Outlook add-in.

The COM Add-in project contains the AddinModule.vb (or AddinModule1.cs) file described in the next step.

Step 2. COM Add-in module

The AddinModule.vb (or AddinModule1.cs) is a COM Add-in module that is the core part of the COM add-in project. The add-in module implements the IDTExtensibility2 interface and allows you to manage add-in toolbars and their controls. The module is the container for Add-in Express components, which allow you to concentrate on the functionality of your add-in. You specify add-in properties in the module's properties, add components to the module's designer, and write the functional code of your add-in in this module. To review its source code, in Solution Explorer, right-click the AddinModule1.vb (or AddinModule1.cs) file and choose the View Code popup menu item.

The code for AddinModule1.vb follows below. Please, pay attention to the OutlookApp property of the module generated by the wizard. You can use it in your code to get access to Outlook objects.

Imports System.Runtime.InteropServices
Imports System.ComponentModel
'Add-in Express Add-in Module
<GuidAttribute("3BDF26A5-74E4-42CB-A93A-E88435BC0AD3"), _
      ProgIdAttribute("MyOutlookAddin1.AddinModule")> _
Public Class AddinModule
   Inherits AddinExpress.MSO.ADXAddinModule

#Region " Component Designer generated code. "
   'Required by designer
   Private components As System.ComponentModel.IContainer
   'Required by designer - do not modify
   'the following method
   Private Sub InitializeComponent()
      Me.components = New System.ComponentModel.Container
      '
      'AddinModule
      '
      Me.AddinName = "MyOutlookAddin1"
      Me.SupportedApps = AddinExpress.MSO.ADXOfficeHostApp.ohaOutlook
   End Sub
#End Region
#Region " Add-in Express automatic code "
   'Required by Add-in Express - do not modify
   'the methods within this region
   Public Overrides Function GetContainer() As _
         System.ComponentModel.IContainer
      If components Is Nothing Then
         components = New System.ComponentModel.Container
      End If
      GetContainer = components
   End Function
   <ComRegisterFunctionAttribute()> _
   Public Shared Sub AddinRegister(ByVal t As Type)
      AddinExpress.MSO.ADXAddinModule.ADXRegister(t)
   End Sub
   <ComUnregisterFunctionAttribute()> _
   Public Shared Sub AddinUnregister(ByVal t As Type)
      AddinExpress.MSO.ADXAddinModule.ADXUnregister(t)
   End Sub
   Public Overrides Sub UninstallControls()
      MyBase.UninstallControls()
   End Sub
#End Region
   Public Sub New()
      MyBase.New()
      'This call is required by the Component Designer
      InitializeComponent()
      'Add any initialization after the InitializeComponent() call
   End Sub
   Public ReadOnly Property OutlookApp() As Outlook._Application
      Get
         Return CType(HostApplication, Outlook._Application)
      End Get
   End Property
End Class

Step 3. Customizing your Outlook add-in using the designer

The Add-in Express COM Add-in designer allows setting add-in properties and adding components to the module. In the Solution Explorer window, open the add-in module in the design view, and activate the Properties window.

In the Properties window, you set the name and description of your add-in module (see COM add-in designers).

To add an Add-in Express component to the module, you use an appropriate command in the Properties window, or you can right-click the designer surface and choose the same command in the context menu.

You can use the following module commands in Outlook COM add-ins:

• Add Explorer CommandBar – adds an Outlook Explorer toolbar to your add-in.
• Add Inspector CommandBar – adds an Outlook Inspector toolbar to your add-in.
• Add Outlook Bar Shortcut Manager – adds a component that allows adding Outlook Bar shortcuts and shortcut groups (see Outlook Bar Shortcut Manager).
• Add Outlook Forms Manager – adds a component that allows embedding custom .NET forms into Outlook windows (see Outlook Forms Manager).
• Add Ribbon Tab – adds a Ribbon tab to your add-in (see Office 2007 Ribbon components).
• Add Ribbon Quick Access Toolbar – adds a component that allows customizing the Ribbon Quick Access Toolbar in your add-in.
• Add Ribbon Office Menu – adds a component that allows customizing the Ribbon Office Menu in your add-in.
• Add Events – adds or deletes components that provide access to Outlook application-level events (see Application-level events).

See more commands of the add-in module.

Step 4. Adding a new Explorer toolbar

To add a command bar to the Outlook Explorer window, use the Add Explorer CommandBar command that adds an ADXOlExplorerCommandBar component to the add-in module.

Select the command bar component and, in the Properties window, specify the command bar name using the CommandBarName property and choose its position. The component provides context-sensitive properties. They are FolderName, FolderNames, and ItemTypes (see Outlook CommandBar visibility rules).

Select the Explorer CommandBar component, and, in the Properties window, specify the toolbar name using the CommandBarName property and choose its position (see the Position property on the screenshot above). Outlook-specific versions of Add-in Express CommandBar component provides context-sensitive properties. They are FolderName, FolderNames, and ItemTypes

In the screenshot, you see the properties of the Outlook Explorer toolbar that will be shown for every Outlook folder (FolderName = "*") the default item types of which are Mail or Task. See COM add-ins for Outlook – template characters in FolderName and Command bars: toolbars, menus, context menus).

Step 5. Adding a new commandbar button

To add a new button to the Outlook Explorer command bar, in the Properties window, you select the Controls property and click the property editor button (the button in the property value box). This runs the visual designer. Use its toolbar to add or remove Command bar controls. Just click the appropriate button and see the result. To add an icon to the button, add an ImageList to the add-in module. Then specify the button's Caption property and set the ImageList, Image, and ImageTransparentColor properties of the button. Finally, set the Style property because its default value doesn't show the button image. Adding a new command bar button

For more details about extending Outlook command bar with custom toolbar controls, see a sample project that shows how to add visual .NET controls to Outlook toolbar.

Step 6. Customizing the Outlook 2007 Ribbon user interface

To add a new tab to the Ribbon, you use the Add Ribbon Tab command that adds an ADXRibbonTab component to the module.

In the Properties window, run the editor for the Controls collection of the tab. In the designer window, use the toolbar buttons or context menu to add or delete Add-in Express components that form the Ribbon interface of your add-in. First, you add a Ribbon tab and change its caption to My Ribbon Tab. Then, you select the tab component, add a Ribbon group, and change its caption to My Ribbon Group. Next, you select the group, and add a button group. Finally, you select the button group and add a button. Set the button caption to My Ribbon Button. Use the ImageList and Image properties to set the icon for the button.

Click OK, and, in the Properties window, find the newly added Ribbon button. Remember, the Office 2007 Ribbon tab designer performs the XML-schema validation automatically, so from time to time you will run into the situation when you cannot add a control to some level. It is a restriction of the Ribbon XML-schema.

Unlike other Ribbon-based applications Outlook, has numerous ribbons. Please use the Ribbons property of your ADXRibbonTab components to specify the ribbons you customize with your tabs. See also Office 2007 ribbon components and tips about Outlook 2007 ribbons.

Step 7. Accessing Outlook objects

The Add-in Module provides the HostApplication property that returns the Application object (of the Object type) of the host application the add-in is currently running in. For your convenience, the ADD-IN EXPRESS Project wizard adds host-related properties to the Add-in module. You use these properties to access host application objects. For instance, this sample add-in includes the OutlookApp property in the Add-in module:

   Public ReadOnly Property OutlookApp() As Outlook._Application
      Get
         Return CType(HostApplication, Outlook._Application)
      End Get
   End Property

The _Application object provides the same properties and methods as the Application object but it doesn't provide events. This allows you to write the following code to the Click event of the button just added:

   Private Sub AdxCommandBarButton1_Click(ByVal sender As System.Object) _
         Handles AdxCommandBarButton1.Click
      MsgBox("The subject is:" _
         + vbCrLf _
         + Me.OutlookApp.ActiveExplorer.Selection.Item(1).Subject)
   End Sub

Step 8. Adding a new Inspector toolbar

To add a toolbar to the Outlook Inspector window, use the Add Inspector CommandBar command that adds an ADXOlInspectorCommandBar component to the COM Add-in module.

The Inspector command bar component provides the same properties as the Explorer command bar component. In the screenshot, you see the default values for the Inspector toolbar. The Inspector command bar component provides the same properties as the Explorer command bar component. If you specify the full path to a folder in the FolderName (FolderNames) property of an inspector command bar component, the corresponding toolbar is displayed for inspectors that open Outlook items the Parent properties of which point to that folder.

See also Customizing Outlook Inspector window.

Step 9. Customizing Outlook main menu

Outlook provides two main menu types. They are available for two main types of Outlook windows: Explorer and Inspector. Accordingly, Add-in Express provides two main menu components: Explorer Main Menu component and Inspector Main Menu component. You add either of them using the context menu of the add-in module. Then you use the visual designer provided for the Controls property of the component.

For instance, to add a custom control to the popup shown by the File | New item in all Outlook Explorer windows, you start our free Built-in Control Scanner to scan the command bars and controls of Outlook. The screenshot below shows the result of scanning. You need the Office IDs from the screenshot to bind Add-in Express controls to them:

• Add a popup control to the menu and set its Id property to 30002
• Add a popup control to the popup control above and set its Id to 30037
• Add a button to the popup above and specify its properties.

The following screenshot shows the settings of the popup created at step 3 above:

Step 10. Customizing Outlook context menu

Outlook allows customizing several context menus. Add-in Express allows customizing Outlook menus via the Context Menu component. You use the context menu of the add-in module to add such a component onto the module. Then you choose Outlook in the SupportApp property of the component. Then, in the CommanBarName property, you choose the context menu you want to customize. And finally, you add custom controls in the visual designer supplied for the Controls property.

The sample add-in described on this page adds a custom item to the Folder Context Menu command bar that implements the context menu which is shown when you right-click a folder in the folder tree.

Step 11. Adding a custom task pane in Outlook 2000 - 2007

You start with adding an Add-in Express Outlook Form to your project. Then you add an Outlook Forms Manager component onto your add-in module (see How to add a component to the Add-in Express designer). Finally, you add an item to the Items collection of the manager component and set the following properties of the item:

• ExplorerItemTypes = Mail – your form will be shown for all mail folders
• ExplorerLayout = BottomSubpane – the task pane will be shown below the list of mails in Outlook Explorer
• InspectorItemTypes = Mail – an instance of the form will be shown whenever you open an e-mail
• InspectorLayout = BottomSubpane – your task pane will be shown to the right of the message body
• AlwaysShowHeader = True – the header containing the icon (a 16x16 .ico) and the caption of your form will be shown for your form even if it is a single form in the given region
• CloseButton = True – the header will contain the Close button; a click on it generates the OnADXBeforeCloseButtonClick event of the form
• FormClassName = MyOutlookAddin1.ADXOlForm1 – the class name of the form

For more information, please see Advanced custom task panes. If you develop for Excel, see also how to create a custom Excel task pane.

Step 12. Accessing Outlook Objects

Add the following method to the add-in module:

Friend Function GetSubject(ByVal InspectorOrExplorer As Object) As String
    If InspectorOrExplorer Is Nothing Then Return ""

    Dim mailItem As Outlook.MailItem = Nothing
    Dim selection As Outlook.Selection = Nothing

    If TypeOf InspectorOrExplorer Is Outlook.Explorer Then
        Try
            selection = CType(InspectorOrExplorer, Outlook.Explorer).Selection
            If selection.Count > 0 Then mailItem = selection.Item(1)
        Catch
        Finally
            If selection IsNot Nothing Then Marshal.ReleaseComObject(selection)
        End Try
    ElseIf TypeOf InspectorOrExplorer Is Outlook.Inspector Then
        Try
            mailItem = CType(InspectorOrExplorer, Outlook.Inspector).CurrentItem
        Catch
        End Try
    End If

    If mailItem Is Nothing Then
        Return ""
    Else
        Dim subject As String = mailItem.Subject
        Marshal.ReleaseComObject(mailItem)
        Return subject
    End If
End Function

The code of the GetSubject method emphasizes the following: 

• Outlook 2007 fires an exception when you try to obtain the Selection object in some situations. 
• There may be no items in the Selection object. For information about the use of Marshal.ReleaseComObject, see Releasing COM objects.

Now select the buttons added in previous steps in the Properties window combo one by one and create the following event handlers:

Private Sub DefaultActionInExplorer(ByVal sender As System.Object) _
   Handles AdxCommandBarButton1.Click
    Dim explorer As Outlook.Explorer = Me.OutlookApp.ActiveExplorer
    If explorer IsNot Nothing Then
        MsgBox("The subject is:" _
           + vbCrLf _
           + GetSubject(explorer))
        Marshal.ReleaseComObject(explorer)
    End If
End Sub

Private Sub DefaultActionInInspector(ByVal sender As System.Object) _
         Handles AdxCommandBarButton2.Click, AdxCommandBarButton6.Click
    Dim inspector As Outlook.Inspector = Me.OutlookApp.ActiveInspector
    If inspector IsNot Nothing Then
        MsgBox("The subject is:" _
           + vbCrLf _
           + GetSubject(inspector))
        Marshal.ReleaseComObject(inspector)
    End If
End Sub

Private Sub AdxRibbonButton1_OnClick(ByVal sender As System.Object, _
    ByVal control As AddinExpress.MSO.IRibbonControl, _
    ByVal pressed As System.Boolean) Handles AdxRibbonButton1.OnClick
    DefaultActionInInspector(Nothing)
End Sub

Step 13. Handling Outlook events

The COM add-in designer provides the Add Events command that adds (and remove) event components that allow handling application-level events. When you choose this command, the Add Application Events dialog box opens allowing you to select the application events components you need. In this sample, we add the Outlook Events component to the add-in module.

With the Outlook Events component, you handle any application-level events of Outlook. For instance, the following code handles the BeforeFolderSwitch event of the Outlook Explorer class:

   Private Sub adxOutlookEvents_ExplorerBeforeFolderSwitch _
      (ByVal sender As Object, _
      ByVal e As _
             AddinExpress.MSO.ADXOlExplorerBeforeFolderSwitchEventArgs) _
      Handles adxOutlookEvents.ExplorerBeforeFolderSwitch
      MsgBox("You are switching to the " + e.NewFolder.Name + " folder")
   End Sub

On the form added in Step 10.  Adding a Custom Task Pane in Outlook 2000 - 2007, you add a label and handle, say the ADXSelectionChange event of the form:

For more information about processing Outlook events, see Event classes.

Step 14. Handling events of Outlook Items object

The Outlook MAPIFolder class provides the Items collection. This collection provides the following events: ItemAdd, ItemChange, and ItemRemove. To process these events, you use the Outlook Items Events Class located in the Add-in Express Items folder in the Add New Item dialog:

This adds the OutlookItemsEventsClass1.vb class to the add-in project. You handle the ItemAdd event by entering some code into the ProcessItemAdd procedure of the class:

Imports System

'Add-in Express Outlook Items Events Class
Public Class OutlookItemsEventsClass1
   Inherits AddinExpress.MSO.ADXOutlookItemsEvents

   Public Sub New(ByVal ADXModule As AddinExpress.MSO.ADXAddinModule)
      MyBase.New(ADXModule)
   End Sub

   Public Overrides Sub ProcessItemAdd(ByVal Item As Object)
      MsgBox("The item with subject '" + Item.Subject + _
         "' has been added to the Inbox folder")
   End Sub

   Public Overrides Sub ProcessItemChange(ByVal Item As Object)
      'TODO: Add some code
   End Sub

   Public Overrides Sub ProcessItemRemove()
      'TODO: Add some code
   End Sub
End Class

To use this class, you have to add the following declarations and code to the add-in module:

   Dim ItemsEvents As OutlookItemsEventsClass1 = _
          New OutlookItemsEventsClass1(Me)
...
   Private Sub AddinModule_AddinBeginShutdown(ByVal sender As Object, _
         ByVal e As System.EventArgs) Handles Me.AddinBeginShutdown
      If ItemsEvents IsNot Nothing Then
         ItemsEvents.RemoveConnection()
         ItemsEvents = Nothing
      End If
   End Sub

   Private Sub AddinModule_AddinStartupComplete(ByVal sender As Object, _
         ByVal e As System.EventArgs) Handles Me.AddinStartupComplete
      ItemsEvents.ConnectTo( _
            AddinExpress.MSO.ADXOlDefaultFolders.olFolderInbox, True)
   End Sub

Step 15. Adding Outlook folder property pages

Outlook allows you to add custom option pages to the Options dialog box (the Tools | Options menu) and / or to the Properties dialog box of any folder. To automate this task, Add-in Express provides the ADXOlPropertyPage component. You find it in the Add New Item dialog box.

Click the Add button to add a descendant of the ADXOlPropertyPage class that implements the IPropertyPage COM interface to your project. You can customize the page as an ordinary form: add the controls and handle their events.

To add a property page to the Properties dialog box of an Outlook folder(s), you do the following: 

• In the add-in module properties, run the editor of the FolderPages property, 
• Click the Add button
• Specify the folder you need in the FolderName property
• Set the PageType property to the property page component you've added 
• Specify the Title property and close the dialog box.

The screenshot below shows the settings you need to display your page in the Folder Properties dialog for the Inbox folder.

The path to the Inbox folder depends on the environment as well as on the Outlook localization. To take care of this, get the path to the Inbox folder at add-in startup and assign it to the FolderName property of the Folder Page item. This can be done with the following code that handles the AddinStartupComplete event in the add-in module:

   Private Sub AddinModule_AddinStartupComplete(ByVal sender As Object, _
         ByVal e As System.EventArgs) Handles Me.AddinStartupComplete
   ItemsEvents.ConnectTo( _
      AddinExpress.MSO.ADXOlDefaultFolders.olFolderInbox, True)
   Dim ns As Outlook.NameSpace = Me.OutlookApp.GetNamespace("Mapi")
   Dim folder As Outlook.MAPIFolder = _
      ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox)
   Me.FolderPages.Item(0).FolderName = GetFolderPath(folder)
   Marshal.ReleaseComObject(folder)
   Marshal.ReleaseComObject(ns)
End Sub

You can find the code of the GetFolderPath function here: FolderPath property value in Outlook 2000 and XP.

In order to control the events for the folder, add a checkbox to the page and handle its CheckedChanged event as well as the Dirty, Apply, and Load events of the page as follows:

...
Friend WithEvents CheckBox1 As System.Windows.Forms.CheckBox
Private TrackStatusChanges As Boolean

...

Private Sub CheckBox1_CheckedChanged( _
ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles CheckBox1.CheckedChanged
    If Not TrackStatusChanges Then _
        Me.OnStatusChange() 'this enables the Apply button
End Sub

Private Sub PropertyPage1_Dirty( _
ByVal sender As System.Object, _
ByVal e As AddinExpress.MSO.ADXDirtyEventArgs) Handles MyBase.Dirty
    e.Dirty = True
End Sub

Private Sub PropertyPage1_Apply( _
ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles MyBase.Apply
    CType(AddinModule.CurrentInstance, MyOutlookAddin1.AddinModule) _
        .IsFolderTracked = Me.CheckBox1.Checked
End Sub

Private Sub PropertyPage1_Load( _
ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Load
    TrackStatusChanges = True
    Me.CheckBox1.Checked = _
        CType(AddinModule.CurrentInstance, MyOutlookAddin1.AddinModule) _
            .IsFolderTracked
    TrackStatusChanges = False
End Sub
Finally, you add the following property to the add-in module:
Friend Property IsFolderTracked() As Boolean
   Get
      Return ItemsEvents.IsConnected
   End Get
   Set(ByVal value As Boolean)
      If value Then
         ItemsEvents.ConnectTo(ADXOlDefaultFolders.olFolderInbox, True)
      Else
         ItemsEvents.RemoveConnection()
      End If
   End Set
End Property

This sample describes adding a property page to the Folder Properties dialog for a given folder. To add a property page to the Tools | Options dialog box, you use the PageType and PageTitle properties of the add-in module.

See also Outlook Property page.

Step 16. Intercepting keyboard shortcuts

To intercept a keyboard shortcut, you add an ADXKeyboardShortcut component to the COM Add-in Module using the Add Keyboard Shortcut command of the module. In the Properties window you select (or enter) the desired shortcut in the ShortcutText property.

To use keyboard shortcuts, you need to set the HandleShortcuts property of AddinModule to true.

Now you handle the Action event of the component:

   Private Sub AdxKeyboardShortcut1_Action(ByVal sender As System.Object) _
      Handles AdxKeyboardShortcut1.Action
      MsgBox("You've pressed " + _
         CType(sender, AddinExpress.MSO.ADXKeyboardShortcut).ShortcutText)
   End Sub

Step 17. Running the Outlook COM add-in

Save the add-in project, close Outlook, build and register the plugin using the Register Add-in Express project item from the Build menu, then restart Outlook and find your option page(s), command bars, and controls, Ribbon controls, and custom task panes:

You can find your add-in in the COM Add-ins dialog. See also Add the COM add-ins command to a toolbar or menu.

Step 18. Debugging the Outlook COM add-in

To debug your add-in, just specify the Outlook executable in Start External Program in the Project Options window.

However, when debugging an add-in or a smart tag on Visual Studio 2003 and Office XP you cannot see your add-in or smart tag on the COM add-ins or AutoCorrect dialog box. This is a “feature” of Office XP "added" by Microsoft.

Step 19. Deploying your Outlook add-in

Just built the setup project, copy all setup files to the target PC and run the setup.exe file to install the add-in. Read more about deploying Outlook COM add-in,  MSI and ClickOnce deployment,  find some useful deploying and debugging tips.

Back to Add-in Express .NET homepage