COM Add-ins Part I: Introducing an Office 2000 Solution for the Entire (Office) Family

Thomas Rizzo
Microsoft Corporation

May 1999

Applies to: Microsoft Office 2000

This article is reprinted with permission of Informant Communications Group, Inc. Please visit their Web site at www.informant.com/mod/index.asp.

Summary: This article from Microsoft Office and Visual Basic for Applications Developer helps you get started with COM add-ins in Office 2000 by taking a look at the architecture of the COM add-in technology. (6 printed pages)

Introduction

When developing Microsoft® Office applications, most developers want to extend the already rich functionality found in the Office products. With Office 97, the Office products had different extensibility models, such as templates, forms, macros, and client extensions. To make extending Office 2000 easier for developers, Microsoft introduced a technology called COM add-ins in Office 2000. As you can guess by the name, a developer can build these add-ins using any COM-compliant programming tool. The pool of tools from which to choose includes VBA—already included in Office—Visual Basic®, and Visual C++®.

In addition to supporting any COM tool, COM add-ins are compatible across all Microsoft Office products. This support across all Office products means you can write your add-in once, and then use the add-in in any Office product. Add-ins that use common Office object libraries, such as the CommandBar object library, are the add-ins you'll share most often across Office products. As you would expect, the reuse aspect of your add-in would be "broken" if you use product-specific objects in your code.

To help you get started with COM add-ins in Office 2000, this article takes a look at the architecture of the COM add-in technology. To see how to develop a COM add-in for one of the Office products, see "COM Add-ins Part II: Building a COM Add-in for Outlook 2000."

COM Add-in Architecture

The architecture for COM add-ins is straightforward. On the one hand, you have an Office application that serves as a host for the add-in. On the other hand, you have the add-in you write, which is an in-process COM server.

Essentially your COM add-in is a compiled DLL that you write and register so that Office knows how to load and communicate with your add-in. By writing your add-in as a DLL, you get the speed of running your code in-process with your host application. This can provide tremendous performance benefits. However, you have to make sure you use defensive coding practices when writing your add-in, because you can crash the host application if you have errors in your code. Furthermore, poorly written code can slow down the host application, because the host application will have to wait for your add-in to finish processing before continuing.

As you can see in Figure 1, the Office application loads and connects to your add-in. As a result, the host Office application controls the lifetime of your add-in. This means that if your add-in needs to run or receive events when the host application isn't running, you shouldn't use a COM add-in.

Figure 1. Relationship between an Office application and a COM add-in

Furthermore, the COM add-in technology relies heavily on the system registry to determine which add-ins are available for the different Office products. The registry also tells the Office application how to load the add-in. For example, by putting certain configuration information into the registry, an add-in can always be loaded at the startup of the Office application.

Beyond holding this configuration information for add-ins, the registry specifies the users for whom the add-in should load. This capability is useful if your users are roaming; by placing the registration information for your application in a specific part of the registry, your add-in can roam with the user. Also, by placing your registration in a different part of the registry, you can force every user on a machine to use your add-in, and prevent the users from uninstalling the add-in from the machine.

When you register your add-in under HKEY_LOCAL_MACHINE, it's made available to every user on the machine. This allows developers to install an add-in on a machine once, and not have to repeat the process for each user who logs on to the machine. A good example of an add-in that works this way is the VBA add-in for Outlook 2000. As you can see in Figure 2, the VBA add-in is registered under HKEY_LOCAL_MACHINE, so every user on the machine can access the add-in.

Figure 2. Registry locations for your COM add-ins, and their effects

The other location where you can install your add-in is under HKEY_CURRENT_USER (again, see Figure 2). Installing your add-in under this key allows you to make it available only to the current user of the system. You should register your add-in under this key when it meets the needs of only certain users on a multiuser system.

When writing registration information to the registry for your add-in, there are three values you need to write. The three properties are shown in Figure 3. Figure 4 describes values for the LoadBehavior property.

Table 1. Properties that must be written to the registry to properly control a COM add-in's behavior

Table 2. Valid values for the LoadBehavior property

COM Add-in Event Procedures

COM add-ins must implement a specific interface, IDTExtensibility2, to work with Office 2000. The IDTExtensibility2 interface provides five event procedures you must implement in your add-in (see Figure 5). These procedures provide a way for the Office applications to talk with your COM add-in to tell it when the host application is done initializing, when your add-in has been loaded, or when the add-in has been disconnected.

Table 3. Event procedures you must implement in your COM add-in

By using the different event procedures in IDTExtensibility2, you can write dynamic add-ins. For example, by using the OnStartupComplete event, you can dynamically change the toolbars and menu items of the host application, as soon as you know it's finished loading. You can also use this event to initialize different variables in your add-in that correspond to the objects in the host application. You should make your initialization code short and fast, however, so the host application doesn't appear to "hang" as a result of waiting for your code to finish.

Looking Ahead

We've discussed what a COM add-in is and the architecture behind the technology. The article "COM Add-ins Part II: Building a COM Add-in for Outlook 2000" takes a look at developing and registering a COM add-in in Office 2000. Hopefully, many of the concepts you've seen in this Part I article will become clearer when you see the code in Part II. For developers, COM add-ins provide a great opportunity to extend and integrate your applications even more closely with Microsoft Office 2000.

Thomas Rizzo works as a Product Manager in the Microsoft Exchange Server Product Unit in Redmond, WA. He specializes in evangelizing development features in both Exchange and Outlook. You can reach Tom at thomriz@microsoft.com. Tom is also the author of Programming Microsoft Outlook and Exchange Server [Microsoft Press, March 1999].