How a COM AddIn Is Registered

A COM add-in, from the standpoint of the Office application, is a COM component registered in a particular place in the registry that implements the IDTExtensibility2 interface defined by Office and Visual Studio. From your standpoint as a Visual Basic developer, you are writing a Visual Basic class that you will compile into an assembly (DLL). Through .NET's COM interop support, your Visual Basic class can be made to look like a COM component to the Office application. You will have to register your add-in just like any COM component to get the Office application to load it.

The registry settings and interface implementation described in this section are created for you automatically when you create an add-in project in Visual Studio. It is still important to understand the anatomy of an add-in, however, should you have to troubleshoot add-in issues.

Registry Location of a COM AddIn: HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE

Office determines which COM add-ins to load for a particular application by checking two places in the registry: either under HKEY_CURRENT_ USER or under HKEY_LOCAL_MACHINE. To view the registry, choose Run from the Start menu of Windows; type regedit.exe; and click the OK button.

The first place a COM add-in can be registered is in the registry under HKEY_CURRENT_USER\Software\Microsoft\Office\%appname%\Addins. This is where COM add-ins installed on a peruser basis are found, as shown in Figure 23.1. COM add-ins typically should be installed on a peruser basis so that the add-in user settings will move with the user should the user log on to a different machine.

Figure 23.1. A registry entry for a COM add-in.

Any COM add-ins registered in the registry under HKEY_CURRENT_ USER will show up in the COM AddIns dialog box for the relevant Office application. Finding the COM AddIns dialog box in each Office application can be quite a challenge. In all Office applications, the dialog box is not available from a menu in the default install. To add a button to show the COM AddIns dialog box, you need to customize the toolbars in the Office application by rightclicking the command bar and selecting Customize. Doing so causes the Customize dialog box to appear (see Figure 23.2). Click the Commands tab, and select Tools in the Categories list. Then scroll through the list of available commands; find the COM AddIns command; and drag this command onto an existing toolbar.

Figure 23.2. Locating the COM AddIns command in the Customize dialog box.

When you click the COM AddIns button that you have added to a toolbar, the COM AddIns dialog box displays, as shown in Figure 23.3. This dialog box shows you all the COM add-ins registered in the registry under HKEY_CURRENT_USER for the Office application you are using.

Figure 23.3. The COM AddIns dialog box.

The second place a COM add-in can be registered is under HKEY_LOCAL_MACHINE\Software\Microsoft\Office\%appname%\Addins. COM add-ins registered on a permachine basis are available for all users but also are effectively hidden from the user within the Office application. If a COM add-in is registered under HKEY_LOCAL_MACHINE, it will never show up in the COM AddIns dialog box. It is recommended that you register your COM add-in under HKEY_LOCAL_USER so that your COM add-in is visible to end users.

Registry Entries Required for a COM AddIn

Each COM add-in registered in the registry, whether under HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE, must be registered in the following way. First, there must be a key representing the COM add-in under the Addins key. This key is named with the ProgID of the COM add-in. A ProgID is an identifier for the COM add-in that is generated by Visual Studio. COM uses this identifier to figure out how to create your COM add-in. The default ProgID for a Visual Studio COM add-in project is the name of the add-in project combined with the name of the class (Connect) generated in Visual Studio that implements IDTExtensibility2. So if you create a COM add-in project in Visual Studio called MyAddin2 for an Office application such as Outlook, the main key that Visual Studio creates in the registry for the COM add-in would be this:

HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\Addins\   MyAddin2.Connect 

Under the key for your COM add-in, several values are required. FriendlyName is a string value that contains the name of the COM add-in that will appear to the user in the COM AddIns dialog box. Description is a string value that contains a more indepth description of the COM add-in. This description does not appear anywhere in the Office UI or COM AddIns dialog box, but it is helpful when users or administrators are investigating, by using regedit.exe, what add-ins are installed on a machine and what they do. LoadBehavior is a DWORD value that describes the load behavior of the COM add-in. The values that LoadBehavior can be set to are a bitwise or of the values in Table 23.1. Typically, this should be set to the value of 3 to load and connect the COM add-in at startup. If the LoadBehavior is set to 2, the COM add-in is loaded, but its IDTExtensibility.OnConnection method is never called, which effectively amounts to the COM add-in's being disabled.

Table 23.1. Possible Values for LoadBehavior

Value	Description
0	Disconnected. The COM add-in is not loaded.
1	Connected. The COM add-in is loaded.
2	Load at startup. The COM add-in will be loaded and connected when the host application starts.
8	Load on demand. The COM add-in will be loaded and connected when the host application requires it (for example, when a user clicks a button that uses functionality in the COM add-in).
16	Connect first time. The COM add-in will be loaded and connected the first time the user runs the host application after registering the COM add-in.

In addition to these keys, several entries under HKEY_CLASSES_ROOT\CLSID are made for the COM add-in, as shown in Figure 23.4. A unique ClassID (a GUID, which is a unique identifier that looks like {FEC2B9E793664AD2AD054CF0167AC9C6}) is created by Visual Studio. This ClassID is added as a key under the HKEY_CLASSES_ ROOT\CLSID path. This ClassID is registered so that it corresponds to the ProgID for the COM add-in (MyAddin2.Connect, in our example). The keys and values created under the ClassID key are described in more detail later in this chapter.

Figure 23.4. The registry entries for a COM add-in under the HKEY_CLASSES_ROOT\CLSID path