Microsoft KB Archive/238228

= How to build an Office 2000 COM add-in in Visual Basic =

Article ID: 238228

Article Last Modified on 1/24/2007

-

APPLIES TO


 * Microsoft Excel 2000 Standard Edition
 * Microsoft Office XP Developer Edition
 * Microsoft Office 2000 Developer Edition
 * Microsoft Access 2002 Standard Edition
 * Microsoft Access 2000 Standard Edition
 * Microsoft Excel 2002 Standard Edition
 * Microsoft FrontPage 2002 Standard Edition
 * Microsoft FrontPage 2000 Standard Edition
 * Microsoft Outlook 2002 Standard Edition
 * Microsoft Outlook 2000 Standard Edition
 * Microsoft PowerPoint 2002 Standard Edition
 * Microsoft PowerPoint 2000 Standard Edition
 * Microsoft Word 2002 Standard Edition
 * Microsoft Word 2000 Standard Edition
 * Microsoft Visual Basic 5.0 Professional Edition
 * Microsoft Visual Basic 6.0 Professional Edition
 * Microsoft Visual Basic 5.0 Enterprise Edition
 * Microsoft Visual Basic 6.0 Enterprise Edition

-



This article was previously published under Q238228



SUMMARY
Microsoft Office 2000 and later support a new, uniform design architecture for building application add-ins to enhance and control Office applications. These add-ins are called COM Add-Ins. This article will demonstrate how to build a COM Add-In using Visual Basic.



