VBtech

COM Add-ins: Part I

Introducing COM Add-ins for Office 2000

By Ken Getz

Several years ago, back in the bad old days of Windows 3.1, I was hired to write an add-in that would accomplish the same task in Word, Excel, and Access. I had to store the current printer selection, switch the default printer to a specific driver, print the current document, and then set the default printer back to its original setting.

Besides this task requiring me to determine how to work with printers in each of the products, it also required learning how to program in three distinct programming languages (Word Basic and Access Basic, although similar in titles, have many painful differences in dialect, and Excel macros are a disaster unto themselves), and how to create, manage, and deploy three different types of documents. For Word, I created a DOT file; for Access, an MDA file; and for Excel, an XLA file.

Given the same task today for Office 2000, the job would be a lot simpler. Because each of the Office 2000 products supports add-ins implementing a common COM interface, all you need to do is create an ActiveX EXE or DLL (that is, an ActiveX component that runs either in- or out-of-process), and share it among all the products that need to use the add-in. You write the required shared code for all the products hosting your add-in, and add a minor bit of code for handling each individual product's object model as necessary. Because these add-ins are built on classes you create in a single project, you can share code between the add-ins for each of the products, and supply a single DLL or EXE to your clients using the add-in.

Why create an add-in at all? You might want to extend the functionality of the product, like all the Wizards provided with Microsoft Office, or provide similar features across all the Office products. In this series, you'll see how to create add-ins, using Visual Basic (VB) 6, which can run in any of the Microsoft Office 2000 products (or any other product that supports the COM add-in model). The sample code provides two examples (see end of article for details):

• From within Excel, Word, and Outlook, display a form that allows users to enter name and address information. Once completed, the form inserts the information, formatted for the current host application, into the current document (Word and Excel) or into a new Contact item (Outlook). The sample VB project is named InsertName.vbp.
• Although the techniques aren't discussed in this article, you can create add-ins for the VBA IDE as well. The second example (WebBrowser.vbp) allows you to add a dockable Web browser window (using the Internet Explorer Web browser control) to the VBA IDE. This add-in can be used in any VBA 6 host that supports add-ins (including all the Office applications, and some other products that have licensed VBA). The concepts are the same as those involved in creating add-ins for the Office products themselves, but VBA also supports add-ins whose windows can be docked to the edges of the parent window, just like the Properties or Project windows.

To create a COM add-in for Microsoft Office 2000, you'll need to create an in- or out-of-process ActiveX component. The simplest way to accomplish this goal is to use VB6, and this article series uses VB to create its samples. You can certainly apply this information to any development environment that allows you to create ActiveX components. You'll need to implement the correct interface, IDTExtensibility2, as well. Microsoft provides a type library for this interface, making it easy for VB developers to create add-ins: MSADDNDR.DLL contains the information you need. In fact, this DLL also provides VB developers with another useful tool; it includes a COM add-in designer, making it even easier for VB developers to create add-ins, as you'll see later. Once your add-in is "hooked up" correctly, it has complete access to the full object model of its host application, and can run code as if it was part of a VBA project hosted in the application itself.

If you are to write a COM add-in from scratch, you'll need to accomplish these goals:

