Build sample VSTO Outlook 2007 and Outlook 2003
add-in / plug-in in Visual C#, VB.NET
Add-in Express
for Microsoft VSTO
Add-in Express Home > Add-in Express for VSTO > Online Guide > Building Outlook plugins in VSTO
Program VSTO Outlook add-ins / plug-ins
Add-in Express 2008 for VSTO is the first component set that applies the RAD paradigm to COM add-in development. Now you can build a VSTO Outlook 2007 and Outlook 2003 add-in / plugin faster than ever before. Add-in Express provides additional components for COM Add-ins in Outlook. For more information, please see:
Now let's see Add-in Express in action. The sample Outlook add-in project below is written in VB.NET, but you can use Visual C# as well.
Step 1 – Creating a new VSTO Outlook add-in project
In Visual Studio 2005, close all opened solutions, choose “File | New | Project…”, select the “Outlook Add-in" item in either Visual Basic / Office / 2003 Add-ins (2007 Add-ins) or Visual C# / Office / 2003 Add-ins (2007 Add-ins) folder in the New Project dialog window, and click the OK button. After this, VSTO creates a solution with two projects: the Outlook add-in project (OutlookAddin1 in this sample) and the setup project (OutlookAddin1Setup).
Step 2 – Adding the Add-in Express module
Now you add an Add-in Express module: right-click on your project item in the Solution Explorer window of the Visual Studio environment, choose the Add-in Express Module item in the Add New Item dialog (it is located in the Add-in Express for VSTO Items folder in the dialog window) and click OK.
This adds the ADXModule1.vb (or ADXModule1.cs if you use C#) file to the add-in project and modifies the code of ThisAddin.vb (or ThisAddin.cs) as follows:
Public Class ThisAddIn
Private Sub ThisAddIn_Startup(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Startup
'Add-in Express for VSTO generated code
ADXModule1.Initialize(Me, _
System.Type.GetType("OutlookAddIn1.ADXModule1"))
End Sub
Private Sub ThisAddIn_Shutdown(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Shutdown
'Add-in Express for VSTO generated code
ADXModule1.Finalize(Me)
End Sub
End Class
Step 3 – Reviewing the Add-in Express module source code
The Add-in Express module contains the ADXModule1 class (ADXModule1.vb or ADXModule1.cs) - the core part of your Outlook add-in. Its designer, a placeholder of the Add-in Express components, allows you to specify such add-in properties as add-in name and description, load behavior and such. In this class, you add the applied code of your Outlook plug-in.
To add an Add-in Express component to the class designer, you select the appropriate command in the designer's context menu.
To review its source code, in the Solution Explorer window, right-click on the file and choose the View Code popup menu item. The code for ADXModule1.vb is as follows:
Imports System.Runtime.InteropServices
Imports System.ComponentModel
Imports System.Windows.Forms
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports Office = Microsoft.Office.Core
'Add-in Express for VSTO Module
<ComVisible(True)> _
Public Class ADXModule1
Inherits AddinExpress.VSTO.ADXOutlookAddin
#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()
End Sub
#End Region
#Region " ADX 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
#End Region
Public Sub New(ByVal Application As Object)
MyBase.New(Application)
'This call is required by the Component Designer
InitializeComponent()
'Add any initialization after the InitializeComponent() call
End Sub
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 HostApplication
End Get
End Property
End Class
Partial Public Class ThisAddIn
Protected Overrides Function RequestService(ByVal serviceGuid As Guid) _
As Object
If serviceGuid = GetType(Office.IRibbonExtensibility).GUID Then
ADXModule1.Initialize(Me, _
System.Type.GetType("OutlookAddIn1.ADXModule1"))
Return ADXModule1.CurrentInstance
End If
Return MyBase.RequestService(serviceGuid)
End Function
End Class
Please, pay attention to the OutlookApp property of the module. You can use it in your code to get access to Outlook objects.
Step 4 – Adding a new Outlook Explorer command bar
First off, activate the Add-in Express Module designer window. Right-click the Add-in Express Module designer window and choose the Add Explorer CommanBar popup menu item.
This adds an Explorer command bar (ADXOlExplorerCommandBar component) to your sample VSTO Outlook addin / plug-in.
Select the command bar component, and, in the Properties window, specify its name in the CommandBarName property and its position in the Position property. The command bar name in this sample doesn't coincide with any Outlook toolbar name, so this toolbar will be added to Outlook toolbars. If I chose, say, Standard for the toolbar name, this toolbar would be a built-in one.
Outlook Explorer and Outlook Inspector Command Bar components provide context-sensitive properties. They are FolderName, FolderNames, and ItemTypes.
In the screenshot, you see the Outlook Explorer command bar that will be shown for every Outlook folder (FolderName = "*") the default item type of which is Mail.
Outlook 2003 and Outlook 2007
In Outlook 2003, this command bar will be positioned at the top of the Outlook Explorer window. In Outlook 2007, this command bar will be shown in the Add-ins tab if the Visible property of the command bar is set to True and if the controls of the command bar are visible. See also How To for Outlook explorer toolbars.
Step 5 – Adding a new button onto the toolbar
To add a new button to the Outlook toolbar, select the Controls property of the commandbar, run its editor, and click the ADXCommandBarButton item of the Add button (see below).
Specify the button's Caption property, set the Style property (default value = adxMsoButtonCaption), and close the collection editor. To handle the Click event of the button, add the Click event handler. See also a sample project showing how to add any .NET control to Outlook toolbar in 5 easy steps.
Private Sub AdxCommandBarButton1_Click(ByVal sender As System.Object) _
Handles AdxCommandBarButton1.Click
End SubStep 6 – Accessing Outlook objects
For your convenience, Add-in Express also adds the OutlookApp property in the Add-in Module:
Public ReadOnly Property OutlookApp() As Outlook._Application
Get
Return HostApplication
End Get
End Property
Note, the HostApplication property mentioned in the code above returns the Application object (of the Object type) of the host application the add-in is currently running in (it's Outlook, if you remember). Knowing this, you can 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
ThisApplication property
This property of the Add-in Module returns the value of the ThisApplication VSTO property.
Step 7 – Handling Outlook events
The Add-in Module provides all application-level Outlook events. For instance, the following code handles the BeforeFolderSwitch event of the Outlook Explorer class:
Private Sub ADXModule1_ExplorerBeforeFolderSwitch _
(ByVal sender As Object, _
ByVal e As _
AddinExpress.VSTO.ADXOlExplorerBeforeFolderSwitchEventArgs) _
Handles Me.ExplorerBeforeFolderSwitch
MsgBox("You are switching to the " + e.NewFolder.Name + " folder")
End Sub
Step 8 – Adding a new Inspector command bar
To add a command bar to the Outlook Inspector window, use the Add Inspector CommandBar command that adds an ADXOlInspectorCommandBar component to the Add-in Module.
The Inspector command bar component provides the same properties as the Explorer command bar component. In the screenshot below you see the properties of the Inspector command bar that will be shown for Mail and Task Items.
Outlook add-ins, 2003 and 2007
In Outlook 2003, this command bar will be positioned at the top of the Outlook Inspector window. In Outlook 2007, this command bar will be shown in the Add-ins tab if the Visible property of the command bar is set to True and if the controls of the command bar are visible.
Add a new command bar button to the command bar (see Step 5 – Adding a new command bar button for details).
Now you can show the subject of the currently open mail or task item using the following code that handles the Click event of the button:
Private Sub AdxCommandBarButton2_Click(ByVal sender As System.Object) _
Handles AdxCommandBarButton2.Click
MsgBox("The subject is:" _
+ vbCrLf _
+ Me.OutlookApp.ActiveInspector.CurrentItem.Subject)
End Sub
See also HowTo for Outlook inspector toolbars.
Step 9 – 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 will add 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 for VSTO Outlook Items Events Class
Public Class OutlookItemsEventsClass1
Inherits AddinExpress.VSTO.ADXOutlookItemsEvents
Public Sub New(ByVal ADXModule As AddinExpress.VSTO.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
This requires adding the following declarations and code to the Add-in Module:
Dim ItemsEvents As OutlookItemsEventsClass1 = _
New OutlookItemsEventsClass1(Me)
...
Private Sub ADXModule1_OnBeginShutdown(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.OnBeginShutdown
If ItemsEvents IsNot Nothing Then
ItemsEvents.RemoveConnection()
ItemsEvents = Nothing
End If
End Sub
Private Sub ADXModule1_OnStartupComplete(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.OnStartupComplete
ItemsEvents.ConnectTo( _
AddinExpress.VSTO.ADXOlDefaultFolders.olFolderInbox, True)
End SubStep 10 – Adding Outlook folder property pages
Unlike other Office applications, 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 Outlook Property Page component. You find it in the Add New Item dialog box.
Click the Add button to add a new property page instance, a descendant of the ADXOlPropertyPage class that implements the IPropertyPage interface:
Imports System.Runtime.InteropServices
'Add-in Express for VSTO Outlook Options Page
Public Class OptionsPage1
Inherits AddinExpress.VSTO.ADXOlPropertyPage
#Region " Component Designer generated code "
Public Sub New()
MyBase.New()
'This call is required by the Component Designer
InitializeComponent()
'Add any initialization after the InitializeComponent() call
End Sub
'Clean up any resources being used
Protected Overloads Overrides Sub Dispose(ByVal disposing As Boolean)
If disposing Then
If Not (components Is Nothing) Then
components.Dispose()
End If
End If
MyBase.Dispose(disposing)
End Sub
'Required by designer
Private components As System.ComponentModel.IContainer
'Required by designer - do not modify
'the following method
_
Private Sub InitializeComponent()
components = New System.ComponentModel.Container()
'
'OptionsPage1
'
Me.Name = "OptionsPage1"
Me.Size = New System.Drawing.Size(413, 358)
End Sub
#End Region
End Class
You can customize the page as an ordinary form: add the controls and handle their events. To add a property page to the <FolderName> Properties dialog box of an Outlook folder(s), you do the following:
- In the AddinModule 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 PropertyPage component you've added.
- Specify the Title property and close the dialog box.
The screenshot above shows the settings you need to display your page in the Folder Properties dialog for all Mail folders (FolderName = '*' and ItemTypes = Mail). In order to limit the property page to the Inbox folder only, change the code of the OnStartupComplete event in the Add-in Module as follows:
Private Sub ADXModule1_OnStartupComplete(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.OnStartupComplete
ItemsEvents.ConnectTo(_
AddinExpress.VSTO.ADXOlDefaultFolders.olFolderInbox, True)
Dim ns As Outlook.NameSpace = Me.OutlookApp.GetNamespace("Mapi")
Dim folder As Outlook.MAPIFolder = _
ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox)
Dim FullPath As String = folder.FolderPath
' remove leading backslashes
Me.FolderPages.Item(0).FolderName = _
FullPath.Substring(2, FullPath.Length - 2)
Marshal.ReleaseComObject(folder)
Marshal.ReleaseComObject(ns)
End Sub
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()
End Sub
Private Sub OptionsPage1_Apply(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Apply
CType(AddinExpress.VSTO.ADXOutlookModule.Instance, _
OutlookAddIn1.ADXModule1).IsFolderTracked = _
Me.CheckBox1.Checked
End Sub
Private Sub OptionsPage1_Dirty(ByVal sender As Object, _
ByVal e As AddinExpress.VSTO.ADXDirtyEventArgs) Handles Me.Dirty
e.Dirty = True
End Sub
Private Sub OptionsPage1_Load(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Load
TrackStatusChanges = True
Me.CheckBox1.Checked = _
CType(AddinExpress.VSTO.ADXOutlookModule.Instance, _
OutlookAddIn1.ADXModule1).IsFolderTracked
TrackStatusChanges = False
End SubFinally, you add the following property to the AddinModule code:
...
Friend Property IsFolderTracked() As Boolean
Get
Return ItemsEvents.IsConnected
End Get
Set(ByVal value As Boolean)
If value Then
ItemsEvents.ConnectTo _
(AddinExpress.VSTO.ADXOlDefaultFolders.olFolderInbox, True)
Else
ItemsEvents.RemoveConnection()
End If
End Set
End PropertyPlease remember, you must check the Make Assembly COM-Visible checkbox to make your property pages work. Find it in Project Properties / Application / Assenbly Information.
Adding a page to the Outlook Options dialog
To add this or other property page to the main Options dialog box, you use the PageType and PageTitle properties of the add-in module. See also Outlook property page.
Step 11 – Intercepting keyboard shortcut
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. We chose the shortcut for the Send button in the mail Inspector's Standard command bar. It is Ctrl+Enter.
HandleShortcuts 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.VSTO.ADXKeyboardShortcut).ShortcutText)
End Sub
End Property
See also how to create custom application-level keyboard shortcuts.
Step 12 – Customizing the Outlook 2007 Ribbon User interface
You add a custom tab to the Outlook Inspector Ribbon using the Add Ribbon Tab command that adds an appropriate component to the module.
The Controls collection of the tab provides you with a handy tree-view-like editor that makes the task of customizing the Outlook Ribbon user interface as simple as it can be. Say, in the screenshot below you see how we added a Ribbon tab with a Ribbon group to which we added a button group and, finally, we placed a button in this button group. Ohhhh.
Having done this, in the Properties window, find the newly added Ribbon button and modify its Click event as follows:
Private Sub AdxRibbonButton1_OnClick(ByVal sender As System.Object, _
ByVal control As AddinExpress.VSTO.IRibbonControl, _
ByVal pressed As System.Boolean) Handles AdxRibbonButton1.OnClick
AdxCommandBarButton2_Click(Nothing)
End Sub
The Ribbon tab component performs the Outlook 2007 XML schema validation automatically.
Note, 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.
Step 13 – Adding custom task panes in Outlook 2007
Add a UserControl to the add-in project and add some controls to the UserControl. For the UserControl to become a custom task pane, you add an item to the TaskPanes collection of the Add-in Module and set the properties of the item: Title, ControlType, and OutlookWindows. That's easy. More about custom Outlook task panes.
Step 14 – Running your VSTO Outlook add-in
Save the project and build it.
Restart Outlook and see your sample Outlook plug-in with custom option page(s), command bars, ribbon tabs, and custom task panes. You find your add-in in the COM Add-ins dialog.
Use the Clean <YourProjectName> menu item in the Build menu to unregister the add-in.
Step 15 – Debugging the Outlook add-in
To debug your add-in, just choose the Start Debugging item in the Debug menu of Visual Studio.
Back to Add-in Express for VSTO homepage