MORE INFORMATION
A COM Add-In is an inprocess COM server (an ActiveX 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.

OnConnection
The OnConnection 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 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 was connected.
 * ext_cm_AfterStartup - Started by the end user from the COM add-ins dialog box.
 * ext_cm_CommandLine - Connected from the command line. (Does not apply to building COM add-ins for Office applications.)
 * ext_cm_External - Connected by an external application through automation. (Does not apply to building COM add-ins for Office applications.)
 * ext_cm_Startup - 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 Variants that can hold user-defined data.

OnDisconnection
The OnDisconnection 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 restore any changes made to the host application.

OnDisconnection takes the following two parameters:
 * RemoveMode - A constant that specifies how the add-in was disconnected.
 * ext_dm_HostShutdown - Disconnected when the host application closed.
 * ext_dm_UserClosed - Disconnected by the end user or an Automation controller.
 * Custom - An array of Variants that can hold user-defined data.

OnAddInsUpdate
The OnAddInsUpdate 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 OnBeginShutdown methods are called when the host application has left or is entering a state where user-interaction should be avoided because the application is busy loading or unloading itself from memory. OnStartupComplete is only called if your add-in was connected during startup, and OnBeginShutdown is only called if your add-in is disconnected by the host 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 from OnConnection and OnDisconnection.

Registering the COM add-in
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 sub key, using its ProgID as the name for the key, under the following location: HKEY_CURRENT_USER\Software\Microsoft\Office\\Addins\ 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 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 user.
 * 16 = ConnectFirstTime - Load only once (on next startup).

The typical value specified is 0x03 (Connected | Bootload).

Add-ins that implement IDTExtensibility2 should also specify a DWORD value called "CommandLineSafe" to indicate whether they are safe for operations that do not support a user interface. A value of 0x00 means False, 0x01 is True.

Building a COM add-in
You can build a COM Add-In in one of the three ways mentioned below:

Building a COM add-in by using the Com add-in Template
If you have Microsoft Office 2000 Developer or Microsoft Office XP Developer and Visual Basic 6.0, the easiest way to build a COM Add-in is to use the COM add-in.vbp template. This project is located in the ODETools\V9\Samples\OPG\Samples\CH11\VB_COM_AddIn subfolder on the Office 2000 Developer CD. Copy the files in this folder to the Visual Basic 6.0 Template\Projects folder, which is typically C:\Program Files\Microsoft Visual Studio\VB98\Template\Projects. Copying the template project to this location will ensure that the template appears in the Visual Basic 6.0 New Project dialog box. See Chapter 11 of the Microsoft Office 2000 Visual Basic Programmer's Guide for more information about this template and creating COM Add-ins.

Building a COM add-in by using the Visual Basic 6 add-in designer
If you have just Microsoft Visual Basic 6.0 installed and want to use a wrapper so that you don't need to directly implement IDTExtensibility2, you can use the same Add-In designer that you would use to build a VB6 Add-In. Follow these steps to build such an add-in for Microsoft Excel 2000 or 2002:  Start Microsoft Visual Basic 6.0 and select Addin as the project type. This should add a designer class to the project (Connect) and a form (frmAddin). Open the Designer window for Connect and select Microsoft Excel from the Application drop-down list. In the Initial Load Behavior drop-down list, select Startup. Remove frmAddin from the project. From the Project window, right-click the Connect item and select view code. Remove all the code in the designer's code window. This code works for VB add-ins but not Office add-ins.</li>  Add the following code to the designer: Option Explicit

Dim oXL As Object Dim WithEvents MyButton As Office.CommandBarButton

Private Sub AddinInstance_OnConnection(ByVal Application As Object, _   ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, _    ByVal AddInInst As Object, custom As Variant) On Error Resume Next MsgBox "My Addin started in " & Application.Name Set oXL = Application Set MyButton = oXL.CommandBars("Standard").Controls.Add(1) With MyButton .Caption = "My Custom Button" .Style = 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 there is more than ' one application window 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, such that if         ' the add-in is not loaded when a user presses the button, ' MSO loads the add-in automatically and then raises ' the Click event for the add-in to handle.

.OnAction = "!<" & AddInInst.ProgId & ">"

.Visible = True End With End Sub

Private Sub AddinInstance_OnDisconnection(ByVal RemoveMode As _     AddInDesignerObjects.ext_DisconnectMode, custom As Variant) On Error Resume Next MsgBox "My Addin was disconnected by " & _ IIf(RemoveMode = ext_dm_HostShutdown, _        "Excel shutdown.", "end user.") MyButton.Delete Set MyButton = Nothing Set oXL = Nothing End Sub

Private Sub MyButton_Click(ByVal Ctrl As Office.CommandBarButton, _    CancelDefault As Boolean) MsgBox "Our CommandBar button was pressed!" End Sub </li> Save the project and create the MyAddin.dll. The designer will register the add-in for you.</li> Open Microsoft Excel and you will notice a message box when the add-in is loaded and unloaded. On the standard toolbar, you will have a new button labeled My Custom Button that our add-in will handle when selected.</li></ol>

Building a COM add-in by using implements
While not as simple, you can create a COM Add-In using Microsoft Visual Basic 5.0 and the Implements keyword to directly implement the IDTExtensibility2 interface. The only downside to this approach is registration. Since Microsoft Visual Basic does not know how to add the keys needed to register the add-in with Office, you will need to do this separately (in a custom setup utility, or using a REG script).

However, the advantage to using Implements is that it is more direct and efficient than using the designer, and it allows us to create a single COM object that can work in multiple Office applications (instead of creating a separate Connect object for each application we want to work in).

Here are the steps for writing an Add-In using Implements: <ol> Open Visual Basic and create a new ActiveX DLL project. Name the project MyCOMAddin, and name the public class Connect.</li> From the References dialog box (Project | References), add a reference to the Microsoft Office 9.0 (or 10.0 for Office XP) Object Library and the Microsoft Add-In Designer type library. If you cannot find the Add-In Designer in the References list, you should Browse for Msaddndr.dll or Msaddndr.tlb, typically located in the "C:\Program Files\Common Files\Designer" folder.</li>  In the Code window for Connect, add the following: Option Explicit Implements IDTExtensibility2

Dim oHostApp As Object Dim WithEvents MyButton As Office.CommandBarButton

Private Sub IDTExtensibility2_OnConnection(ByVal Application As Object, _    ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, _

ByVal AddInInst As Object, custom As Variant)     On Error Resume Next    ' Set a reference to the host application...      Set oHostApp = Application    ' If you aren't in startup, then manually call OnStartupComplete...      If (ConnectMode <> ext_cm_Startup) Then _         Call IDTExtensibility2_OnStartupComplete(custom)   End Sub

Private Sub IDTExtensibility2_OnStartupComplete(custom As Variant) Dim oCommandBars As Office.CommandBars Dim oStandardBar As Office.CommandBar On Error Resume Next ' Set up a custom button on the "Standard" commandbar... Set oCommandBars = oHostApp.CommandBars If oCommandBars Is Nothing Then ' Outlook has the CommandBars collection on the Explorer object Set oCommandBars = oHostApp.ActiveExplorer.CommandBars End If     Set oStandardBar = oCommandBars.Item("Standard") If oStandardBar Is Nothing Then ' Access names it's main toolbar Database

Set oStandardBar = oCommandBars.Item("Database") End If   ' In case the button was not deleted, use the exiting one... Set MyButton = oStandardBar.Controls.Item("My Custom Button") If MyButton Is Nothing Then

Set MyButton = oStandardBar.Controls.Add(1) With MyButton .Caption = "My Custom Button" .Style = 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 there is more than ' one application window 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, such that if         ' the add-in is not loaded when a user presses 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 End With End If   ' Display a simple message to know which application you started in...      MsgBox "Started in " & oHostApp.Name & "."

Set oStandardBar = Nothing Set oCommandBars = Nothing End Sub

Private Sub IDTExtensibility2_OnDisconnection(ByVal RemoveMode As _    AddInDesignerObjects.ext_DisconnectMode, custom As Variant)

On Error Resume Next If RemoveMode <> ext_dm_HostShutdown Then _ Call IDTExtensibility2_OnBeginShutdown(custom) Set oHostApp = Nothing

End Sub

Private Sub IDTExtensibility2_OnBeginShutdown(custom As Variant) On Error Resume Next ' Notify the user you are shutting down, and delete the button...     MsgBox "Our custom Add-In is unloading." MyButton.Delete Set MyButton = Nothing End Sub

Private Sub MyButton_Click(ByVal Ctrl As Office.CommandBarButton,   CancelDefault As Boolean) MsgBox "Our CommandBar button was pressed!" End Sub

Private Sub IDTExtensibility2_OnAddInsUpdate(custom As Variant) 'You do nothing if this is called, but you need to     'add a comment so Visual Basic properly implements the function... End Sub </li> Save the project and create the MyCOMAddin.dll. However, before your add-in will work you need to associate it with each Office application that you want it to run in. In the real world, a setup utility can do this when the DLL is installed. For this sample, you will call a registration function directly from the Visual Basic IDE.</li>  Add a new module to the project. In the code for Module1, add the following: Option Explicit

Private Declare Function RegCreateKeyEx Lib "advapi32.dll" _ Alias "RegCreateKeyExA" (ByVal hKey As Long, ByVal lpSubKey As String, _  ByVal Reserved As Long, ByVal lpClass As String, ByVal dwOptions As _   Long, ByVal samDesired As Long, ByVal lpSecurityAttributes As Long, _   phkResult As Long, lpdwDisposition As Long) As Long Private Declare Function RegSetValueEx Lib "advapi32.dll" _ Alias "RegSetValueExA" (ByVal hKey As Long, ByVal lpValueName As _  String, ByVal Reserved As Long, ByVal dwType As Long, lpData As Any, _   ByVal cbData As Long) As Long Private Declare Function RegDeleteKey Lib "advapi32.dll" _ Alias "RegDeleteKeyA" (ByVal hKey As Long, ByVal lpSubKey As String) _ As Long Private Declare Function RegCloseKey Lib "advapi32.dll" _ (ByVal hKey As Long) As Long

Private Const HKEY_CURRENT_USER = &H80000001 Private Const KEY_ALL_ACCESS = &H1F0037 Private Const REG_CREATED_NEW_KEY = &H1 Private Const REG_SZ = 1 Private Const REG_DWORD = 4

'These are the settings for your Add-in... Private Const PROGID As String = "MyCOMAddin.Connect" Private Const DESCRIPTION As String = "My VB5/6 COM Add-In Sample" Private Const LOADBEHAVIOR As Long = 3 Private Const SAFEFORCOMMANDLINE As Long = 0

Public Sub RegisterAll RegisterOfficeAddin "Access" RegisterOfficeAddin "Excel" RegisterOfficeAddin "FrontPage" RegisterOfficeAddin "Outlook" RegisterOfficeAddin "PowerPoint" RegisterOfficeAddin "Word" End Sub

Public Sub UnregisterAll UnRegisterOfficeAddin "Access" UnRegisterOfficeAddin "Excel" UnRegisterOfficeAddin "FrontPage" UnRegisterOfficeAddin "Outlook" UnRegisterOfficeAddin "PowerPoint" UnRegisterOfficeAddin "Word" End Sub

Public Sub RegisterOfficeAddin(sTargetApp As String) Dim sRegKey As String Dim nRet As Long, dwTmp As Long Dim hKey As Long sRegKey = "Software\Microsoft\Office\" & sTargetApp _ & "\Addins\" & PROGID nRet = RegCreateKeyEx(HKEY_CURRENT_USER, sRegKey, 0, _        vbNullString, 0, KEY_ALL_ACCESS, 0, hKey, dwTmp) If nRet = 0 Then If dwTmp = REG_CREATED_NEW_KEY Then Call RegSetValueEx(hKey, "FriendlyName", 0, _              REG_SZ, ByVal PROGID, Len(PROGID)) Call RegSetValueEx(hKey, "Description", 0, _              REG_SZ, ByVal DESCRIPTION, Len(DESCRIPTION)) Call RegSetValueEx(hKey, "LoadBehavior", 0, _              REG_DWORD, LOADBEHAVIOR, 4) Call RegSetValueEx(hKey, "CommandLineSafe", 0, _              REG_DWORD, SAFEFORCOMMANDLINE, 4) End If        Call RegCloseKey(hKey) End If  End Sub

Public Sub UnRegisterOfficeAddin(sTargetApp As String) Dim sRegKey As String sRegKey = "Software\Microsoft\Office\" & sTargetApp _ & "\Addins\" & PROGID Call RegDeleteKey(HKEY_CURRENT_USER, sRegKey) End Sub </li> From the Immediate window (View | Immediate Window), type RegisterAll, and then press ENTER. This will register the add-in with all the Office applications supported (Access, Excel, FrontPage, Outlook, PowerPoint, and Word).</li> Open any of the Office applications listed prior. Notice the message box on startup and shutdown, and the custom button added to standard toolbar.</li> When you want to unregister the add-in, type UnregisterAll in the Visual Basic Immediate window and then press ENTER.</li></ol>

<div class="references_section">