Build add-in for MS Office Excel , Word, PowerPoint 2010 - 2000
in C++, C#, VB.NET: task panes, context menus, buttons

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

Add-in Express Home > Add-in Express for Office and .NET > Online Guide > Building Office COM add-in

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 2000-2003) and context menu, and a Ribbon button to the Ribbon UI of Office 2007-2010. Also, the add-in creates an advanced task pane supporting versions 2000-2010 of the host applications. The source code of the project - both VB.NET and C# versions - can be downloaded here; the download link is labeled Add-in Express for Office and .NET sample projects.

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 e-mails, 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 2000-2010. 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 e-mail when it is being sent; it can cancel saving an Excel workbook or it can check if a Word document 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 add-in project; your add-in is per-machine if the add-in module has ADXAddinModule.RegisterForAllUsers = True. Registering for all users means writing to HKLM and that means the user registering a per-machine add-in must have administrative permissions. Accordingly, RegisterForAllUsers = Flase means writing to HKCU (=for the current user). See Registry keys.

A standard user may turn a per-user add-in off and on in the COM Add-ins Dialog. You use that dialog to check if your add-in is active.

Step 1. Creating a COM add-in project

Make sure that you have administrative permissions before running Visual Studio. If you have Windows Vista, Windows 7, or Windows 2008, make sure that you run Visual Studio via Run as Administrator.

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 and specifying the oldest Office version your add-in needs to support.

Choosing a particular Office version will add corresponding interop assemblies to the project. Later on, in case you need to support an older or a newer Office version, you will be able to 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.

You can choose one or more Microsoft Office applications in the above window. For every chosen application, the project wizard will do the following:

• copy the corresponding interop assembly to the Interops folder of your project folder,
• add an assembly reference to the project
• add a COM add-in module to the project
• set up the SupportedApp property of the add-in module
• add a property to the add-in module; the property name reflects the name of the chosen Office application; you will use that property
• to access the object model of the Office application loading your add-in, see Step #6 - Accessing host application objects.

Select which Office applications will be supported by your add-in and click Next.

If you don't know anything about strong names or don't have a special strong name key file, choose Generate new. If you are in doubt, choose Generate new. If, later on, you need to use a specific strong name key file, you will be able to specify its name on the Signing tab of your project properties; you are required to unregister your add-in project before using another strong name.

Choose Generate new or specify an existing .snk file and click Next.

The project wizard creates and opens a new solution in the IDE.

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 add-in. You specify add-in properties in the module's properties, add the components to 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 comment line in the constructor of the module

The comment suggests that you write any initialization code in the AddinInitialize or AddinStratupComplete events of the add-in module, not in the constructor.

• the ExcelApp, WordApp, and PowerPointApp properties

These properties are added by the COM add-in project wizard. You use these properties as entry points to the object models of the corresponding Office applications; see Step #6 - Accessing host application objects.

• the CurrentInstace property

This property returns the current instance of the add-in module, a very useful thing when, for example, you need to access the add-in module from the code of 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 three areas:

