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

Article
06/14/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

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.

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

See Also

Additional resources