• Create a new DLL/EXE COM server project.
• Implement the IDTExtensibility2 interface. (You'll use the add-in designer object to take care of this for you.)
• Take care of a few simple Windows registry settings (again, the designer takes care of this for you).

That's it! You've got a COM add-in for Office. Of course, the details are more complex than these steps would make them appear.

Although VB ships with a template that makes it easy to create add-ins for the VB environment, you can't use that template for creating add-ins for Office. (You can use the Add-in project template that comes with VB to create add-ins for VBA, but it requires some modifications in order to work correctly in that environment.) Instead, you can use the template provided with Microsoft Office 2000 Developer, or you can use the modified version of that template provided with this article's samples. I prefer the modified version of the template - it suits my particular needs better - but you may use whichever one you like. In either case, you'll need to copy the template to your VB templates folder (use the Tools | Options menu, selecting the Environment tab, to determine in which folder VB looks for templates). Make sure you place the files in the Projects folder within the templates location, so VB will provide Office Add-In as an option the next time you create a new project.

To get started, you might try creating an add-in based on the template provided with this article. Once you've copied the four files to the appropriate folder, create a new VB project based on the Office Add-In template. Compile the add-in - it will be named MyComAddIn.DLL by default - and then start Microsoft Word. (The template creates add-ins for Word, unless you modify it.) You should find, on the Tools menu, a new item named My COM Add-In. Select it and Word displays a simple form, provided by the COM add-in you just created. It couldn't be much simpler than that, could it? Make sure you actually quit the host application before attempting to run the add-in, if it's currently running. The host application only checks the registry for available COM add-ins when it loads, so your newly created add-in won't be available until you quit and restart the host.

How can you tell what COM add-ins are available for a particular product? Besides checking in the registry (look for the HKEY_CURRENT_USER\Software\Microsoft\Office\<AppName>\Addins key), you can use the COM Add-Ins menu within each host application. Most likely, however, you won't be able to find this menu item, because it's not included in the host application's menu structure by default. You'll need to choose the View | Toolbars | Customize menu item in each application, select the Commands tab, find the Tools menu in the Categories list, and then find the COM Add-Ins item in the Commands list (see FIGURE 1).

FIGURE 1: Use the Customize dialog box to add the COM Add-Ins menu item to the host application's menu.

Click and drag the item onto an appropriate existing menu (I normally place it on the Tools menu), and then close the Customize dialog box. You can accomplish this goal programmatically, if you must, but most users will never need to see this menu item within their applications. Once you've made the COM Add-Ins menu item available, selecting it will allow you to load or unload your add-ins. FIGURE 2 shows this dialog box in action.

FIGURE 2: Use the COM Add-Ins dialog box to connect or disconnect add-ins.

Using the COM Add-in Designer

Why use the COM add-in designer? This designer, which includes a simple user interface and a class module, takes care of several of the housekeeping details for you. The designer:

• provides a reference back to the host application.
• makes it simple to set the add-in's properties.
• handles setting up the necessary registry values for you, saving the properties you set using the user interface to the registry.
• implements the IDTExtensibility2 interface for you. Because the designer takes care of this, you don't need to supply all the methods required by the interface (as you would otherwise). You only supply the code you need for your add-in.

You don't need to use the designer; you could take care of all these tasks yourself. I suggest, however, that you take advantage of this useful tool. When you first create a new project using the Office Add-In template, you'll find one instance of the COM add-in designer in your project. This designer allows you to specify the behavior of the add-in for a specific host application, and you'll need to supply values for several properties, as shown in FIGURE 3.

FIGURE 3: Properties you can set using the COM add-in designer.

FIGURE 4 shows an instance of the COM add-in designer, from the InsertName sample project.

FIGURE 4: The General tab of the COM add-in designer allows you to specify descriptive text, the host application, and load-time behavior.

You can also select the Advanced tab of the COM add-in designer. On this page, you can specify the name of a resource DLL (in case you need to localize text or images), and you can specify a registry key and values, to contain your own registry values, specific to your add-in. FIGURE 5 describes each of the options.

FIGURE 5: Specify these properties on the Advanced tab of the COM add-in designer.

The Initial Load Behavior property of the designer requires further explanation. This property defines when the add-in gets loaded into the host application. By setting this property's value, you can force your add-in to be loaded each time the user starts the host application, and to never load the add-in until the user specifically requests it. FIGURE 6 describes each of the options.

FIGURE 6: Select the Initial Load Behavior property from these values.

Because you must include one instance of the COM add-in designer for each host you want your add-in to support, you'll need to add more than one designer if you want to support multiple host applications. You're likely to want to set all the designer properties once, and then duplicate the properties for each host application. To do that, your best bet is to get one application's properties set up correctly, save the designer, and then add it back in using a different name for each host application. Follow the next steps to accomplish this goal.

Using the Office Add-In template, set up one designer so that it includes all the appropriate property settings. Save the designer, giving it a generic (host application-neutral) name. Modify the Name property of the designer within the VB project, perhaps indicating the host application, and then save the designer to disk, using an application-specific name. (Use the File | Save As menu item to save the file.) Use the Project | Add File menu item to add a new copy of the designer to the project, choosing the generic name. Modify the new designer's properties, and save the designer to disk with an application-specific name again. Repeat the last couple of steps as necessary, adding one copy of the designer for each host application you must support.

Conclusion

That's all we have room for. I've related a bit of the history of the COM add-in, and shown you why the Office 2000 version is far superior to its Office 97 predecessor. I've also introduced the COM add-in designer, and described why Visual Basic 6 makes a particularly good environment for developing COM add-ins.

In Part II, we'll delve into the coding requirements, including the necessary methods and event handlers. We'll also discuss debugging techniques and deployment issues. See you then.

Ken Getz (mailto: KenG@mcwtech.com) is a Senior Consultant with MCW Technologies, a Microsoft Certified Solution Provider focusing on Visual Basic and the Office and BackOffice suites. He is also co-author of Visual Basic Language Developer's Handbook (with Mike Gilbert) [SYBEX, 2000], and Access 2000 Developer's Handbook (with Gilbert and Paul Litwin) [SYBEX, 1999]. He's recently completed a series of VB6 training tapes, and a series of Access 97 tapes (with co-author Paul Litwin) for Application Developers Training Company (http://www.appdev.com/video).