• Add-in Express Toolbox - (#1 on the screenshot below) it contains commands; clicking a command adds a corresponding Add-in Express component onto the add-in module
• Add-in module designer - (#2 on the screenshot below) it is a usual designer
• In-place designer - (#3 on the screenshot below) if there's a visual designer for the currently selected Add-in Express component, then it is shown in this area

The areas are shown in the screenshot below:

Note that the module itself provides a number of properties. You can click its designer surface and see the Properties window where you set the name and description of your add-in as well as the RegisterForAllUsers property, which is essential for distinguishing per-user and per-machine COM add-ins.

To add any Add-in Express component onto the module, you click an appropriate command in the Add-in Express Toolbox (#1 in the screenshot above). Let's see how to use it.

Step 4. Adding a new toolbar

In the Add-in Express Toolbox, click the Add ADXCommandBar button.

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.

This adds a command bar component, of the ADXCommandBar type, onto the add-in module. Select the just added command bar component and, in the Properties window, specify the toolbar name in the CommandBarName property.

If the toolbar name is the same as the name of a built-in command bar of the host application, then the component will create the controls you specify on the built-in toolbar. Otherwise, the component will create a new toolbar at run-time. That is, if you set CommandBarName = "Standard", and add, say, an ADXCommandBarButton to the Controls collection of the ADXCommandBar component, this will create the button on the built-in Standard toolbar, while specifying CommandBarName = "Standard2" will create a new toolbar, Standard2, with the button on it. If the Standard2 toolbar already exists in the host application, the button will be added to that toolbar. Use our free Built-in Controls Scanner to get the names of all built-in command bars in any Office 2000-2010 application.

Step 5. Adding a new toolbar button

Select the command bar component on the designer of the add-in module and open the in-place designer area. In this area, you'll see the visual designer of the ADXCommandBar component. Use the visual designer to add a toolbar button onto the command bar component.

In the screenshot below, the toolbar button is already added:

Select the button and open the Properties window where you specify the button's Caption property, change the Style property to show an icon on the button (default value = adxMsoButtonCaption), and add an event handler to the Click event. Also, in the screenshot above, we demonstrate the button properties that make the icon visible and transparent: Image, ImageList, and ImageTransparentColor. Note that the Style property (not visible in the screenshot) is set to adxMsoButtonIconAndCaption in order to show the icon because command bar buttons do not show icons by default. See also Command Bar Control Properties and Events.

Step 6. Accessing host application 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 project wizard adds host-related properties to the module such as ExcelApp, WordApp, etc. You use these properties as entry points to the host applications object models. See how these properties are used in the code below:

   Private Sub DefaultAction(ByVal sender As System.Object) _
    Handles AdxCommandBarButton1.Click
    MsgBox(GetInfoString())
End Sub

Friend Function GetInfoString() As String
    Dim ActiveWindow As Object = Nothing
    Try
        ActiveWindow = Me.HostApplication.ActiveWindow() 'late binding
    Catch
    End Try
    Dim Result As String = "No document window found!"
    If Not ActiveWindow Is Nothing Then
        Select Case Me.HostType
            Case ADXOfficeHostApp.ohaExcel
                Dim ActiveCell As Excel.Range = _
                    CType(ActiveWindow, Excel.Window).ActiveCell
                If ActiveCell IsNot Nothing Then
                    'relative address
                    Dim Address As String = ActiveCell.AddressLocal(False, False)
                    Marshal.ReleaseComObject(ActiveCell)
                    Result = "The current cell is " + Address
                End If
            Case ADXOfficeHostApp.ohaWord
                Dim Selection As Word.Selection = _
                    CType(ActiveWindow, Word.Window).Selection
                Dim Range As Word.Range = Selection.Range
                Dim Words As Word.Words = Range.Words
                Dim WordCountString = Words.Count.ToString()
                Marshal.ReleaseComObject(Selection)
                Marshal.ReleaseComObject(Range)
                Marshal.ReleaseComObject(Words)
                Result = "There are " + WordCountString _
                    + " words currently selected"
            Case ADXOfficeHostApp.ohaPowerPoint
                Dim Selection As PowerPoint.Selection = _
                    CType(ActiveWindow, PowerPoint.DocumentWindow).Selection
                Dim SlideRange As PowerPoint.SlideRange = Selection.SlideRange
                Dim SlideCountString = SlideRange.Count.ToString()
                Marshal.ReleaseComObject(Selection)
                Marshal.ReleaseComObject(SlideRange)
                Result = "There are " + SlideCountString _
                    + " slides currently selected"
            Case Else
                Result = AddinName + " doesn't support " + HostName
        End Select
        Marshal.ReleaseComObject(ActiveWindow)
    End If
    Return Result
End Function
              
              

Two things in the code above deserve your attention. First, the GetInfoString method will be called from a number of events. If this code is run in Word and there is no open document, Me.HostApplication.ActiveWindow() will fire an exception. That is why this code line is wrapped in a try/catch block. Second, you have to release every COM object created in your code. See Releasing COM objects for more details.

Step 7. Customizing main menus

Add-in Express provides a component to customize the main menu of any Office application. Note that several Office applications from Office 2000-2003 have several main menus. Say, in these Excel versions, you find Worksheet Menu Bar and Chart Menu Bar. Naturally, in Excel 2007 and 2010 these menus are replaced with the Ribbon UI. Nevertheless, they 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 in Outlook 2000 - 2007.

In this sample, we are going to customize the File menu in Excel and Word, version 2000-2003. 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 main menu.

The screenshot below shows how you set up the main menu component in order to customize the Worksheet Menu Bar main menu in Excel 2000-2003.

Now you can open the in-place designer for the main menu component and populate it with controls. First off, you add a popup control 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 the built-in popup control having ID=30002, which is the ID of the File menu item in Office applications. To find this and similar IDs, use our free Built-in Control Scanner. See also Connecting to existing commandBar controls.

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. 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 added menu item (button) set Style = adxMsoButtonIconAndCaption.

Note that Office imposes restrictions on controls that can be added onto a main menu: the only control types available are command bar button and command bar popup.

See also Step 11. Customizing the Ribbon user interface for customizing the Office button menu in Office 2007 and the File tab in Office 2010.

Step 8. Customizing context menus

Add-in Express allows customizing commandbar-based context menus in Office 2000-2010 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:

• Add a context menu component to the add-in module
• Specify the host application, a context menu of which you need to customize
• Specify the context menu to customize
• Use the in-place designer to add custom controls to the Controls collection of the component

There are several issues related to using command bar based context menus:

• Excel contains two different context menus named Cell. This fact breaks down the command bar development model because the only way to recognize two command bars is to compare their names. This isn't the only exception: use our Built-in Control Scanner to find a number of examples. In this case, the context menu component cannot distinguish context menus. Accordingly, it connects to the first context menu of the name specified by you.
• Command bar based context menu items cannot be positioned in the Ribbon-based context menus: a custom context menu item created with the ADXContextMenu component will always be shown below the built-in and custom context menu items in a Ribbon-based context menu of Office 2010.

To add a custom item to a context menu in Office 2010, 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.

See also Step 11. Customizing the Ribbon User interface.

Step 9. Handling host application events

The add-in module designer provides the Add Events command that adds (and removes) 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:

   Private Sub Deactivate(ByVal sender As Object, _
      ByVal hostObj As Object, ByVal window As Object) _
      Handles adxWordEvents.WindowDeactivate, _
          adxExcelEvents.WindowDeactivate, _
          adxPowerPointEvents.WindowActivate
      Me.AdxCommandBarButton1.Enabled = False
   End Sub

   Private Sub Activate(ByVal sender As Object, ByVal hostObj As Object, _
      ByVal window As Object) _
      Handles adxWordEvents.WindowActivate, _
          adxExcelEvents.WindowActivate, _
          adxPowerPointEvents.WindowDeactivate
      Me.AdxCommandBarButton1.Enabled = True
   End Sub

Step 10. Handling Excel worksheet events

Add-in Express provides the Excel Worksheet Events Class item available in the Add New Item dialog in Visual Studio. It allows implementing a set of business rules for an Excel worksheet by handling its events

This adds an event class to your project.

In the event class, you add the following code to the procedure that handles the BeforeRightClick event of the Worksheet class:

   Public Overrides Sub ProcessBeforeRightClick(ByVal Target As Object, _
         ByVal E As AddinExpress.MSO.ADXCancelEventArgs)
      Dim R As Excel.Range = CType(Target, Excel.Range)
      'Cancel right-clicks for the first column only
      If R.Address(False, False).IndexOf("A") = 0 Then
         MsgBox("Context menu will not be shown!")
         E.Cancel = True
      Else
         E.Cancel = False
      End If
   End Sub

In addition, you modify the Activate and Deactivate procedures as follows:

   Dim MyEventClass As ExcelWorksheetEventsClass1 = _
       New ExcelWorksheetEventsClass1(Me)
...
Private Sub Deactivate(ByVal sender As Object, ByVal hostObj As Object, _
   ByVal window As Object) _
   Handles adxWordEvents.WindowDeactivate, adxExcelEvents.WindowDeactivate
   Me.AdxCommandBarButton1.Enabled = False
   Select Case Me.HostName
      Case "Excel"
         If MyEventClass.IsConnected Then MyEventClass.RemoveConnection()
      Case "Word"
      Case "PowerPoint"
      Case Else
         MsgBox(Me.AddinName + " doesn't support " + Me.HostName)
   End Select
End Sub

Private Sub Activate(ByVal sender As Object, ByVal hostObj As Object, _
   ByVal window As Object) _
   Handles adxWordEvents.WindowActivate, adxExcelEvents.WindowActivate
   Me.AdxCommandBarButton1.Enabled = True
   Select Case Me.HostName
      Case "Excel"
         If MyEventClass.IsConnected Then MyEventClass.RemoveConnection()
         MyEventClass.ConnectTo(Me.ExcelApp.ActiveSheet, True)
      Case "Word"
      Case "PowerPoint"
      Case Else
         MsgBox(Me.AddinName + " doesn't support " + Me.HostName)
   End Select
End Sub

Step 11. Customizing the Ribbon User interface

To add a new tab to the Ribbon, you use the Add Ribbon Tab command on the Add-in Express Toolbox; it adds an ADXRibbonTab component to the module. In the in-place visual designer, use toolbar buttons or context menu to add or delete Add-in Express components that form the Ribbon interface of your add-in

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 ImageList and Image properties to set the image for the button.

Now add the event handler to the Click event of the button. Write the following code:

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

Remember, the Ribbon Tab designer validates the XML-markup 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.

In the code of this sample add-in, 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 add-in 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. Adding advanced task panes in Excel 2000-2010

Creating a new Excel task pane includes the following steps:

• Use the Add-in Express Toolbox to add an Excel Task Panes Manager, ADXExcelTaskPanesManager, onto the add-in module.





• Open the Add New Item dialog in Visual Studio to add an Add-in Express Excel Task Pane, ADXExcelTaskPane, to the project.
• Select the Excel Task Panes Manager component, add an item to its Items collection, choose the pane just added in the TaskPaneClassName property of the item and set other properties, such as Position (see the screenshot below).

The properties shown on the screenshot above are:

• AlwaysShowHeader - specifies that the pane header will be shown even if the pane is the only pane in the current region.
• CloseButton - specifies if the Close button will be shown in the pane header. Obviously, there's not much sense in setting this property to true when the header isn't shown.
• Position - specifies the region in which an instance of the pane will be shown. Excel panes are allowed in four regions docked to the four sides of the main Excel window: Right, Bottom, Left, and Top. The fifth region is Unknown.
• TaskPaneClassName - specifies the class name of the Excel task pane.

Now you add a label onto the form and change its caption in the following code:

Private Sub RefreshTaskPane()
    Private Sub RefreshTaskPane()
    Select Case Me.HostName
        Case "Excel"
            Dim Pane As ADXExcelTaskPane1 = _
                TryCast(Me.AdxExcelTaskPanesCollectionItem1.TaskPaneInstance, _
                    ADXExcelTaskPane1)
            If Pane IsNot Nothing Then
                Pane.Label1.Text = Me.GetInfoString()
            End If
        Case "Word"
        Case "PowerPoint"
        Case Else
            'System.Windows.Forms.MessageBox.Show("Invalid host application!")
    End Select
End Sub

See also Advanced Custom Task Panes

Step 13. Adding advanced task panes in PowerPoint 2000-2010

Now you add a PowerPoint task pane:

• Use the Add-in Express Toolbox to add a PowerPoint Task Panes Manager, ADXPowerPointTaskPanesManager, onto the add-in module.





• Open the Add New Item dialog in Visual Studio to add an Add-in Express PowerPoint Task Pane, ADXPowerPointTaskPane, to the project.
• Select the PowerPoint Task Panes Manager component, add an item to its Items collection, bind the pane to the item and specify an appropriate value in the Position.

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:

Private Sub RefreshTaskPane()
    Select Case Me.HostName
        Case "Excel"
...
        Case "Word"
        Case "PowerPoint"
            Dim Pane As ADXPowerPointTaskPane1 = _
                TryCast( _
                    Me.AdxPowerPointTaskPanesCollectionItem1.TaskPaneInstance, _
                    ADXPowerPointTaskPane1)
            If Pane IsNot Nothing Then
                Pane.Label1.Text = Me.GetInfoString()
            End If
        Case Else
            'System.Windows.Forms.MessageBox.Show("Invalid host application!")
    End Select
End Sub

Step 14. Adding advanced task panes in Word 2000-2010

You add a Word task pane in the same manner:

• Use the Add-in Express Toolbox to add an ADXWordTaskPanesManager, Word Task Panes Manager, onto your add-in module.





• Open the Add New Item dialog in Visual Studio to add an Add-in Express Word Task Pane (ADXWordTaskPane) to the project.
• Select the Word Task Panes Manager component, add an item to its Items collection, bind the pane to the item and specify an appropriate value in the Position.

Now add a label onto the form and update RefreshTaskPane in order to set the label:

Private Sub RefreshTaskPane()
    Select Case Me.HostName
        Case "Excel"
...
        Case "Word"
            Dim Pane As ADXWordTaskPane1 = _
                TryCast( _
                    Me.AdxWordTaskPanesCollectionItem1.CurrentTaskPaneInstance, _
                    ADXWordTaskPane1)
            If Pane IsNot Nothing Then
                Pane.Label1.Text = Me.GetInfoString()
            End If
        Case "PowerPoint"
...
        Case Else
            'System.Windows.Forms.MessageBox.Show("Invalid host application!")
    End Select
End Sub

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 (if you use the Express edition of Visual Studio, this item can be found in the context menu of the add-in module's designer surface), and restart the host applications.

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 COM add-ins. Find background information in Deploying Office extensions.

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.

Back to Add-in Express for Office and .NET homepage