Hooking a COM Add-in Up to a Command Bar Control

If your COM add-in has a user interface, it must be integrated with the host application in some way, so the user can interact with it. For example, the user interface for your COM add-in most likely includes a form. At some point, code in the add-in must be run to display the form.

One way to integrate your add-in with an application's user interface is to include code in the OnStartupComplete event procedure that creates a new command bar control (toolbar button or menu item) in the host application. When your add-in is loaded, the user can click the button or menu item to work with the add-in. You can use the OnConnection event procedure, but it does not guarantee that the command bar object has been loaded.

Similarly, you can add code to unload your add-in in the OnBeginShutdown event procedure or the OnDisconnection event procedure.

The critical aspect of integrating an add-in through a command bar control is the process of setting up the event sink. You must create a command bar control that is event-ready, so its Click event is triggered when the user clicks the control. You can use the WithEvents keyword to create an event-ready command bar control.

If you set the load behavior for your add-in to Load at Next Startup Only, you also must set the OnAction property for the command bar control. If you do not set the OnAction property, the add-in will load the first time the application starts. The next time you start the application, however, the load behavior for the add-in will be set to Load on Demand, and the command bar control that you have created for the add-in will not load the add-in unless the OnAction property has been set.

Even if your add-in is not demand-loaded, it is a good idea to set this property in your code, in case you later change the load behavior for the add-in. The syntax for setting the OnAction property for a COM add-in is:

ctlButton.OnAction = "!<ProgID>"

where ctlButton is the CommandBarButton object and ProgID is the programmatic identifier for the add-in. The programmatic identifier is the sub key that is created for the add-in in the Microsoft® Windows® registry. Each add-in designer or class module that implements the IDTExtensibility2 library in the COM Add-in project adds its own programmatic identifier to the registry, beneath the AddIns sub key for the host application in which it will run. The programmatic identifier for a COM add-in consists of the name of the project followed by the name of the add-in designer or class module. For example, the programmatic identifier for the ImageGallery add-in for Microsoft® Word is ImageGallery.dsrImageWord.

To return the programmatic identifier for an add-in, you can use the AddInInst argument that is passed to the OnConnection event procedure. This argument provides a reference to the add-in designer or class module in which code is running currently. The AddInInst argument is an object of type COMAddIn, which has a ProgId property that returns the programmatic identifier. Note that you must concatenate the !< and > delimiters before and after the programmatic identifier string to properly set the OnAction property.

Note   If your add-in will run in Word, you also must set the Tag property for the CommandBarButton object to a unique String value. This makes sure the command bar button will respond to the Click event and load the add-in for each new document window that the user opens. Because the Tag property provides you with additional information about the control, it is a good idea to set the Tag property for a command bar button that loads a COM add-in in any host application.

See Also

Building COM Add-ins for Office Applications | Working with Add-in Designers | Specifying Load Behavior | Writing Code in the Add-in Designer | Creating a Command Bar Control | Debugging a COM Add-in | Making the DLL | Distributing COM Add-ins | COM Add-ins and Security