Office 2000 COM Add-Ins

[Previous] [Next]

When developing Office solutions, you probably want to extend existing Office applications—Outlook in this case—with new functionality. With Outlook 98, you could add new forms to your application's Outlook environment, but you could not easily add new toolbars or program your application to respond to events beyond the form events, such as Item_Open or Item_Read. Plus, if you really wanted to extend beyond forms, you had to write an Exchange Client Extension. Exchange Client Extension development involved strict requirements and coding practices, and any extensions had to be written using C/C++. This meant that as a Microsoft Visual Basic or VBA developer, you were stuck either hacking a solution together or not enhancing the functionality at all.

Office 2000 includes support for COM add-ins. A COM add-in is a dynamic-link library (DLL) that can be used in an Office 2000 application. COM add-ins are used to include additional functionality in an Office application. As you can guess by the name, a COM add-in can be built using any COM development tool, such as Visual Basic, Microsoft Visual C++, or even Microsoft Visual J++. Since COM add-ins are compatible with all Office products, you can design a COM add-in once and reuse it in other Office products. For example, you could write a COM add-in that customizes the toolbars in your applications by using the CommandBar object model, which is shared across all of the Office products.

In this chapter, we'll look at a COM add-in that cannot be used across all the Office applications since it does call specific Outlook functionality. However, the concepts required to build this COM add-in can be applied to any add-in designed for other Office applications.

COM add-ins are registered specifically to be loaded by Office 2000 applications. Since COM add-ins are designed as DLLs, they will run in the same process as the host application. One benefit of an in-process add-in is that it has efficient access to the object model of the host application, allowing the add-in to quickly call methods and properties or to receive events from the host application. One potential caution to running an add-in in the same process space as the host is that you're in danger of slowing down or even crashing the host application. Keep this in mind during development.

Deciding Whether to Write a COM Add-In

You need to consider a number of issues when deciding whether to develop a COM add-in. Some of the functionality COM add-ins provide in Outlook is similar to other Microsoft Exchange Server and Outlook development technologies, such as the Event Scripting Agent, which we'll discuss in Chapter 13. For this reason, I've provided three test questions to help you determine whether to create a COM add-in or use another technology.

First, do you need to receive events when the Outlook client is not running? The life span of your COM add-in is controlled by Outlook. When the Outlook process is running, your COM add-in can run and receive events. When Outlook is not running, your add-in is also not running. If you need to receive events when the Outlook client is not running, you might want to consider using the Event Scripting Agent; because your agent runs on the server, it will always receive events while the server is running. In Chapter 10, we'll examine a COM add-in that notifies users when an item in a folder changes—functionality that might be better implemented by using the Event Scripting Agent.

The second test question to answer is this: is performance a big concern for your application? If so, you should use an add-in because it is loaded in-process with Outlook, but be aware that you must use defensive coding practices to prevent crashing Outlook. Don't create an add-in that performs expensive lookups or data retrievals when starting, because Outlook will wait for it to finish before continuing.

Third, is your application event-driven? Outlook will fire a number of new events that your COM add-in can implement and handle. These new events allow you greater control over the Outlook user interface and Outlook data.

Developing a COM Add-In

If your application passes my three test questions, start developing your COM add-in! It is actually quite easy as Visual Basic has some features that can get you up and developing in a matter of minutes. In this section, we'll take a look at how to start developing COM add-ins, and then we'll review the new features of the Outlook object model that you can employ in your COM add-ins.

Before you can begin creating an add-in, you must start Visual Basic 5.0 or a later version and select an ActiveX DLL project. After the new project loads, you must select Microsoft Add-In Designer from the Project/References dialog box, as shown in Figure 8-1. This library contains the necessary interfaces for your COM add-ins.

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

Figure 8-1. Select Microsoft Add-In Designer from the Project/References dialog box.

Figure 8-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 8-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.

OnConnection event

The OnConnection event is called when your add-in is first loaded or connected to—for example, when Outlook starts or when the user selects to load your COM add-in. The user can select your add-in in the COM Add-Ins dialog box in Outlook 2000. You can access this dialog box in Outlook by choosing Options from the Tools menu, clicking the Other tab, clicking the Advanced Options button, and clicking COM Add-Ins. The COM Add-Ins dialog box is shown in Figure 8-3.

