Build COM add-in for Word, PowerPoint, Excel 2016, 2013, 2010
in C#, VB.NET: ribbon, menu, task pane
Building Office COM add-ins
The sample project below demonstrates how you create a COM add-in supporting several Office applications (Excel, Word and PowerPoint). The add-in creates a custom toolbar and adds a CommandBar button to the toolbar, main menu (in Office 2003 - 2000) and context menu, and a Ribbon button to the Ribbon UI of Microsoft Office 2007, 2010, 2013 and Office 2016. Also, the add-in creates an advanced task pane supporting versions 2016 - 2010 of the host applications. You can download the source code of the project as well as plenty more samples on the How-To pages: VB.NET examples for Office and C# examples for Excel.
A bit of theory
COM add-ins have been around since Office 2000 when Microsoft allowed Office applications to extend their features with COM DLLs supporting the IDTExtensibility2 interface (it is a COM interface, of course). COM add-ins is the only way to add new or re-use built-in UI elements such as command bar controls and Ribbon controls. Say, a COM add-in can show a command bar or Ribbon button to process selected Outlook emails, Excel cells, or paragraphs in a Word document and perform some actions on the selected objects. A COM add-in supporting Outlook, Excel, Word or PowerPoint can show advanced task panes in Office 2016, 2013, 2010, 2007, 2003 and lower. In a COM add-in targeting Outlook, you can add custom option pages to the Tools | Options and Folder Properties dialogs. A COM add-in also handles events and calls properties and methods provided by the object model of the host application. For instance, a COM add-in can modify an email when it is being sent; it can cancel saving an Excel workbook or it can check if a Word document or selected text meets some conditions.
Per-user and per-machine COM add-ins
A COM add-in can be registered either for the current user (the user running the installer) or for all users on the machine. Add-in Express generates a per-user project; your add-in is per-machine if the addin module has ADXAddinModule.RegisterForAllUsers = True. Registering for all users means creating registry entries in HKLM and that means the user registering a per-machine plug-in must have administrative permissions. Accordingly, RegisterForAllUsers = False means writing to HKCU (=for the current user). See Registry keys.
Before you modify the RegisterForAllUsers property, you must unregister the add-in project on your development PC and make sure that adxloader.dll.manifest is writable.
A standard user may turn a per-user addin off and on in the COM Add-ins dialog. You use that dialog to check if your plugin is active.
Step 1. Creating a COM add-in project
Make sure that you have administrative permissions before running Visual Studio. Run Visual Studio via the Run as Administrator command.
In Visual Studio, open the New Project dialog and navigate to the Extensibility folder.
Choose Add-in Express COM Add-in and click OK. This starts the COM Add-in project wizard. The wizard allows choosing your programming language (C#, VB.NET or C++) and specifying the oldest Office version your plugin needs to support. We are going to choose VB.NET and Office 2010.
Choosing a particular Office version will add corresponding interop assemblies to the project. Later on you can replace interop assemblies and reference them in your project. If you are in doubt, choose Microsoft Office 2000 as the minimum supported Office version. If you need background information, see Choosing interop assemblies.
Choose your programming language and the minimum Office version that you want to support and click Next.
The wizard allows creating add-in projects targeting several Office applications. Since we want our plugin to work in Microsoft Word, Excel and PowerPoint, we are selecting these three apps.
You can choose one or more Microsoft Office applications in the above window. For every chosen application, the project wizard will do the following:
Select the Office applications you want to support by your add-in and click Next. The wizard allows specifying a strong name file; it is used to uniquely identify your add-in assembly.
If you don't have a specific strong name key file, choose Generate new. If you are in doubt, choose Generate new. If, later on, you need to use a strong name key file, specify its name on the Signing tab of your project properties; you are required to unregister your project before using another strong name.
Choose Generate new or specify an existing .snk file and click Finish.
The project wizard creates and opens a new solution in Visual Studio.
The solution contains an only project, the COM add-in project. The project contains the AddinModule.vb file (for VB.NET projects) or AddinModule.cs (for C# projects) discussed in the next step.
Step 2. Add-in module
AddinModule.vb (or AddinModule1.cs) is the core part of the add-in project. It is a container for components essential for the functionality of your plugin. You configure the addin's settings in the module's properties, put components onto the module's designer, and write the functional code of your add-in in this module. To review its source code, in the Solution Explorer, right-click the AddinModule1.vb (or AddinModule1.cs) file and choose View Code in the popup menu.
In the code of the module, pay attention to three points:
The text suggests that you write initialization code in the AddinInitialize or AddinStartupComplete events of the add-in module, not in the constructor. This is important because an instance of the module is created (this runs the constructor) when your plug-in is being registered and unregistered. When the module is created for this purpose, no Office objects, properties, methods or events are available. If your code is not prepared for this, the installer of your add-in will fail.
Moving custom initialization code out of the module's constructor allows preventing installation failures.
You use these properties – they are generated by the COM add-in project wizard – as entry points to the object models of the corresponding Office applications; see Step #6 - Accessing host application objects.
This property returns the current instance of the add-in module, a very useful thing if you need to access the add-in module from e.g. a task pane.
Step 3. Add-in module designer
The designer of the add-in module allows setting add-in properties and adding components to the module.
In Solution Explorer, right-click the AddinModule.vb (or AddinModule.cs) file and choose View Designer in the popup menu.
The add-in module designer view provides access to the following four areas shown in the screenshot below:
To put any Add-in Express component onto the module, you click an appropriate command in the Add-in Express Toolbox (#1 in the screenshot above). Then you select the newly created component and set it up using the visual designer (#3 in the screenshot above) and Properties window.
Note that the add-in module provides a number of properties. Click the designer surface and specify the name and description of your add-on in the Properties window. Also, pay attention to the RegisterForAllUsers property - it is essential for distinguishing per-user and per-machine COM add-ins; you must unregister the add-in project before modifying this property.
Step 4. Creating a new Office toolbar
In the Add-in Express Toolbox, click the Add ADXCommandBar button. This places a new ADXCommandBar component onto the add-in module. Select the ADXCommandBar just created and specify the toolbar name in the CommandBarName property (see in the Properties window).
You may use both Command Bar UI and Ribbon UI components on the add-in module. When your add-in is loaded in a particular version of the host application, either command bar or ribbon controls will show up. Find additional information in Command Bars in the Ribbon UI.
ADXCommandBar creates controls on the toolbar the name of which you specify in the CommandBarName property. If the specified toolbar is missing on the host application, ADXCommandBar creates it. That is, if you place some Add-in Express CommandBar control components onto the ADXCommandBar the CommandBarName property of which is set to "Standard", this will create the controls on the built-in Standard toolbar, while specifying CommandBarName = "Standard2" will create a new toolbar, Standard2, with the controls on it. If the Standard2 toolbar exists in the host application, the buttons will be added to that toolbar. You can use our free Built-in Controls Scanner to get the names of all built-in command bars in any Office 2013 - 2000 application.
Select the command bar component on the designer of the add-in module and expand the in-place designer area. In this area, you'll see the visual designer of the ADXCommandBar component. Use the visual designer to put a toolbar button onto the command bar component.
To achieve the result shown in the screenshot above, select the new button and open the Properties window where you specify the button's Caption property and add an event handler to the Click event. Also, in the screenshot above, we demonstrate the properties that make the icon visible and transparent: Image, ImageList, and ImageTransparentColor. Please pay attention: to get the icon displayed, the Style property (it isn't visible in the screenshot) is set to adxMsoButtonIconAndCaption. This is because command bar buttons do not show icons by default. To get the icon transparent, the value of the ImageTransparentColor property is chosen in accordance with the bitmap used. See also Command bar control properties and events.
The add-in module provides the HostApplication property that returns the Application object (of the Object type) of the host application the plug-in is currently running in. The project wizard adds properties such as ExcelApp, WordApp, etc. to the module; the properties just cast HostApplication to the appropriate type. You use these properties as entry points to the corresponding object models:
Two things in the code above deserve your attention. First, Me.HostApplication.ActiveWindow() is wrapped in a try/catch block: this prevents a notorious exception which occurs when you call ActiveWindow() on the Word.Application object and there are no documents opened in Word. Second, you have to release every COM object created in your code, see Releasing COM objects for more details.
Step 7. Customizing Office main menu
Add-in Express provides a component to customize the main menu of a pre-Ribbon Office application. Note that some Office applications from Office 2003, XP and 2000 have several main menus. Say, in these Excel versions, you find Worksheet Menu Bar and Chart Menu Bar. Naturally, starting from Excel 2007, these menus are replaced with the Ribbon UI. Nevertheless, the CommandBar objects representing the main menus are still accessible programmatically and you may want to use this fact in your code. As for customizing main menus in Outlook, see Step 8. Customizing main menu of Outlook 2007 - 2000.
In this sample, we are going to customize the File menu in Excel and Word, version 2003-2000. You start with adding two main menu components and specifying correct host applications in their SupportedApp properties. Then, in the CommandBarName property, you specify the name of the main menu to be customized.
The screenshot below shows how you set up the main menu component in order to customize the Worksheet Menu Bar main menu in Excel 2003-2000.
Now you can open the in-place designer for the main menu component and populate it with controls.
In the screenshot above, you see the ADXMainMenu component and its visual designer. You use the visual designer to populate the ADXMainMenu with controls. Note that only command bar buttons and command bar popups can be added onto a main menu.
To add a custom control to the File menu, you add a popup control to the ADXMainMenu component and set its Id property to 30002. Specifying anything but 1 in this property means that controls added to that ADXCommandBarPopup component, will be created on a built-in popup with the corresponding ID. And 30002 is the ID of the File menu item in pre-Ribbon Office applications.
Then you add a button and set their properties in the way described in Step 5. Adding a new toolbar button.
Pay attention to the BeforeID property of the button component. To place the button before the New button, you set this property to 3, which is the ID of the button New. Please remember that showing an image for any command bar control requires choosing a correct value for the Style property of the button. For the newly created menu item (button) set Style = adxMsoButtonIconAndCaption.
See also Step 11. Customizing the Ribbon user interface for customizing the Office button menu in Office 2007 and the File tab (Backstage View) in Office 2010 - 2016.
Add-in Express allows customizing commandbar-based context menus with the ADXContextMenu component. Its use is similar to that of the ADXMainMenu component. See how to set up such a component to add a custom button to the Cell context menu in Excel:
There are several issues related to using command bar based context menus:
To add a custom item to a ribbon-based context menu, you use the ADXRibbonContextMenu component.
Unlike its commandbar-based counterpart (ADXContextMenu), this component allows adding custom Ribbon controls to several context menus in the specified Ribbons. The screenshots below demonstrate component settings required for adding a control to the ExcelWorkbook Ribbon. To specify the context menus, to which the control will be added, you use the editor of the ContexMenuNames property of the component.
Step 9. Handling host application events
The add-in module designer provides the Add Events command that creates (and deletes) event components that allow handling application-level events (see Application-level events).
With the event components, you handle any application-level events of the host application. Say, you may want to disable the button when a window deactivates and enable it when a window activates. The code is as follows:
Add-in Express provides the Excel Worksheet Events Class item in the Add New Item dialog in Visual Studio. A descendant of this class allows connecting to an Excel.Worksheet object and handling its events. You can use it for creating a set(s) of business rules for handling specific Excel worksheets.
Selecting the Excel Worksheet Events Class item and clicking OK adds an event class to your project.
In the event class, add the following code to the procedure that handles the BeforeRightClick event of the Worksheet class:
In addition, you modify the Activate and Deactivate procedures as follows:
To add a new tab to the Ribbon, you use the Add Ribbon Tab command on the Add-in Express Toolbox; it places a new ADXRibbonTab component onto the module. Select the component and, in the in-place designer, use toolbar buttons or context menu to add or delete components that create the Ribbon interface of your addin.
In this sample, you change the caption of your tab to My Ribbon Tab. Then, you add a Ribbon group, and change its caption to My Ribbon Group. Finally, you select the group, add a button and set its caption to My Ribbon Button. Use the Glyph property to set the image for the button.
Now add an event handler to the Click event of the button and write the following code:
The sample project described here creates a custom Ribbon tab. You can also customize a built-in Ribbon tab, please check Referring to built-in ribbon controls.
In the code of this sample plugin, you can find how you can customize the Office Button menu in Office 2007, see component named AdxRibbonOfficeMenu1. As to the Backstage View, also known as the File Tab in Office 2010, the sample project provides the AdxBackstageView1 component that implements the customization shown in Figure 3 at Introduction to the Office 2010 Backstage View for developers. Note, if you customize the Office Button menu only, Add-in Express maps your controls to the Backstage View when the plugin is loaded by Office 2010. If, however, both Office Button menu and File tab are customized at the same time, Add-in Express ignores custom controls you add to the Office Button menu. See also Ribbon UI components.
Step 12. Creating advanced task panes in Excel 2016 - 2000
Creating a new Excel task pane includes the following steps:
Select the newly created item and, in the Properties window, specify properties as follows:
Now you add a label onto the form and change its caption in the following code:
See also Advanced custom task panes
Now you create a PowerPoint task pane:
Select the newly created item and, in the Properties window, specify properties as follows:
Now add a label onto the form, write a property that reads and updates the label, and update RefreshTaskPane in order to set the property value:
You create a Word task pane in the same manner:
Now add a label onto the form and update RefreshTaskPane in order to set the label:
The different names of the properties returning instances of the three pane types reflect the difference in Excel, PowerPoint and Word windowing; while Excel and PowerPoint show their documents in just one main window, Word normally shows documents in multiple windows. In this situation, the Word Task Panes Manager creates one instance of the pane for every document open in Word. Therefore, you need to handle the task pane instance, which is currently active. For that reason, the property name is CurrentTaskPaneInstance.
Step 15. Running the COM Add-in
Choose Register Add-in Express Project in the Build menu. Alternatively, you can choose Add-in Express | Register in the context menu of the add-in project. See also If you use an Express edition of Visual Studio.
Start the host application(s) and check if the add-in works. If the add-in isn't visible in the host application's UI, see Troubleshooting add-in loading.
The newly created COM add-in in Microsoft Word 2016:
The COM add-in in Microsoft Excel 2016:
The COM add-in in Microsoft PowerPoint 2016:
You can also find your add-in in the COM Add-ins dialog.
Step 16. Debugging the COM add-in
To debug your add-in, in the Project Options window, specify the path to the host application of the add-in in Start External Program and run the project.
Step 17. Deploying the COM add-in
The table below provides links to step-by-step instructions for deploying Office add-ins. Find background information in Deploying Office extensions.
Table 1. Deploying COM add-ins: links to step-by-step instructions
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: