Developing a COM Add-In

If your answers to the three questions indicate that you should use a COM add-in, development is actually quite straightforward. Visual Basic has some features that can get you up and developing in a matter of minutes. In this section, I'll take a look at how to start developing COM add-ins, and then I'll review the features of the Outlook object model that you can employ in your COM add-ins.

Before you begin developing an add-in, you must create an ActiveX DLL project in Visual Basic (version 5.0 or later). After the project loads, select Microsoft Add-In Designer in the Project/References dialog box, as shown in Figure 7-1. This library contains the interfaces for your COM add-ins. (Another option is to use the add-in project; instead of selecting ActiveX DLL as your project type, select Add-in to open the Add-In Designer.)

Figure 7-1: The Microsoft Add-In Designer in the Project/References dialog box

In your Visual Basic code, you must type Implements IDTExtensibility2 to see the IDTExtensibility2 interface's events in the Procedure drop-down list in the Visual Basic code window. Figure 7-2 shows the code window with the IDTExtensibility2 event procedures added.

Figure 7-2: The Visual Basic 6.0 code window with the five event procedures for the IDTExtensibility2 interface

The IDTExtensibility2 Events

As you can see in Figure 7-2, IDTExtensibility2 provides five events for you to use in your COM add-in: OnConnection , OnDisconnection , OnStartupComplete , OnBeginShutdown , and OnAddInsUpdate . Let's examine each of these events in detail.

OnConnection Event

The OnConnection event is called when your add-in is first loaded or a connection to it is established ”for example, when Outlook starts or when the user chooses to load your COM add-in. The user can select your add-in in the COM Add-Ins dialog box in Outlook (as shown in Figure 7-3). You open this dialog box by choosing Options from the Tools menu, clicking on the Other tab, clicking the Advanced Options button, and clicking COM Add-Ins.

Figure 7-3: The COM Add-Ins dialog box, in which users add or remove COM add-ins

The OnConnection event procedure is a great place to grab and store the Outlook Application object for use in your code later. When an OnConnection event occurs, the OnConnection event procedure is passed the following four parameters: Application , ConnectMode , AddInInst , and Custom() . The Application parameter is a reference to the Outlook Application object. The ConnectMode parameter describes the way in which the COM add-in was loaded. The ConnectMode parameter is a Long data type that can be set to one of the following constants: ext_cm_AfterStartup , ext_cm_CommandLine , ext_cm_External , or ext_cm_Startup . The constants ext_cm_CommandLine and ext_cm_External do not apply to Office add-ins. The ext_cm_AfterStartup and ext_cm_Startup constants are subtly different from each other. The ConnectMode parameter is set to ext_cm_AfterStartup when the add-in is connected after Outlook starts or when the Connect property of the add-in is set to True . Usually, the ConnectMode parameter is set to ext_cm_AfterStartup when the user connects the add-in manually through the user interface. The ConnectMode parameter is set to ext_cm_Startup when your add-in is connected when Outlook starts up. The AddInInst parameter passes an object that refers to the current instance of your COM add-in. The Custom parameter is an array of Variant data types that can hold user-defined data for your add-in. For Office add-ins, this parameter should be ignored.

OnDisconnection Event

The OnDisconnection event occurs when your COM add-in is being disconnected from the application. The OnDisconnection event procedure is passed two parameters: RemoveMode and Custom . The RemoveMode parameter, which is a Long data type, specifies how your add-in was disconnected and can be set to ext_dm_HostShutdown or ext_dm_UserClosed . As you can guess by their names , ext_dm_HostShutdown indicates that the add-in is disconnected by the host shutting down, and ext_dm_UserClosed indicates either that a user is deselecting the add-in's check box in the COM Add-Ins dialog box or that the Connect property of the add-in is set to False .

The second parameter, Custom , is an array of Variant data types that can hold user-defined data for your add-in. For Office add-ins, this parameter should be ignored.

You use the OnDisconnection event to restore any changes made to the application or to perform general cleanup for your application. Be sure to destroy any Inspector or Explorer objects that you create because Outlook will not properly close if any instances of these objects still exist. The easiest way to do this is to check the Explorers and Inspectors collections to see if any of the objects exist.

Also note that in Outlook 2003, the Application's Quit event is fired earlier in the shutdown of Outlook. You can also use this event to destroy any references to Outlook objects that you have in your programs. However, because this applies only to Outlook 2003 and has not yet been back-ported to previous versions of Outlook, you might want to implement both options in your COM add-ins ”attempt to destroy objects in the Quit event and also in OnDisconnection . Just be sure to have good error handling to catch any errors that occur in either event.

OnStartupComplete Event

If a COM add-in connects at the time the host application is started, the OnStartupComplete event fires when the host has completed all of its startup routines. The OnStartupComplete event does not fire if a user chooses to load the add-in from the COM Add-Ins dialog box after the application has already started. In that case, the OnConnection event fires. The OnStartupComplete event procedure takes one parameter, Custom , which you should ignore.