Figure 8-3. The COM Add-Ins dialog box in Outlook 2000, where users can add or remove COM add-ins. Using the registry, you can force your add-ins to always load no matter what the user selects.

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 four 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 2000 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 at the time 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 2000 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 these constants: 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 unchecking 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 2000 add-ins, this parameter should be ignored.

Use the OnDisconnection event to restore any changes made to the application or to perform general cleanup for your application. Make sure you destroy any Inspector or Explorer objects that you create since Outlook will not properly close if any of these objects still exist.

OnStartupComplete event

In the case where 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 will not occur when a user selects to load the add-in from the COM Add-Ins dialog box after the application has already loaded. In that case, the OnConnection event will fire. The OnStartupComplete event procedure takes one parameter, Custom(), which you should ignore.

In this event procedure, place code that interacts with the application and 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 for Chapter 10, 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 is fired when the application is about to shut down and is called before the OnDisconnection event. Even after the OnBeginShutdown event 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 your open Explorer or Inspector objects because your Outlook COM add-in will not correctly shut down if any Explorer or Inspector objects are left open.

OnAddInsUpdate event

The OnAddInsUpdate event is fired whenever 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 upon which your add-in is dependent is connected. Once the dependent add-in 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 based on 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

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

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

Before writing this information to the registry, you must first 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 he or she wants to load the add-in. The model you select determines where in the registry the information for your add-in has to 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

Then you must lock down the registry because the COM Add-Ins dialog box cannot unload add-ins registered there. If you want to give your users the option to specify whether they want the add-in loaded and to choose their own settings for the add-in, install your add-in under this key:

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

This location allows per-user settings for the add-in. An example of registering your add-in under this key is shown in Figure 8-4.

Figure 8-4. This registry shows an add-in loaded under the key \HKCU\Software\Microsoft\Office\Outlook\AddIns. Registering your add-ins under this key will allow per-user settings.

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 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 file (.reg) 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\9.0\Outlook\Security 

By assigning 0 to DontTrustInstalledFiles, you are specifying that Outlook trust all installed add-ins. A value of 1 specifies to not trust all add-ins.

Debugging Your COM Add-In

Debugging your add-in using Visual Basic 6.0 is easy. All you need to do is write your add-in, register it, set some breakpoints on the code statements you are interested in, and then run the add-in in the Visual Basic 6.0 environment. In the Project Properties dialog box, shown in Figure 8-5, you can set some debugging options. You can specify whether you want to wait for the component to be created by the host application or you want Visual Basic to start an instance of the host application for you. Most times, I specify to wait for the components to be created by the host application. After Outlook starts and creates the COM add-in, the code in the add-in will execute and stop on encountered breakpoints. You can then step through your code in the Visual Basic Editor.

Figure 8-5. The Debugging tab of the Project Properties dialog box in Visual Basic version 6.0. You can specify how you want Visual Basic to debug your ActiveX DLL.

When debugging, be aware that message boxes in your add-in will appear in the Visual Basic development environment, not Outlook. If Outlook stops responding, you should switch to Visual Basic to see whether a message box is visible and waiting for you to respond.

WARNING

---

One thing to watch out for in your COM add-ins is references to Inspector or Explorer objects in your code. If you do not properly destroy your variables, Outlook will exit but will stay in memory. Even if you set the variables holding references to these objects in your OnBeginShutdown procedure to Nothing, Outlook will still stay in memory. For this reason, both the Explorer and Inspector objects implement a Close event. You should add code to this event to destroy your references and check for any remaining Explorer or Inspector objects. If you find no Inspector objects and only one Explorer object, it's a sign that Outlook is properly shutting down.

Using COM Add-Ins from Custom Outlook Forms

There are many ways you can leverage COM add-ins from Outlook forms. One of the best ways is to use them to add functionality that might not be very easy to implement in Microsoft Visual Basic Scripting Edition (VBScript) or that might be very expensive to create. For example, you could create a CDO session in a COM add-in and then share that CDO session across multiple Outlook applications so that each application does not have to create and destroy a CDO session. By using VBScript, you can access the collections of COM add-ins available on your local machine and call public methods or set public properties on these add-ins. Since you can write add-ins in Visual Basic or Visual C++, you can implement advanced functionality that would be difficult to implement with VBScript. Furthermore, a COM add-in can provide a library of functions that you can reuse in all your custom Outlook forms.

