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

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

Building Office COM add-ins

This page describes the general principles that Add-in Express .NET is based on. Here you fill find a step-by-step example of building a COM add-in for Excel, Word, or other applications from the Microsoft Office 2000 - 2007 suites .

On other pages you will find some tips and tricks about:

• Building Office add-in
• Customizing Office 2007 ribbons
• Creating command bars and their controls
• Deploying and debugging your add-in 

Please keep in mind, Add-in Express provides special components for developing Outlook plug-ins, toolbars and menus. For more information please see a sample Outlook plug-in.

Example of building an Office COM add-in

The sample add-in below for Microsoft Excel and Word is written in VB.NET, but you can use Add-in Express .NET to develop an Office add-in in Visual C#, Visual C++ and RO Chrome as well. You may also want to find more about special features provided by Add-in Express for creating an advanced Excel GUI.

COM development in Visual Studio .NET is not a visual process. But Add-in Express cures this and makes add-in development easier. How can this be achieved? With ease. Let's go!

Step 1. Create a new add-in project

Add-in Express adds the Add-in Express COM Add-in project template to the Visual Studio IDE.

When you select the template and click OK, the Add-in Express COM Add-in project wizard starts. In the wizard windows, you choose the programming language (in our project it is Visual Basic), setup project options, and supported applications of your add-in .

 
This VB.NET sample shows an Add-in Express COM Add-in project implementing a COM add-in for Excel and Word with the Add-in Express Loader as a shim. To understand shims and the Add-in Express Loader, see Deploying Add-in Express projects.

Your add-ins are version-neutral

Add-in Express delivers version-neutral Office Interop assemblies that allow developing extensions for Office 2000 - 2007. To use them, just check the Use Version-neutral Interop Assemblies check box when creating your projects. See also Version-neutral interop assemblies.

 
The Add-in Express Project wizard builds and opens the COM add-in solution in Visual Studio. The solution includes the COM Add-in project and the setup project.

 
The COM Add-in project contains the AddinModule.vb (or AddinModule1.cs) file described in Step 2.

Step 2. Add-in Express COM Add-in module

The AddinModule.vb (or AddinModule1.cs) is a COM Add-in module that is the core part of the COM add-in project (see COM add-ins). It is a container for the Add-in Express components components essential for the functionality of your add-in. You specify the add-in properties in the module's properties, add the Add-in Express 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 window, right-click the AddinModule1.vb (or AddinModule1.cs) file and choose the View Code popup menu item.

 
The code for AddinModule1.vb is as follows:

Imports System.Runtime.InteropServices
Imports System.ComponentModel


'Add-in Express Add-in Module
<GuidAttribute("AB07BADE-56F7-414B-ACA0-D3E2DDAABCCB"), _
       ProgIdAttribute("MyAddin1.AddinModule")> _
Public Class AddinModule
    Inherits AddinExpress.MSO.ADXAddinModule
 
#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()
      Me.components = New System.ComponentModel.Container
      '
      'AddinModule
      '
      Me.AddinName = "MyAddin1"
      Me.SupportedApps = CType((AddinExpress.MSO.ADXOfficeHostApp.ohaExcel _
             Or AddinExpress.MSO.ADXOfficeHostApp.ohaWord), _
             AddinExpress.MSO.ADXOfficeHostApp)
   End Sub
#End Region
 
#Region " Add-in Express 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
 
    <ComRegisterFunctionAttribute()> _
    Public Shared Sub AddinRegister(ByVal t As Type)
        AddinExpress.MSO.ADXAddinModule.ADXRegister(t)
    End Sub
 
    <ComUnregisterFunctionAttribute()> _
    Public Shared Sub AddinUnregister(ByVal t As Type)
        AddinExpress.MSO.ADXAddinModule.ADXUnregister(t)
    End Sub
 
    Public Overrides Sub UninstallControls()
        MyBase.UninstallControls()
    End Sub
 
