Microsoft Office 2000 and later support a new, uniform
design architecture for building application add-ins to enhance and to control
Office applications. These add-ins are called COM add-ins. This step-by-step
article discusses Office COM add-ins and describes how to build an Office COM
add-in by using Microsoft Visual Basic .NET.
The IDTExensibility2 Interface
A COM add-in is an in-process COM server, or ActiveX dynamic link
library (DLL), that implements the IDTExensibility2
interface as described in the Microsoft Add-in Designer type
library (Msaddndr.dll). All COM add-ins inherit from this interface and must
implement each of its five methods.
event fires whenever the COM add-in is
connected. The add-in may be connected on startup, by the end user, or through
Automation. If OnConnection
returns successfully, the add-in is said to be
loaded. If an error message is returned, the host application immediately
releases its reference to the add-in, and the object is destroyed. OnConnection
takes the following four parameters:
- Application - A reference to the host application object.
- ConnectMode - A constant that specifies how the add-in is connected. The
add-in can be connected in the following ways:
- ext_cm_AfterStartup - The add-in is started by the end user from the COM Add-ins dialog box.
- ext_cm_CommandLine - The add-in is connected from the command line. Note that this
does not apply to building COM add-ins for Office applications.
- ext_cm_External - The add-in is connected by an external application through
Automation. Note that this does not apply to building COM add-ins for Office
- ext_cm_Startup - The add-in is started by the host at application startup. This
behavior is controlled by a setting in the registry.
- AddInInst - A reference to the COMAddIn object that refers to this add-in in the COMAddIns collection for the host application.
- Custom - An array of Variant type values that can hold user-defined data.
event fires when the COM add-in is
disconnected and just before it unloads from memory. The add-in should perform
any cleanup of resources in this event and should restore any changes made to the
host application. OnDisconnection
takes the following two
- RemoveMode - A constant that specifies how the add-in was disconnected. The
add-in can be disconnected in the following ways:
- ext_dm_HostShutdown - The add-in is disconnected when the host application
- ext_dm_UserClosed - The add-in is disconnected by the end user or an Automation
- Custom - An array of Variant type values that can hold user-defined data.
event fires when the set of registered COM
add-ins changes. In other words, whenever a COM add-in is installed or removed
from the host application, this event fires.
OnStartupComplete and OnBeginShutdown
Both the OnStartupComplete
and the OnBeginShutdown
methods are called
when the host application has left or is entering a state in which user
interaction should be avoided because the application is busy loading or
unloading itself from memory. OnStartupComplete
is only called if the add-in
was connected during startup, and OnBeginShutdown
is only called if the host
disconnects the add-in during shutdown.
Because the user interface
for the host application is fully active when these events fire, they may be
the only way to perform certain actions that otherwise would be unavailable
COM Add-in Registration
In addition to normal COM registration, a COM add-in needs to
register itself with each Office application in which it runs. To register
itself with a particular application, the add-in should create a subkey, using
its ProgID as the name for the key, under the following location:
The add-in can provide values at this key location
for both a friendly display name and a full description. In addition, the
add-in should specify its desired load behavior by using a DWORD value called
LoadBehavior. This value determines how the add-in is loaded by the host
application, and is made up of a combination of the following values:
- 0 = Disconnect - Is not loaded.
- 1 = Connected - Is loaded.
- 2 = Bootload - Load on application startup.
- 8 = DemandLoad - Load only when requested by
- 16 = ConnectFirstTime - Load only once (on next
The typical value specified is 0x03 (Connected | Bootload).
Add-ins that implement IDTExtensibility2
should also specify a DWORD value called CommandLineSafe to
indicate whether the add-ins are safe for operations that do not support a user
interface. A value of 0x00 indicates False, and a value of 0x01 indicates True.
How to Build a COM Add-in by Using Visual Basic .NET
As mentioned earlier, an Office COM add-in is an in-process COM
server that is activated by an Office application through the COM run-time
layer. Therefore, developing a COM add-in in Visual Basic .NET requires that the add-in
component be implemented in .NET and then exposed to the COM clients (that is,
the Office applications) through the COM interop layer.
To create a
COM add-in in Visual Basic .NET, follow these steps:
- In Visual Basic .NET, create a Class Library
- Add a reference to the type library that implements IDTExtensibility2. The primary interop assembly for this is already available under
the name Extensibility.
- Add a reference to the Microsoft Office object library. The
primary interop assembly for this is already available under the name Office.
- Create a public class in the class library that implements IDTExtensibility2.
- After the class library is built, register the library for
COM interop. To do this, generate a strong named assembly for this class
library and then register it with COM interop. You can use Regasm.exe to
register a .NET component for COM interop.
- Create registry entries so that Office applications can
recognize and load the add-in.
You can choose to complete all of these steps, or you can
create a .NET project of type Shared Addin
. This starts the Extensibility Wizard, which helps you to create
a COM add-in in .NET.
The Extensibility Wizard creates a Visual
Basic .NET class library project along with a Connect
class that implements the IDTExtensibility2
interface. The skeleton code that implements the empty members of
is also generated. This project has references to Extensibility
and Office assemblies. The build settings of the project have Register for COM Interop
selected. The assembly key (.snk) file is generated and is
referenced in the AssemblyKeyfile
attribute in Assemblyinfo.vb.
Along with the class
library project, the wizard generates a setup project that you can use to
deploy the COM add-in on other computers. You may remove this project if
- On the File menu in Microsoft Visual Studio .NET, click New, and then click Project.
- In the New Project dialog box, expand Other Projects under Project Types, select Extensibility Projects, and then select the Shared Add-in template.
- Type MyCOMAddin as the name of the
add-in, and then click OK.
- When the Extensibility Wizard appears, follow these steps:
- On page 1, select Create an Add-in using Visual Basic, and then click Next.
- On page 2, select the following host applications, and
then click Next:
- Microsoft Word
- Microsoft PowerPoint
- Microsoft Outlook
- Microsoft Excel
- Microsoft Access
- On page 3, provide a name and description for the
add-in, and then click Next.
Note The name and description of the add-in appear in the COM Add-in dialog box in the Office application.
- On page 4, select all of the available options, and then
- Click Finish.
- Add the following member to the Connect class:
Dim WithEvents MyButton As CommandBarButton
- Implement the code for all the members of IDTExtensibility2 in the Connect class, as follows:
Public Sub OnBeginShutdown(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnBeginShutdown
On Error Resume Next
' Notify the user you are shutting down, and delete the button.
MsgBox("Our custom Add-in is unloading.")
MyButton = Nothing
Public Sub OnAddInsUpdate(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnAddInsUpdate
Public Sub OnStartupComplete(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnStartupComplete
Dim oCommandBars As CommandBars
Dim oStandardBar As CommandBar
On Error Resume Next
' Set up a custom button on the "Standard" command bar.
oCommandBars = applicationObject.CommandBars
If oCommandBars Is Nothing Then
' Outlook has the CommandBars collection on the Explorer object.
oCommandBars = applicationObject.ActiveExplorer.CommandBars
oStandardBar = oCommandBars.Item("Standard")
If oStandardBar Is Nothing Then
' Access names its main toolbar Database.
oStandardBar = oCommandBars.Item("Database")
' In case the button was not deleted, use the exiting one.
MyButton = oStandardBar.Controls.Item("My Custom Button")
If MyButton Is Nothing Then
MyButton = oStandardBar.Controls.Add(1)
.Caption = "My Custom Button"
.Style = MsoButtonStyle.msoButtonCaption
' The following items are optional, but recommended.
' The Tag property lets you quickly find the control
' and helps MSO keep track of it when more than
' one application window is visible. The property is required
' by some Office applications and should be provided.
.Tag = "My Custom Button"
' The OnAction property is optional but recommended.
' It should be set to the ProgID of the add-in, so that if
' the add-in is not loaded when a user clicks the button,
' MSO loads the add-in automatically and then raises
' the Click event for the add-in to handle.
.OnAction = "!<MyCOMAddin.Connect>"
.Visible = True
' Display a simple message to show which application you started in.
MsgBox("Started in " & applicationObject.Name & ".")
oStandardBar = Nothing
oCommandBars = Nothing
Public Sub OnDisconnection(ByVal RemoveMode As Extensibility.ext_DisconnectMode, ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnDisconnection
On Error Resume Next
If RemoveMode <> Extensibility.ext_DisconnectMode.ext_dm_HostShutdown Then _
applicationObject = Nothing
Public Sub OnConnection(ByVal application As Object, ByVal connectMode As Extensibility.ext_ConnectMode, ByVal addInInst As Object, ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnConnection
MsgBox("On Connection In MyAddin")
applicationObject = application
addInInstance = addInInst
' If you aren't in startup, manually call OnStartupComplete.
If (connectMode <> Extensibility.ext_ConnectMode.ext_cm_Startup) Then _
Private Sub MyButton_Click(ByVal Ctrl As Microsoft.Office.Core.CommandBarButton, ByRef CancelDefault As Boolean) Handles MyButton.Click
MsgBox("Our CommandBar button was pressed!")
- Build and test the COM add-in. To do this, follow these
- On the Build menu, click Build MyCOMAddin. Note that building the COM add-in registers the .NET class with
the COM interop.
- Start one of the Office applications that you selected
as host applications for your add-in (for example, Microsoft Word or Microsoft Excel).
- After the add-in has started, the OnConnection event is
fired, and you receive a message box. When you dismiss the message box, the
OnStartupComplete event fires, and you receive a second message box. Dismiss the
- Note that the add-in added a new custom button with the
caption "My Custom Button" to the standard toolbar.
- Click My Custom Button. The Click event for the button is handled by the add-in and you receive a
message box. Dismiss the message box.
- Quit the Office application.
- When you quit the application, the OnBeginShutDown
event fires, and you receive a message box. Dismiss the message box to end the
additional information about writing COM add-ins, click the article number
below to view the article in the Microsoft Knowledge Base:
INFO: VB6 Designers Do Not Work in VB5
For more information about developing Web-based solutions for Microsoft Internet Explorer, visit the following Microsoft Web sites:
(c) Microsoft Corporation 2001, All Rights Reserved.
Contributions by Ranjit R. Sawant, Microsoft Corporation.