In the OnStartupComplete event procedure, you place code that interacts with the application and that should not be run until the application finishes loading. This event procedure is a good place to set some of your local and global variables to their corresponding Outlook objects. In the COM add-in example in Chapter 8, the OnStartupComplete event procedure searches the Outlook groups for a shortcut to the Account Tracking application and also has code to manipulate the command bars in the user interface.

OnBeginShutdown Event

The OnBeginShutdown event fires when the application is about to shut down; it is called before the OnDisconnection event. Even after OnBeginShutdown fires, you still have full access to the Outlook object model, so you can save your settings to the registry or a file, or save any changes to your objects, before your objects are unloaded.

Note  

If you are using Explorer or Inspector objects in your COM add-in, listen for the Close event on these objects. When your application receives this event, it should destroy all open Explorer or Inspector objects because your Outlook COM add-in will not shut down correctly if any Explorer or Inspector objects are left open. (Chapter 6 covers the Explorer and Inspector objects.)

OnAddInsUpdate Event

The OnAddInsUpdate event fires when the list of COM add-ins is updated. When another add-in is connected or disconnected, this event occurs in any other connected COM add-in. You can use this event to ensure that any other add-in that your add-in depends on is connected. Once the add-in that yours depends on is disconnected, you can disable your functionality or display a dialog box to warn the user to reconnect the other add-in. The OnAddInsUpdate event handler includes one parameter, Custom , which your application should ignore.

Registry Settings for COM Add-Ins

Now that you know which events fire for add-ins, you need to know how to register and load the add-ins. Outlook decides which add-ins to load on the basis of settings in the user's registry. If your add-in is not specified correctly in the registry, Outlook will not be able to load your add-in, nor will your add-in appear in the COM Add-Ins dialog box.

Registering Your Add-In

After you compile your add-in, you must register the add-in DLL for your add-in to work correctly. To do this, you use the Regsvr32 command and specify the path to your DLL. This registers your DLL under the HKEY_CLASSES_ROOT subtree in the registry. If you are deploying your add-in to multiple machines, you must figure out how to install your DLL on those machines. One way is to use logon scripts to copy and register the DLL. Another way is to deploy your add-in using the Visual Basic deployment and setup tools, an MSI, or Microsoft Systems Management Server (SMS).

After your COM add-in DLL is registered, you must add some settings to the registry on the local machine. These settings include the add-in's name , a description of the add-in, and the add-in's target application, initial load behavior, and connection state.

Before writing this information to the registry, you must decide how you want to deploy your add-in: you can either force all users to use your add-in or allow each user to decide whether to load it. The approach you use will determine where in the registry the information for your add-in must be written. If you want to ensure the add-in is always loaded and that every user on a machine has access to it, you must register it under the key:

 \HKLM\Software\Microsoft\Office\<application>\AddIns 

Installing your add-in here effectively locks down the COM Add-Ins dialog box because the user cannot unload add-ins that are registered here.

If you want to give your users the option to specify whether to load the add-in and to choose their own settings for the add-in, install your add-in under the key:

 \HKCU\Software\Microsoft\Office\<application>\AddIns 

This location allows per-user settings for the add-in. An example of a registered add-in under this key is shown in Figure 7-4.

Figure 7-4: A registry key showing an add-in loaded under the key \HKCU\Software\Microsoft\Office\Outlook\AddIns

When you register your add-in under one of these registry keys, the information written to the key includes the following name/value pairs: Description , FriendlyName , and LoadBehavior . Description is a string type that provides a short description of the COM add-in. FriendlyName is a string that contains the name displayed in the COM Add-Ins dialog box. LoadBehavior is of type DWORD , where the value is an integer that specifies how to load your COM add-in. This integer can have a value of 0 for Disconnected, 1 for Connected, 2 for load on startup, 8 for load on demand, or 16 for connect first time. You can combine these values to create different types of load sequences. For example, if you assign the value 3 to LoadBehavior , the add-in will be loaded on startup as well as connected. If you assign 9 to the add-in, the add-in will be connected and demand-loaded when necessary, such as when the user clicks a button that uses code in the add-in.

The following code shows the content of a sample registry editor (.reg) file for a COM add-in:

 REGEDIT4      [HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\ Addins\Sample.MyAddIn] "FriendlyName"="My Sample Add-In" "Description"="Sample Outlook COM Add-In" "LoadBehavior"=dword:00000003 

Trusting Your COM Add-Ins

You can specify whether to trust all installed COM add-ins on a machine by setting the DWORD value DontTrustInstalledFiles under the following registry key:

 \HKCU\Software\Microsoft\Office\<version number>\Outlook\Security 

By assigning 0 to DontTrustInstalledFiles , you specify that Outlook should trust all installed add-ins. A value of 1 specifies not to trust all add-ins. By default, Outlook trusts all files and installed add-ins. But this does not mean that Outlook will run all macros by default. Macros are different from COM add-ins. There is another setting for macros ”the security level, which you can set to high, medium, or low. This setting controls whether signed, trusted macros are run.