How to write Outlook COM add-in / plugin in VB.NET, C#, C++.
Create ribbon tabs, menus, buttons for Outlook toolbar.
Add-in Express™ |
|
The class name of the form, instances of which will be created and shown as specified in other properties. |
|
An instance of the form specified in the FormClassName property will be shown below the list of items in the Outlook Explorer whenever you navigate to a mail folder. |
|
An instance of the form specified in the FormClassName property will be shown below the message body whenever you open an e-mail. |
|
These will show a header containing the form icon and the form caption even if the form is a single form in the given region. The header will contain the Close button; when you click it, the form will generate the OnADXBeforeCloseButtonClick event (cancellable). |
|
A pre-defined color corresponding to the current Office theme is used for the background of the form specified in the FormClassName property. |

See also Advanced Outlook Regions.
Step 11. Accessing Outlook objects
Add the following method to the add-in module:
Friend Function GetSubject(ByVal InspectorOrExplorer As Object) As String
Dim item As Object = Nothing
Dim selection As Outlook.Selection = Nothing
If TypeOf InspectorOrExplorer Is Outlook.Explorer Then
Try
'Explorer.Selection fires an exception for a top-level folder
selection = CType(InspectorOrExplorer, Outlook.Explorer).Selection
item = selection.Item(1)
Catch
Finally
If selection IsNot Nothing Then Marshal.ReleaseComObject(selection)
End Try
ElseIf TypeOf InspectorOrExplorer Is Outlook.Inspector Then
Try
item = CType(InspectorOrExplorer, Outlook.Inspector).CurrentItem
Catch
End Try
End If
If item Is Nothing Then
Return ""
Else
Dim subject As String = "The subject is:" + "'" + _
item.GetType().InvokeMember("Subject", _
Reflection.BindingFlags.GetProperty, _
Nothing, item, Nothing).ToString() _
+ "'"
Marshal.ReleaseComObject(item)
Return subject
End If
End Function
The code of the GetSubject method emphasizes the following:
- Outlook fires an exception when you obtain the Selection object for a top-level folder, such as Personal Folders
- There may be no items in the Selection object
- All COM objects created in your code must be released, see Releasing COM objects
Now create the following event handlers for the CommandBar and Ribbon buttons added in previous steps:
Private Sub ActionInExplorer(ByVal sender As System.Object) _
Handles AdxCommandBarButton1.Click
Dim explorer As Outlook.Explorer = Me.OutlookApp.ActiveExplorer
If explorer IsNot Nothing Then
MsgBox(GetSubject(explorer))
Marshal.ReleaseComObject(explorer)
End If
End Sub
Private Sub ActionInInspector(ByVal sender As System.Object) _
Handles AdxCommandBarButton2.Click, AdxCommandBarButton6.Click
Dim inspector As Outlook.Inspector = Me.OutlookApp.ActiveInspector
If inspector IsNot Nothing Then
MsgBox(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
Dim context As Object = control.Context
If TypeOf context Is Outlook.Inspector Then
' Outlook 2007 and higher
ActionInInspector(Nothing)
ElseIf TypeOf context Is Outlook.Explorer Then
' Outlook 2010 and higher
ActionInExplorer(Nothing)
Else
' there can be a lot of other contexts in Outlook 2010,
' see http://msdn.microsoft.com/en-us/library/ee692172(office.14).aspx
End If
Marshal.ReleaseComObject(context)
End Sub
Step 12. Handling Outlook events
The Add-in Express Toolbox provides the Add Events command that adds (and removes) event components providing application-level events. In this sample, we add the Outlook Events component to the add-in module.
With the Outlook Events component, you handle 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
If you create a label on the form added in Step 10 - Adding an advanced Outlook region in Outlook 2000-2010, you can modify the label in the ADXSelectionChange event of the form:
Private Sub ADXOlForm1_ADXSelectionChange() Handles MyBase.ADXSelectionChange
Me.Label1.Text = CType(Me.AddinModule, MyOutlookAddin1.AddinModule) _
.GetSubject(Me.ExplorerObj)
End Sub
See also Step 13 - Handling events of Outlook Items Object and Events Classes.
Step 13. 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 item located 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
To process events of the Folders and Items classes as well as of all item sorts in Outlook, see Event classes.
Step 14. Adding property pages to the folder properties dialog
Outlook allows adding custom pages (tabs) to the Options dialog (the Tools | Options menu) as well as to the Properties dialog of any folder. To automate this task, Add-in Express provides the ADXOlPropertyPage component. You find it in the Add New Item dialog (see the screenshot below).

Click the Add button to add a descendant of the ADXOlPropertyPage class to your project. You can customize that page as an ordinary form: add controls and handle their events.
To add a property page to the <folder name> 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. The code below gets the full folder name of the Inbox folder in the AddinStartupComplete event of 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
See the code of the GetFolderPath function in FolderPath property is missing in Outlook 2000 and XP.
Now add a checkbox to the property page. The code below handles the CheckedChanged event of the checkbox as well as the Dirty, Apply, and Load events of the property page:
...
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 (Outlook 2000-2007), you use the PageType and PageTitle properties of the add-in module. In Outlook 2010 that dialog is located at the following UI path: File Tab | Options | Add-ins | Add-in Options.
See also Outlook Property page.
Step 15. Intercepting keyboard shortcuts
To intercept a keyboard shortcut, you use the Add Keyboard Shortcut command to add an ADXKeyboardShortcut to the add-in module.
Then, in the Properties window for the Keyboard Shortcut component, you choose 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 16. Running the COM add-in
Choose Register Add-in Express Project in the Build menu, restart Outlook and find your option page(s), command bars, and controls, Ribbon controls, and custom task panes.

If you use an Express edition of Visual Studio, the Register Add-in Express Project item is located in the context menu of the add-in module's designer surface.


You can find your add-in in the COM Add-ins dialog.
Step 17. Debugging the COM add-in
To debug your add-in, just specify the Outlook executable in Start External Program in the Project Options window and press F5.

Step 18. Deploying the COM add-in
The table below provides links to step-by-step instructions for deploying COM add-ins. Find background information in Deploying Office extensions.
|
How you install the Office extension |
Per-user COM add-in |
Per-machine COM add-in |
| A user runs the installer from a CD/DVD, hard disk or local network location. |
Windows Installer ClickOnce ClickTwice :) |
Windows Installer ClickTwice :) |
| A corporate admin uses Group Policy to install your Office extension for a specific group of users in the corporate network; the installation and registration occurs when a user logs on to the domain. For details, please see the following article on our blog: HowTo: Install a COM add-in automatically using Windows Server Group Policy. | Windows Installer | N/A |
| A user runs the installer by navigating to a web location or by clicking a link. |
ClickOnce ClickTwice :) |
ClickTwice :) |
What's next?
Here you can download the project described above, both VB.NET and C# versions; the download link is labeled Add-in Express for Office and .NET sample projects.
You may want to check the following sections under Add-in Express tips and notes:
- Development - typical misunderstandings, useful tips and a must-read section Releasing COM Objects.
- COM add-ins - solutions for typical problems: the add-in doesn't show the UI elements, etc.
- Command bars and controls - if your COM add-in supports pre-Ribbon Office applications.
- Debugging and deploying - if you have never developed an Office extension.
Also, in Add-in Express components we describe components that you use to customize the UI of the host application and handling its events.
|
See Also
|




























