Visual Studio Tools for Office: Using C# with Excel, Word, Outlook, and InfoPath [Electronic resources] نسخه متنی

How a COM Add-In 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 C# developer, you are writing a C# class that you will compile into an assembly (DLL). Through .NET's' COM interop support, your C# 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. However, it is still important to understand the anatomy of an add-in should you have to troubleshoot add-in issues.

Registry Location of a COM Add-In: 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 registryeither under HKEY_CURRENT_USER or under HKEY_LOCAL_MACHINE. To view the registry, choose Run from the Start menu of Windows and 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 per-user basis are found, as shown in Figure 23-1. COM add-ins should typically be installed on a per-user basis so that the add-in user settings will move with the user should the user log on to a different machine.

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

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

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 per-machine 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 Add-Ins dialog. 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 Add-In

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. This identifier is used by COM 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 Add-Ins dialog. Description is a string value that contains a more in depth description of the COM add-in. This description does not appear anywhere in the Office UI or COM Add-Ins dialog, 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 for 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 being disabled.

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 {FEC2B9E7-9366-4AD2-AD05-4CF0167AC9C6} ) is created by Visual Studio. This ClassID is added as a key under the HKEY_CLASSES_ROOT\CLSID path. This ClassID is registered so 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.