Figure 8-6 shows a sample Outlook form that uses a COM add-in to launch other executable programs. Since VBScript doesn't support the Shell function, you can leverage the Shell function in your COM add-in.

Figure 8-6. A simple Outlook form that uses VBScript to leverage a COM add-in. From this form, you can launch any executable you need.

Take a look at the following code from the Outlook form in Figure 8-6. Notice how you can access the COMAddins collection to retrieve a list of the COM add-ins on your machine. You can then check whether the COM add-in you're interested in is loaded and connected in Outlook. To retrieve a COM add-in, use the Item method on the collection and either pass in the index of your add-in in the collection or pass a string that specifies the ProgID of the add-in. Notice how I use the GetObject method with the ProgID of the COM add-in. You would think that I could simply use the Object property of the COM add-in object that corresponds to my add-in. However, this technique didn't work on my test machines. If it works for you, by all means use this method. Otherwise, you should use the workaround in the code to make the COM add-in library work.

 Dim oCOMAddinObj Dim oCOMAddin Sub cmdLaunchWord_Click Launch "winword" End Sub Sub cmdLaunchCalc_Click launch "calc" end sub Sub cmdLaunchApp_Click Launch item.userproperties.find("strAppPath").value end sub Function Item_Open() 'On error resume next err.clear 'Try to get a reference to the COM add-in set oCOMAddin = Application.COMAddIns.Item("OutlookHelper.Library") if err.number <> 0 then Msgbox "There was an error retrieving a reference to the COM " _ & "Add-in Helper Library! Closing form!" Item_Open = False exit function end if 'Check to see whether the COM add-in is connected if oCOMAddin.Connect = False then msgbox "You must connect the COM Add-in before using this app!" Item_Open = False exit function end if 'Get the real COM add-in object 'This doesn't work in Outlook! set oCOMAddinObj = _ Application.COMAddins.Item("OutlookHelper.Library").object 'Workaround: use GetObject set oCOMAddinObj = GetObject("","OutlookHelper.Library") End Function Sub Launch(strAppPath) 'Get the Windows style iStyle = item.userproperties.find("strWindowsStyle").value iError = oCOMAddinObj.CustomShell(strAppPath, iStyle) if iError = 0 then msgbox "Error launching application!" end if end Sub 

In the next example, the add-in doesn't do much besides add a single public function named CustomShell that the user can call. This function leverages the Shell function in Visual Basic and allows you to shell out to another program. The function also provides a bit of error checking just in case some bogus values get past the Outlook test form. If the add-in successfully shelled out to executable, it returns the ID of the executable. If not, it returns zero.

 Implements IDTExtensibility2 Dim oApp As Outlook.Application 'Global Outlook Application Object Private Sub IDTExtensibility2_OnAddInsUpdate(custom() As Variant) End Sub Private Sub IDTExtensibility2_OnBeginShutdown(custom() As Variant) Set oApp = Nothing End Sub Private Sub IDTExtensibility2_OnConnection( _ ByVal Application As Object, _ ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, _ ByVal AddInInst As Object, custom() As Variant) Set oApp = Application End Sub Private Sub IDTExtensibility2_OnDisconnection( _ ByVal RemoveMode As AddInDesignerObjects.ext_DisconnectMode, _ custom() As Variant) End Sub Private Sub IDTExtensibility2_OnStartupComplete(custom() As Variant) End Sub Public Function CustomShell(strAppPath, iWindowStyle) If strAppPath = "" Then 'Return back an error Err.Raise vbObjectError + 513, "Shell Function", "A blank " _ & "pathname was passed!" Exit Function Else 'Check iWindowStyle If CInt(iWindowStyle) < 0 Or CInt(iWindowStyle) > 6 Then 'Make it normal with focus iWindowStlye = vbNormalFocus End If 'Try to execute the command and return the value iReturn = Shell(strAppPath, CInt(iWindowStyle)) CustomShell = iReturn End If End Function