#End Region
 
    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 ExcelApp() As Excel._Application
        Get
            Return CType(HostApplication, Excel._Application)
        End Get
    End Property


    Public ReadOnly Property WordApp() As Word._Application
        Get
            Return CType(HostApplication, Word._Application)
        End Get
    End Property

Please, pay attention to the ExcelApp and WordApp properties of the module generated by the Add-in Express Project Wizard. You can use them in your code to get access to the host application objects.

Step 3. Add-in Express COM Add-in designer

The Add-in Express COM Add-in designer allows setting add-in properties and adding components to the module. In the Solution Explorer window, right-click the AddinModule.vb (or AddinModule.cs) file and choose the View Designer popup menu item. 

In the Properties window, you set the name and description of your add-in module.

 
To add an Add-in Express component to the module, you use an appropriate command in the Properties window, or you can right-click the designer surface and choose the same command in the context menu.

 
The following commands add the following components to the module:

• Add CommandBar – adds a command bar to your add-in.
• Add Explorer CommandBar – adds an Outlook Explorer command bar to your add-in (see Command bars).
• Add Inspector CommandBar – adds an Outlook Inspector command bar to your add-in.
• Add Built-in Control Connector – adds a component that allows intercepting the action of a built-in control of the host application(s) (see Built-in Control Connector).
• Add Keyboard Shortcut– adds a component that allows intercepting application-level keyboard shortcuts (see Keyboard shortcuts).
• Add Outlook Bar Shortcut Manager – adds a component that allows adding Outlook Bar shortcuts and shortcut groups (see Outlook Bar Shortcut Manager).
• Add Outlook Forms Manager – adds a component that allows embedding custom .NET forms into Outlook windows (see Outlook Forms Manager).
• Add Ribbon Tab – adds a Ribbon tab to your add-in (see Office 2007 Ribbon components).
• Add Ribbon Quick Access Toolbar – adds a component that allows customizing the Ribbon Quick Access Toolbar in your add-in.
• Add Ribbon Office Menu – adds a component that allows customizing the Ribbon Office Menu in your add-in.
• Add Events – adds or deletes components that provide access to application-level events of the add-in host applications.

Step 4. Adding a new command bar

To add a command bar to your add-in, use the Add CommandBar command that adds an ADXCommandBar component to the COM Add-in module (see Command bars: toolbar, menu, context menu).

 
Select the command bar component and, in the Properties window, specify the command bar name using the CommandBarName property. In addition, you select its position in the Position property.

Command bars in Office 2007

To display the command bar in Office 2007 you must explicitly set the UseForRibbon property of the command bar component to True.

Step 5. Adding a new command bar button

To add a new button to the command bar, in the Properties window, you select the Controls property of an appropriate command bar component and click the property editor button (the button in the property value field).

This runs the visual designer. Use its toolbar to add or remove Command bar controls. Just click the appropriate button and see the result.

In this sample, we add a button. When it is added, select it in the tree. Then specify the button's Caption property, change the Style property if you need to show an icon in the button (default value = adxMsoButtonCaption), and close the collection editor. To handle the Click event of the button, close the editor, select the newly added button in the topmost combo of the Properties window and add the Click event handler: The code of the event handler follows below (it's empty as you can see).

    Private Sub AdxCommandBarButton1_Click(ByVal sender As System.Object) _
           Handles AdxCommandBarButton1.Click
    
    End Sub

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 Add-in module. You use these properties to access host application objects. For instance, we write the following code to the Click event of the button just added. 

    Public ReadOnly Property ExcelApp() As Excel._Application
        Get
            Return CType(HostApplication, Excel._Application)
        End Get
    End Property

    Public ReadOnly Property WordApp() As Word._Application
        Get
            Return CType(HostApplication, Word._Application)
        End Get
    End Property

