Add-in Express™
for Microsoft® Office and .netAdd-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, PowerPoint or other applications from the Microsoft Office 2000 - 2007 suites in Visual Studio 2003, 2005 and 2008.
On other pages you will find some tips and tricks about:
Please keep in mind that 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 Delphi Prism 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. You will find it in the New Project dialog.
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 the shim that will be used for loading your add-in into the host application(s).
On the second page you specify the host application(s) of your Office COM add-in and the interop assemblies to use. In our sample, we selected Microsoft Excel, Word and PowerPoint.
This VB.NET sample shows an Add-in Express COM Add-in project implementing a COM add-in for Excel, Word and PowerPoint 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.
When you click Finish, the project wizard creates and opens a new 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 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 View Code in the popup menu.
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.
Here is a list of available commands and the components they add 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.
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 newly added button.
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
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.
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 called 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 the File menu in Excel and Word version 2000 - 2003, 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. The screenshot 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 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, you 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 designer provides the Add Events command that adds (and removes) 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 event components you need (see Application-level events). In our sample we add Excel, Word and PowerPoint event components to the COM Add-in module.
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 Events template item that allows implementing a set of business rules for an Excel worksheet by handling its events.
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 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 source code of the sample add-in described here, you can find how you can customize the Office 2007 menu. See also Office 2007 Ribbon components and Office 2007 Ribbon visual designer.
Step 12. Adding a custom task pane in Excel 2000 - 2007
To creating a new Excel task pane just do the following:
- Add an Excel Task Panes Manager (ADXExcelTaskPanesManager) to your add-in module (see How to add an Add-in Express component to a designer) .
- Add an Add-in Express Excel Task Pane (ADXExcelTaskPane) to your project.
- In the visual designer available for the Controls collection of the manager, add an item to the collection, bind the pane to the item and specify its properties, such as Position.
The screenshot below shows the setting chosen for the above-mentioned item:
The properties of interest are described below:
- 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.
For more information, see also Advanced custom task panes. For step-by-step instructions, see Developing a custom Excel task pane sample.
Now you add a label onto the form, write a property that reads and updates the label, and set the property value in the following code (the property is named InfoString):
Private Sub RefreshTaskPane()
Select Case Me.HostName
Case "Excel"
Dim Pane As ADXExcelTaskPane1 = _
TryCast(Me.AdxExcelTaskPanesCollectionItem1.TaskPaneInstance, _
ADXExcelTaskPane1)
If Pane IsNot Nothing Then
Pane.InfoString = Me.GetInfoString()
End If
Case Else
'System.Windows.Forms.MessageBox.Show("Invalid host application!")
End Select
End Sub
Step 13. Adding custom task panes in Word 2000 - 2007
Now, when the Excel pane is ready, you add a Word task pane in the same manner:
- Add a Word Task Panes Manager (ADXWordTaskPanesManager) to your add-in module.
- Add an Add-in Express Word Task Pane (ADXWordTaskPane) to your project.
- In the visual designer available for the Controls collection of the manager, add an item to the collection, bind the pane to the item and specify an appropriate value in the Position.
When the item's properties are set, you 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"
Dim Pane As ADXExcelTaskPane1 = _
TryCast(Me.AdxExcelTaskPanesCollectionItem1.TaskPaneInstance, _
ADXExcelTaskPane1)
If Pane IsNot Nothing Then
Pane.InfoString = Me.GetInfoString()
End If
Case "Word"
Dim Pane As ADXWordTaskPane1 = _
TryCast(Me.AdxWordTaskPanesCollectionItem1. _
CurrentTaskPaneInstance, ADXWordTaskPane1)
If Pane IsNot Nothing Then
Pane.InfoString = Me.GetInfoString()
End If
Case Else
'System.Windows.Forms.MessageBox.Show("Invalid host application!")
End Select
End Sub
The different names of the properties returning instances of the two pane types reflect the difference in Excel and Word windowing; while Excel is an MDI (or quasi-MDI) application, Word is an application that normally shows multiple windows. In this situation, 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. For more details, please see Office 2007 task pane components.
Step 14. Adding custom task panes in PowerPoint 2000 - 2007
Now you add a PowerPoint task pane:
- Add a PowerPoint Task Panes Manager (ADXPowerPointTaskPanesManager) to your add-in module.
- Add an Add-in Express PowerPoint Task Pane (ADXPowerPointTaskPane) to your project.
- In the visual designer available for the Controls collection of the manager, add an item to the 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:
Friend 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.InfoString = Me.GetInfoString()
End If
Case Else
'System.Windows.Forms.MessageBox.Show("Invalid host application!")
End Select
End Sub
Step 15. Running the COM add-in
Choose the Register Add-in Express Project item 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), and restart the host applications.
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 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.
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 17. 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 |