Build sample VSTO Outlook 2010, 2007, 2003 add-in / plugin,
customize toolbar, menu, ribbon in C#, VB.NET
Add-in Express Home > Add-in Express for Office and VSTO > Online Guide > Building Outlook plugins in VSTO
Program VSTO Outlook add-ins / plug-ins
Add-in Express for VSTO is the first component set that applies the RAD paradigm to COM add-in development. Now you can build a VSTO Outlook 2010, Outlook 2007 and 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:
Sample add-in for Outlook
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# and Delphi Prism as well. You can also download this sample Outlook add-in with source code
Step 1. Creating a new VSTO Outlook add-in project
If you use Visual Studio 2008, then close all opened solutions and select File | New | Project... in the menu and find the Add-in Express for VSTO Add-in item in the Extensibility node of the New Project dialog:
This starts the Add-in Express project wizard. In the project wizard window choose the programming language, the host application of your add-in and its version, make sure that the Generate the Setup Project option is on and click Finish.
If you use Visual Studio 2005 with VSTO 2005 SE installed, then create a new Outlook 2003 add-in solution and, in the Add New Item dialog, choose the Add-in Express Module item as shown on the screenshot below:
This code of ThisAddin.vb (or ThisAddin.cs) will look like this:
Step 2. Add-in module
The Add-in Express module (ADXModule.vb or ADXModule.cs) is the core part of your Outlook add-in project. In this module, you specify the add-in properties in the module's properties, add Add-in Express components to the module's designer, and write the functional code of your Outlook add-in.
To review its source code, in Solution Explorer, right-click the file and choose the View Code popup menu item. The VB.NET code of the module is as follows:
Step 3. Add-in Module designer
To access the Add-in Express Module Designer, in Solution Explorer, right-click the add-in module file and choose the View Designer popup menu item. The designer provides the add-in properties and a number of events including add-in events, application-level Outlook events, Ribbon control events, and Office 2010 and 2007 task pane related events. It is also a container for Add-in Express components that can be added to the module via the context menu of the designer.
In the Properties window for the add-in module designer, specify the name of your add-in, say My Outlook add-in.
Step 4. Adding a new Outlook Explorer command bar
To add a command bar to Outlook Explorer windows, use the Add Explorer CommandBar command that adds an ADXOlExplorerCommandBar to the add-in module (see also Adding components to the Add-in Module).
Select the Explorer command bar component, then, in the Properties window, specify the command bar name in the CommandBarName property and specify its position in the Position property. The Explorer command bar component provides context-sensitive properties. They are FolderName, FolderNames, and ItemTypes.
In the screenshot above, you see an Outlook Explorer command bar component that creates a custom toolbar to be shown for every Outlook folder (FolderName = "*") the default item type of which is Mail.
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 Command bar: toolbar, menu and context menu and How To sample for Outlook explorer toolbars.
Step 5. Adding a new button onto the Outlook toolbar
To add a new button to the Outlook Explorer command bar, select the Explorer command bar component and, in the Properties window, choose the Controls property, and click the property editor button. This starts the command bar visual designer. In its UI, you can add / move /d elete any command bar control (see also Command Bar controls).
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 (see the screenshot below).
Step 6. Customizing the Outlook 2010 and 2007 Ribbon User interface
To add a new tab to the Outlook Ribbon UI, 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 Ribbon tab component. In the visual designer, 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, Image, and ImageTransparentColor properties to set the icon for the button.
Step 7. Adding a new Outlook Inspector command bar
Remember, the Ribbon Tab visual designer validates the Ribbon XML automatically, so from time to time you will run into the situation when you cannot add a control to some Ribbon 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 2010 and 2007 Ribbon components.
To add a command bar to Outlook Inspector windows, 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. However, if ItemTypes is Unknown and you specify the full path to a folder(s) 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. For more details about adding a new button onto the Inspector toolbar see Step 5 - Adding a new button to the Outlook toolbar. See also HowTo for Outlook inspector toolbars.
Step 8. Customizing Outlook main menu
In Outlook 2003 two main menu types are available for Outlook windows: Explorer and Inspector. Accordingly, Add-in Express provides two main menu components: Explorer Main Menu component and Inspector Main Menu component. You use the context menu of your Outlook add-in module to add them. Then you use the visual designer provided for the Controls property of the component.
For example, 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 Outlook command bars and controls. The screenshot below shows the result of scanning. You need the Office IDs you see in the screenshot to bind Add-in Express controls to them:
The following screenshot shows the settings of the popup created at step 3 above:
When testing this sample, pay attention to the Caption property of the New popup: whatever value it has, it doesn't change the name of the New popup in Outlook. This is how Add-in Express connects to existing command bar controls.
Step 9. Customizing Outlook context menu
Use the ADXContextMenu component to customize a context menu of your Outlook add-in. You use this component exactly in the same way as you use the main menu components. Note that for Office main and context menus, the only available control types are button and popup.
The sample add-in described here 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.
Also, you can customize many Ribbon-based context menus in Outlook 2010. The Add ADXRibbonContextMenu command of the add-in module adds an ADXRibbonContextMenu component that allows specifying Ribbons that supply context menu names for the ContextMenuNames property. You use the ContextMenuNames property editor to choose the context menu(s) that will display your custom controls specified in the Controls property.
Step 10. Adding custom task panes in Outlook 2003 - 2010
First you add an Add-in Express Outlook Form to your project and then you add an Outlook Forms Manager component onto your Outlook add-in module. Finally, you add an item to the Items collection of the manager component and set the following properties of the item:
Find more about custom Outlook task panes.
Step 11. Accessing Outlook objects
To access Outlook objects, add the following method to the add-in module:
The code of the GetSubject method highlights the following:
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:
Step 12. 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:
The form added in Step 10. Adding a custom task pane in Outlook 2010 - 2003 also provides a number of Outlook events. Say, you can handle the ADXSelectionChange event as follows (requires adding a label onto the form):
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 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:
This requires adding the following declarations and code to the Add-in Module:
Step 14. 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:
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:
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:
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:
Finally, you add the following property to the AddinModule code:
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 15. 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.
To use keyboard shortcuts, you need to set the HandleShortcuts property of AddinModule to true.
Now you handle the Action event of the component:
See also how to create custom application-level keyboard shortcuts.
Step 16. 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.
Step 17. Debugging the Outlook add-in
To debug your add-in, just press F5 or select the Start Debugging item in the Debug menu of Visual Studio.
Step 18. Deploying your Outlook add-in
Build the setup project, transfer the files to the target PC and run the setup.exe. You can find another bit of useful information in Deploying Add-in Express based VSTO solutions.