The _Application object provides the same properties and methods as the Application object but it doesn't provide events. This allows us to 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
      If Me.HostName = "Excel" Then
         MsgBox("The current cell is " + _
            Me.ExcelApp.ActiveCell.AddressLocal(False, False)) 'relative
      ElseIf Me.HostName = "Word" Then
         MsgBox("There are " + _
            Me.WordApp.Selection.Range.Words.Count.ToString() + _
               " words currently selected")
      Else
         MsgBox(Me.AddinName + " doesn't support " + Me.HostName)
      End If
   End Sub

Step 7. Customizing main menu

Add-in Express provides a component to customize the main menu of any Office application. Please note that some Office applications have several main menus. Excel is a good example: Excel 2000 -2003 provide two main menus named Worksheet Menu Bar and Chart Menu Bar. Naturally, Excel 2007 doesn't show these menus because they are replaced with the Ribbon UI. Nevertheless, these menus still exist and you may want to use this fact in your code. Also note that the customization of Outlook menus is highlighted on the developing and Outlook COM add-in page.

To customize several main menus, you add an appropriate number of main menu components to the add-in module using its context menu. Then you set the components to make each responsible for handling a single main menu.

To customize the File menu in Excel and Word, add two main menu components and set their SupportedApp property to specify correct host applications. Then, in the CommandBarName property, you specify the main menu. For instance, this is how you set up the main menu component in order to customize the Worksheet Menu Bar main menu in Excel:

Now you can use the Controls property to add custom and built-in controls to the main menu. Please note, however, that Office imposes restrictions on the control types available for the developer when customizing the main menu. The only control types are command bar button and command bar popup.

The screenshot above shows how to add a custom button to the File menu of Excel. First off, we add a popup controls and specify its Id property: in this case, it is 30002, which is the ID of the File menu in Office applications. To find this and similar IDs, use our free Built-in control Scanner. See also Connecting to existing command bar 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 show the button before the New button, we set this property to 3, which is the ID of the New button. Also, remember that showing an image for the button (or any command bar control) requires choosing a correct value for the Style property of the button.

Step 8. Customizing context menu

A context menu is a specific command bar that can be customized too. Add-in Express allows customizing context menus via the Context Menu component. Its use is similar to that of the Main Menu component:

• Add a context menu component to the add-in module
• Specify the host application, the context menu of which you need to customize
• Specify the context menu to customize
• Add custom controls to the Controls collection
• The screenshot below shows how to set up such a component to add a custom button to the Cell menu of Excel:

Now, using the visual designer of the Controls collection, you can add buttons and pop-ups to the context menu. Note that, in the context menu, a popup is shown as a drop-down item.
You may want to use the BeforeAddControls event provided by the component to modify the context menu depending on the current context. Say the context menu may reflect the Excel cell content, the current chapter of the Word document, etc.

One more note. 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: see the Built-in Control Scanner to find a number of examples. In this case, the component cannot distinguish context menus. Accordingly, it connects to the first context menu of the name specified by you.

Step 9. Handling host application events

The COM Add-in designer provides the Add Events command that adds (and remove) event components that allow handling Application-level events. When you choose this command, the Add Application Events dialog box opens allowing you to select the application Events components you need.

This adds Excel and Word Events components to the COM Add-in module.

With the Events components, you handle any application-level events of Excel, Word and other Office host applications. You might see that the Click event handler in the previous step will fire an exception when there are no workbooks or documents open. To prevent this, you disable the button when a window deactivates and enable it when a window activates. This covers the situations mentioned above.

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
      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
      Me.AdxCommandBarButton1.Enabled = True
   End Sub

Step 10. Handling Excel Worksheet events

Add-in Express provides the Excel Worksheet event class that allows implementing a set of business rules for an Excel worksheet by handling its events. You add an event class to your project using the Add New Item dialog:

 
This will add 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

Also, you modify the Activate and Deactivate procedures as follows:

   Dim MyEventClass As ExcelWorksheetEventsClass1 = _
          New ExcelWorksheetEventsClass1(Me)
   Dim Sheet As Excel.Worksheet
...
   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 Sheet IsNot Nothing Then
               MyEventClass.RemoveConnection()
               Sheet = Nothing
            End If
         Case "Word"
         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"
            Sheet = Me.ExcelApp.ActiveSheet
            MyEventClass.ConnectTo(Sheet, True)
         Case "Word"
         Case Else
            MsgBox(Me.AddinName + " doesn't support " + Me.HostName)
      End Select
   End Sub

Step 11. Customizing the Office 2007 Ribbon user interface

To add a new tab to the Ribbon, 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 tab. In the Ribbon Tab 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 and Image properties to set the icon for the button.

 
Click OK, and, in the Properties window, find the newly added Ribbon 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 ADXRibbonTab Controls editor performs the XML-schema validation 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. See also Office 2007 Ribbon components and Office 2007 Ribbon visual designer.

Step 12. Adding a custom task pane in Office 2007

If you need to create a custom task pane for Excel 2000-2003, see another sample Excel task pane project.

To add a new task pane, you add a UserControl to your project and flourish it up with your controls. Then you add an item to the TaskPanes collection of the Add-in Module and specify its properties:

• Caption – the caption of your task pane
• DockPosition – you can dock your task pane to the left, top, right, or bottom edges of the host application window
• ControlProgID – the UserControl just added

The sample Excel add-in described on this page has the following task pane settings:

 
You should understand the difference between the task pane component and task pane instances. The TaskPanes collection of the add-in module contains task pane components. When you set, say, the height or dock position of the component, these properties apply to every task pane instance that the host application shows. To modify the height of a task pane instance, you should get the instance itself. This can be done through the Item property of the component (in C# this property is the indexer for the ADXTaskPane class). The property accepts the parameter, which is the host application's window object that displays the task pane. For instance, the following private methods in the samples' add-in module find the currently active instance of the task pane and refresh it. For the task pane to be refreshed in a consistent manner, these methods are called in appropriate event handlers.

Imports AddinExpress.MSO
...
   Private Sub RefreshTaskPane()
      If Version = "12.0" Then
         Dim Window As Object = Me.HostApplication.ActiveWindow
         If Not Window Is Nothing Then
            RefreshTaskPane(AdxTaskPane1.Item(Window))
            Marshal.ReleaseComObject(Window)
         End If
      End If
   End Sub

   Private Sub RefreshTaskPane(ByVal TaskPaneInstance As _
      ADXTaskPane.ADXCustomTaskPaneInstance)
      If Not TaskPaneInstance Is Nothing Then
         Dim uc As UserControl1 = TaskPaneInstance.Control
         If uc IsNot Nothing And TaskPaneInstance.Window IsNot 
Nothing Then
            uc.InfoString = GetInfoString(TaskPaneInstance.Window)
         End If
      End If
   End Sub

The InfoString property mentioned above just updates the text of the label located on the UserControl.

See also Office 2007 task pane components    Developing custom Excel task panes 

Step 13. Running the COM add-in

Choose the Register Add-in Express Project item in the Build menu, restart Excel, find your toolbar and click the button.

 
You find your add-in in the COM Add-ins dialog. See also Add the COM add-ins command to a toolbar or menu.

Step 14. Debugging the COM add-in

To debug your add-in, just indicate the add-in host application as the Start Program in the Project Options window.

However, when debugging an add-in or a smart tag on Visual Studio 2003 and Office XP you cannot see your add-in or smart tag on the COM add-ins or AutoCorrect dialog box. This is a “feature” of Office XP "added" by Microsoft.

Step 15. Deploying the COM add-in

Just build the setup project, copy all setup files to the target PC and run the setup.exe file to install the add-in. Read more about deploying Office COM add-in,  MSI and ClickOnce deployment,  find some useful deploying and debugging tips.

You may also find useful a free sample Excel add-in in VB. NET, C#, C++ and Word add-in in C#, VB.NET, C++.

Back to Add-in Express.NET homepage