Tài liệu Module 10: Creating COM Add-ins docx

Module 10: Creating
COM Add-ins
Contents
Overview

1

Introduction to COM Add-ins

2

Developing a COM Add-in

8

Working with a COM Add-in Project

20

Working with Command Bars

25

Creating Custom Property Pages for
Outlook 2000

42

Lab A: Creating the MoveApp COM
Add-in

50

Lab B: Converting a Visual Basic for
Applications Macro to a COM Add-in

58

Review

69


Information in this document is subject to change without notice. The names of companies,
products, people, characters, and/or data mentioned herein are fictitious and are in no way intended
to represent any real individual, company, product, or event, unless otherwise noted. Complying
with all applicable copyright laws is the responsibility of the user. No part of this document may
be reproduced or transmitted in any form or by any means, electronic or mechanical, for any
purpose, without the express written permission of Microsoft Corporation. If, however, your only
means of access is electronic, permission to print one copy is hereby granted.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual
property rights covering subject matter in this document. Except as expressly provided in any
written license agreement from Microsoft, the furnishing of this document does not give you any
license to these patents, trademarks, copyrights, or other intellectual property.
 1999 Microsoft Corporation. All rights reserved.
Microsoft, Active Desktop, Active Directory, ActiveX, BackOffice, Developer Studio, FrontPage,
JScript, MSDN, MSN, NetMeeting, Outlook, PivotChart, PivotTable, PowerPoint, Visual Basic,
Visual C++, Visual FoxPro, Visual InterDev, Visual J++, Visual SourceSafe, Visual Studio,
Windows, Windows Media, and Windows NT are either registered trademarks or trademarks of
Microsoft Corporation in the U.S.A. and/or other countries.
The names of companies, products, people, characters, and/or data mentioned herein are fictitious

and are in no way intended to represent any real individual, company, product, or event, unless
otherwise noted.
Other product and company names mentioned herein may be the trademarks of their respective
owners.
Project Advisor: Janet Wilson
Project Lead and Instructional Designer: Anne Bockman (Excell Data Corporation)
Instructional Designers: Josh Barnhill (Volt Technical) and Jo Berry (Exchange)
Lead Program Manager: Greg Bott
Program Managers: Colleena Carr and Chris Boar (Intl Vendor)
Graphic Artist: Andrea Heuston (Artitudes Layout and Design)
Editing Manager: Lynette Skinner
Editor: Jennifer Kerns (S&T Onsite)
Copy Editor: Shari G. Smith (R & S Consulting)
Online Program Manager: Arlo Emerson (Aditi)
Production Support: Irene Barnett (Barnett Communications)
Manufacturing Manager: Bo Galford
Manufacturing Support: Mimi Dukes (S&T Onsite)
Development Services: Kimber Dodge
Lead Product Manager: Mary Larson
Group Product Manager: Robert Stewart


Module 10: Creating COM Add-ins

iii

Instructor Notes Module 10: Creating COM Add-ins
Presentation:
60 Minutes
Labs:

60 Minutes

This module presents Component Object Model (COM) add-ins as a way of
developing solutions for Microsoft® Outlook® 2000 and other Microsoft
Office 2000 applications.
At the end of this module, students will be able to write, debug, compile, and
register a COM add-in. They will also be able to use one of the shared Office
object models, Command Bars, to programmatically create and modify toolbars
and menus. Students will also be able to create a custom property page for
Outlook 2000 by using a COM add-in.

Materials and Preparation
This section provides you with the materials and preparation needed to teach
this module.

Materials
To teach this module, you need the following materials:
Microsoft PowerPoint® file 1593a_10.ppt
Module 10, “Creating COM Add-ins”

Preparation
To prepare for this module, you should:
Read all the materials for this module.
Read the instructor notes and margin notes for the module.
Complete the labs.


iv

Module 10: Creating COM Add-ins

Module Strategy
Use the following strategy to present this module:
Introduction to COM Add-ins
Describe what COM add-ins are, how they differ from the add-in
architecture found in previous versions of Office, and when students should
consider writing code in a COM add-in. Compare COM add-ins and COM
.exe (executable) projects.
Developing a COM Add-in
Explain the purpose of the Add-in Designer and how it is used in a
Microsoft Visual Basic® for Applications project. Describe the property
settings in the Add-in Designer. Show how students can add code to the
class file for the designer.
Describe each of the five events supported by the IDTExtensibility2 library
and explain the type of code typically written to handle these events.
Working with a COM Add-in Project
Show the steps required in debugging a COM add-in. Describe the compile
options for COM add-ins. Explain how a COM add-in is registered on a
development computer and on a user’s computer.
Working with Command Bars
Provide an introduction to the CommandBar object, and describe the uses
of its most important properties and methods. Explain how to create, show,
hide, retrieve, and remove command bars.
Describe how to add controls to command bars and set properties for the
controls. Provide a detailed explanation of the process of adding command
bar buttons to the Outlook 2000 Inspector window toolbar from a COM
add-in.
Creating Custom Property Pages for Outlook 2000
Explain what custom property pages are and what they contribute to an
Outlook 2000 solution. Describe each of the four steps necessary to

implement a custom property page in Outlook 2000.


Module 10: Creating COM Add-ins

Overview
Slide Objective

To provide an overview of
the module topics and
objectives.

Lead-in

In this module, you will learn
about using COM add-ins
and working with Command
Bars.

Introduction to COM Add-ins
Developing a COM Add-in
Working with a COM Add-in Project
Working with Command Bars
Creating Custom Property Pages for Outlook 2000

At the end of this module, you will be able to:
Describe why it is usually more appropriate to create COM add-ins for your
Outlook 2000 solutions than to write Microsoft® Visual Basic® for
Applications code.
Build a COM add-in by using the Add-in Designer.

Perform the steps required to debug, compile, and register a COM add-in
within the Visual Basic Editor.
Modify and create command bars, toolbars, and pop-up menus.
Create a custom property page for a Microsoft Outlook® 2000 folder or the
Outlook 2000 application.

1


2

Module 10: Creating COM Add-ins

Introduction to COM Add-ins
Slide Objective

To outline this topic.

Lead-in

COM add-ins can be easily
integrated into a
collaborative solution and
are readily distributed to
users of your solution.

Comparing COM Add-ins and Visual Basic for
Applications Projects
Comparing COM Add-ins to Other Technologies
Viewing Available COM Add-ins

You can write code for your Outlook 2000 solutions in forms, a Visual Basic
for Applications project, or a COM add-in. COM add-ins provide a shared way
to develop code for use with all Microsoft Office 2000 applications. COM addins can be quickly developed and integrated into a collaborative solution by
using any development environment that supports COM add-in technology.
Whether you decide to use COM add-ins will depend on how the code will be
used by the solution.


Module 10: Creating COM Add-ins

3

Comparing COM Add-ins and Visual Basic for Applications Projects
Slide Objective

To compare COM add-ins
and Visual Basic for
Applications projects in
Outlook 2000.

Lead-in

Code distribution plays the
most important role in
determining whether to use
a COM add-in or a Visual
Basic for Applications
project for development.

Using a Visual Basic for Applications Project in
Outlook 2000
Used to automate procedures in Outlook 2000 to
increase a user’s personal productivity
Using a COM Add-in
Self-registering and easily distributed, does not affect
the Outlook 2000 Visual Basic for Applications projects
of users
A common add-in architecture shared across all
Office 2000 applications
How COM Add-ins Can Be Implemented
As a .dll file or .exe file

In Outlook 2000, you can write Visual Basic for Applications code in either a
COM add-in or a Visual Basic for Applications project.

Using a Visual Basic for Applications Project in
Outlook 2000
A Visual Basic for Applications project is used to automate procedures in
Outlook 2000 to increase a user’s personal productivity. Sharing this project
with other users requires that you import the project file into each Outlook 2000
client where it overwrites all existing Visual Basic for Applications procedures.
Within Outlook 2000, all code is stored in a single Visual Basic for
Applications project—VbaProject.otm.
Note Other Microsoft Office applications store Visual Basic for Applications
projects differently. Each Microsoft Excel, Microsoft Word, Microsoft Access,
or Microsoft PowerPoint® file that you create contains its own Visual Basic for
Applications project.
Before you decide to create a Visual Basic for Applications procedure, you
should consider the limitations of distributing these procedures. If you plan to

distribute the code, you should use a COM add-in instead. If you have already
created a Visual Basic for Applications routine that you want to include in your
solution, you can wrap the routine as a COM add-in.


4

Module 10: Creating COM Add-ins

Using a COM Add-in
To enable multiple users to access the functionality of your application, you can
encapsulate the code within a COM add-in. COM add-ins are self-registering
and are easily distributed, without affecting the Outlook 2000 Visual Basic for
Applications projects of individual users.
In the past, if you wanted to extend Word, Excel, and PowerPoint with the same
solution, you would need to write three separate implementations of the add-in.
All Office 2000 applications now support a common add-in architecture and
development environment. You can write a single COM add-in that will run in
any Office 2000 application. The add-in determines which application has
called it and runs code by using the object model features specific to the
application. The COM add-in can also share common code. For example, place
code that customizes a toolbar within a shared code module that uses the
CommandBar object. Then, the Add-in Designer of each Office application
could invoke the shared code module within the context of the application.
Delivery Tip

Exchange Client Extensions
have to be developed by
using C++ so they are
typically more difficult to

implement than COM addins, which can be developed
in any language that
supports COM add-in
technology. ECE is still an
appropriate solution when
developing for Outlook 97 or
Outlook 98 clients, who do
not support COM add-ins.
ECE also support events
that are not found in COM
add-ins.

How COM Add-ins Can Be Implemented
A COM add-in can be implemented as a dynamic-link library (.dll) file or as an
executable (.exe) file. Because .dll files generally run more efficiently than .exe
files, this module concentrates on building COM add-ins as .dll files.
Note COM add-ins replace solutions developed by using Exchange Client
Extensions.


Module 10: Creating COM Add-ins

5

Comparing COM Add-ins to Other Technologies
Slide Objective

To list the issues to consider
when deciding to write COM
add-ins.

Lead-in

Writing code in a COM addin is not always the best
approach. There are several
issues to consider when
deciding to write a COM
add-in.

Event Handling Considerations
Outlook 2000 fires events that a COM add-in can handle
The life span of a COM add-in is controlled by the
Outlook 2000 client
Use other technologies when you must trap events that
occur when Outlook 2000 client is not running
Performance Considerations
A COM add-in implemented as a .dll file performs better
than other technologies
Avoid COM add-ins that perform extensive data access
operations on startup

You need to consider a number of issues when deciding whether to develop a
COM add-in. Some of the functionality that COM add-ins provide in
Outlook 2000 is similar to other Microsoft Exchange Server and Outlook 2000
development technologies, such as Microsoft Exchange Server Scripting Agent.
(A scripting agent is a server-side script that runs as a result of events occurring
in folders.)

Event Handling Considerations
Outlook 2000 (and any other host Office application) will fire events that a

COM add-in can implement and handle. These events allow the COM add-in to
gain control over the Outlook 2000 user interface and Outlook 2000 data.
The life span of a COM add-in is controlled by Outlook 2000. When the
Outlook 2000 process is running, the COM add-in can run and receive events.
When Outlook 2000 is not running, the add-in does not run.
If you need to receive events when the Outlook 2000 client is not running, you
should consider using a scripting agent. Because the scripting agent runs on the
server, it will continue to receive events as long as the server is running.


6

Module 10: Creating COM Add-ins

Performance Considerations
A COM add-in that is implemented as a .dll will run faster than some other
technologies because it is loaded in process with Outlook 2000. However, you
should be aware that you must use defensive coding practices when writing
COM add-ins to prevent crashing the host application.
Also, you should not create an add-in that performs extensive data access
operations, such as table lookups or data retrievals, when it starts, because
Outlook 2000 will wait for the operation to finish before continuing. You can
avoid this situation by writing a very simple COM add-in that loads when
Outlook 2000 starts and performs such tasks as adding a command to a menu.
When invoked by the user, this add-in can call a more complex add-in that
performs the more essential tasks of the application, such as database
operations, only when the user chooses to run the add-in. An example of a
solution that uses this technique is the Team Folder Wizard.

Module 10: Creating COM Add-ins

Viewing Available COM Add-ins
Slide Objective

To show the COM Add-ins
dialog box.

Lead-in

To see the COM add-ins
loaded in an Office
application, you must first
add the COM Add-ins
command to a menu or a
toolbar.

You can view, add, or delete the COM add-ins available to Outlook 2000 by
displaying the COM Add-ins dialog box.

Viewing COM Add-ins Available in Outlook 2000
To view COM add-ins available in Outlook 2000:
1. On the Tools menu, select Options.
2. In the Options dialog box, click the Other tab.
3. Click Advanced Options.
4. In the Advanced Options dialog box, click COM Add-ins.
You can also add a toolbar button or menu command to view the COM add-ins
available to an Office application. This method is required to view the COM
Add-ins dialog box in Office applications other than Outlook 2000.

Viewing COM Add-ins Available in an Office Application
To view COM add-ins available in an Office application:
1. On the Tools menu, click Customize.
2. Click the Commands tab.
3. In the Categories list box, click Tools.
4. In the Commands list box, click COM Add-ins.
5. Drag the COM Add-ins command to a toolbar or menu, and then click
Close.

7


8

Module 10: Creating COM Add-ins

Developing a COM Add-in
Slide Objective

To outline this topic.

Lead-in

You develop COM add-ins
by using an Add-in Designer
to set initial properties of the
add-in and then write code
to handle add-in specific
events.

Creating an Add-in Project
Working with the Add-in Designer
Implementing the IDTExtensibility2 Library
Handling IDTExtensibility2 Events
Creating COM Add-ins for Multiple Applications
Closing a COM Add-In

You can build COM add-ins in Office 2000 Developer or by using any other
development environment that supports add-in technology, such as Visual Basic
or Microsoft Visual C++®.
Office 2000 Developer includes all of the applications found in Office 2000
Premium, plus enhanced productivity tools and documentation to make
developers more productive. The following tools and materials work from any
Visual Basic for Applications–based host (that is, Office and third-party
applications).
COM Add-in Designer. This tool allows developers to create and debug
COM add-ins without leaving the Visual Basic for Applications
development environment. COM add-ins are developed by using the Add-in
Designer to set initial properties of the add-in and then writing code to
handle add-in specific events.
Visual Basic for Applications productivity tools. These tools include add-ins
such as the Code Librarian, which provides a searchable database that
enable development teams to share a wide range of reusable code easily.
These also include add-ins to automate code documentation, error-handling
routines, and automatic string parsing, as well as other tools for enhancing
productivity.
Learning materials and programming resources. Also included with
Office 2000 Developer are the MSDN™ Library, hard-copy documentation
and prewritten code for standard routines for Visual Basic for Applications,
and Visual Basic.

Module 10: Creating COM Add-ins

9

Creating an Add-in Project
Slide Objective

To show the Add-in
Designer project window.

Lead-in

When you add an add-in
project to the Visual Basic
Editor, the Add-in Designer
displays.

AddInPRoject1 - AddInDesigner1 (AddInDesigner)
General Advanced
Addin Display Name
New Outlook COM Add-in
Addin Description

Application
Microsoft Outlook
Application Version
Microsoft Outlook 9.0
Initial Load Behavior

Startup

OK

Cancel

Help

Office 2000 exposes an extensibility interface that enables you to develop
solutions for Office 2000 with any programming language that can create COM
components. In addition, these add-ins all use the same extensibility model and
user interface to connect and disconnect to any and all Office host applications.
The Office 2000 extensibility interface is exposed to an application by using the
Add-in Designer. An Add-in Designer is a file included with the add-in
template project that helps you create and register your COM add-in. You can
create a COM add-in without including the Add-in Designer, but the Add-in
Designer simplifies the process of creating and registering the add-in. You can
use the Add-in Designer to specify important information for your COM add-in,
such as its name and description, which applications it is to run in, and how it
loads in that application. You add a new Add-in Designer to the project for each
application you plan to target in the add-in.
The Add-in Designer template is available in Office 2000 Developer and Visual
Basic version 6.0.

Adding a COM Add-in Project to a Visual Basic for Applications Project
To add a COM add-in project to a Visual Basic for Applications project:
1. On the File menu, click New Project.
2. In the New Project dialog box, click Add-in Project, and then click OK.
The Visual Basic Editor adds a COM add-in project to your Visual Basic for
Applications project and displays the Add-in Designer.

10

Module 10: Creating COM Add-ins

Working with the Add-in Designer
Slide Objective

To list the properties that
you can set in the Add-in
Designer and to outline
important topics associated
with the Add-in Designer.

Setting Add-in Designer Properties
AddIn Display Name
AddIn Description

Lead-in

Application

The General tab contains
basic information that the
Add-in Designer uses to
register the COM add-in.

Application Version
Initial Load Behavior

Specifying the Initial Load Behavior
Writing Code in the Add-in Designer

Use the Add-in Designer to begin the development process for an add-in by
setting the properties that determine name, description, target application, the
version, and the load behavior. The designer contributes code to the .dll or .exe
of the add-in to register the add-in correctly for the target application.

Setting Add-in Designer Properties
The following table lists and describes the information in the General tab of the
Add-in Designer. The Visual Basic Editor uses this information when it
registers the COM add-in on a user’s computer.
Add-in Designer settings

Description

AddIn Display Name

Lists the name that will appear in the COM Add-ins
dialog box in the target Office application.

AddIn Description

Describes the purpose of the COM add-in. The user will
not see this description.

Application

Choose the application that you want to target with your
COM add-in.

Application Version

After you choose the application, the Add-in Designer
will automatically enter the appropriate Office 2000
application version into this box.

Initial Load Behavior

Specifies how the COM add-in will load in the target
application. Settings include: None, Startup, Load on
demand, and Load at next startup only.


Module 10: Creating COM Add-ins

11

Specifying the Initial Load Behavior
When a COM add-in has been properly registered, it will be available to
whatever application is specified in the Add-in Designer that the project
contains. The display name of the registered COM add-in will appear in the
COM Add-ins dialog box.
Selecting the check box next to an add-in in the COM Add-ins dialog box
loads (connects) the add-in and makes it available to the user; clearing the
check box unloads (disconnects) the add-in, so that it cannot be run.
As the developer, you specify when a COM add-in should be loaded. You do
this in the Initial Load Behavior list in the Add-in Designer. You can specify
that an add-in be loaded in one of the following ways:
None. The COM add-in loads only if the user enters the COM Add-ins

dialog box and enables it.
Load on demand. The COM add-in loads only when the user loads it from
the COM Add-ins dialog box, or when Visual Basic for Applications code
loads it by setting the Connect property of the corresponding COMAddIn
object.
Startup. The COM add-in loads every time the application starts.
Load at next startup only. The COM add-in loads the first time the
application starts, so that it can create a toolbar button or menu item for
itself. After that, the add-in is loaded only when the user requests it by
clicking the menu item or button.

Writing Code in the Add-in Designer
After you have specified general information for a COM add-in in the Add-in
Designer, you can begin writing code in the Add-in Designer’s class module.
To view the Add-in Designer’s class module, right-click the Add-in Designer in
the Project Explorer, and then click View Code on the shortcut menu.
Code that handles the integration of the add-in with the host application is
hidden from view and cannot be modified. However, in the Add-in Designer’s
class module, you can write code that performs the custom functionality of your
add-in. For example, code that runs when the add-in is loaded or unloaded
resides in the Add-in Designer’s class module. If the add-in contains forms, the
Add-in Designer may also contain code to display the forms.


12

Module 10: Creating COM Add-ins

Implementing the IDTExtensibility2 Library
Slide Objective

To describe the
IDTExtensibility2 library and
how it is implemented.

Lead-in

By implementing the
IDTExtensibility2 library, you
can instruct your COM addin to respond to events fired
by the host application.

Function of the IDTExtensibility2 Library Interface
Provides a programming interface for integrating COM
add-ins with their host applications
Contains preconfigured procedure templates used to
manage COM add-ins in Office

Using Office 2000 Developer or Visual Basic 6.0
Automatically implemented if the Add-in Designer is
used

Using Visual Basic 5.0
Must be manually implemented

A COM add-in has events that you can use to run code when the add-in is
loaded or unloaded, or when the host application has finished starting up or
shutting down. To use these events, you must first implement the
IDTExtensibility2 library.

Function of the IDTExtensibility2 Library Interface
The IDTExtensibility2 interface contains events that Office calls when an addin is connected to an Office application, whether through the COM Add-ins
dialog box or some other manner. The IDTExtensibility2 interface contains
preconfigured procedure templates (which include their parameter lists) that
you need to manage add-ins in Office.

Using Office 2000 Developer or Visual Basic 6.0
When you create an add-in by using the Add-in Designer template in
Office 2000 Developer or Visual Basic 6.0, the IDTExtensibility2 library is
implemented for you in the Add-in Designer’s class module. This class module
is called AddInInstance.


Module 10: Creating COM Add-ins

13

Using Visual Basic 5.0
If you create the COM add-in Visual Basic version 5.0, you must implement the
IDTExtensibility2 library manually.

Manually Implementing the IDTExtensibility2 Library in Visual Basic 5.0
To Manually Implement the IDTExtensibility2 Library in Visual Basic 5.0:
1. On the Project menu, click References, and then select the Microsoft Addin Designer check box to set a reference to the library. If this library does
not appear in the list, click Browse and find the Msaddndr.dll file to add the
library to the list. By default this file is located in the subfolder
C:\Program Files\Common Files \Designer.
2. In the Declarations section of the Add-in Designer’s class module, add the
following code:
Implements IDTExtensibility2

3. In the Code window, click IDTExtensibility2 in the Object box. This
creates the OnConnection event procedure stub.
4. To create event procedure stubs for the four remaining event procedures,
click the events in the Procedure box in the Code window.
5. Add code or a comment to each of the five event procedures.
Note You must include the event procedure stub for each event provided by
the IDTExtensibility2 interface. If you omit any of the event procedures, your
project will not compile. If you are not adding code to an event procedure stub,
it is recommended that you add a comment; a single apostrophe (') is sufficient.


14

Module 10: Creating COM Add-ins

Handling IDTExtensibility2 Events
Slide Objective

To list the five events of the
IDTExtensibility2 library.

OnConnection

Lead-in

The IDTExtensibility2 library
exposes five events that you
can handle in your COM
add-in.

OnStartupComplete
OnAddInsUpdate
OnBeginShutdown
OnDisconnection

When you implement the IDTExtensibility2 library within a class module, the
library makes a set of five events available to the module. These are the events
that you use to control your COM add-in. You will frequently write code for the
OnConnection and OnDisconnection events to manage the functionality of your
COM add-in. While these are methods to the IDTExtensibility2 interface, to a
Visual Basic programmer they act and behave like events. That is, when an addin is connected to Office, the OnConnection method is called automatically,
similar to an event firing. When it is disconnected, the OnDisconnection
method is called automatically, and so forth.
The interface’s events are exposed through the Implements statement. When
the Implements IDTExtensiblity2 syntax is typed in the Declarations section
of the Class module that handles an add-in’s events, the interface’s events
become available for use through the module’s Procedure and Object dropdown boxes in Visual Basic. To add the code to the module, simply select it
from the drop-down box.
The IDTExtensibility2 interface currently contains five events: OnConnection,
OnStartUpComplete, OnAddInsUpdate, OnBeginShutdown, and
OnDisconnection.

OnConnection Event
The OnConnection event occurs when the COM add-in is loaded (connected).
An add-in can be loaded in one of the following ways:
The user starts the host application and the add-in’s load behavior is
specified to load when the application starts.
The user loads the add-in from the COM Add-ins dialog box.
The Connect property of the corresponding COMAddIn object is set to

True.


Module 10: Creating COM Add-ins

15

You can place code in the OnConnection event that starts the functionality for
your COM add-in. For example, you can create a new menu bar that provides
specific features needed by your Office solution.
The following four parameters pass to the OnConnection event procedure:
Application. This parameter is a reference to the Outlook 2000 Application
object.
ConnectMode. This parameter describes the way in which the COM add-in
was loaded.
AddInInst. This parameter passes an object that refers to the current instance
of your COM add-in.
Custom. This parameter is an array of Variant data types that can hold userdefined data for your add-in.
The following example displays a message box in response to the
OnConnection event.
Private Sub IDTExtensibility_OnConnection(ByVal _
VBInst As Object, ByVal ConnectMode As _
VBIDE.vbext_ConnectMode, ByVal AddInInst As _
VBIDE.AddIn, custom() As Variant)
MsgBox "Add-in is now connected"
End Sub

OnStartupComplete Event
In the case where a COM add-in loads 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 is already loaded. In that case, the OnConnection event will fire.
Place code in the OnStartupComplete event that interacts with the application
but should not 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 2000 objects.

OnAddInsUpdate Event
The OnAddInsUpdate event fires 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.

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.


16

Module 10: Creating COM Add-ins

OnDisconnection Event
The OnDisconnection event occurs when the COM add-in is unloaded. Place

code in the OnDisconnection event that removes the functionality of your COM
add-in. For example, you can remove a menu bar or menu option. Because your
COM add-in will remain available while Outlook 2000 runs, it is important to
remove any functionality created by your COM add-in that will not work in
other documents that the user might create after using your solution.
The following two parameters pass to the OnDisconnection event procedure:
RemoveMode. This parameter specifies how your add-in was disconnected
and can be set to these constants: ext_dm_HostShutdown or
ext_dm_UserClose.
Custom. This parameter is an array of variant data types that can hold userdefined data for your add-in. (For Office 2000 add-ins, this parameter
should be ignored.)
The following example displays a message box in response to the
OnDisconnection event.
Private Sub IDTExtensibility_OnDisconnection(ByVal _
RemoveMode As VBIDE.vbext_RemoveMode, _
Custom () as Variant)
MsgBox "Add-in is now disconnected"
End Sub

Note If you develop a COM add-in in Visual Basic and do not use the Add-in
Designer (the Add-in Designer is available only in Visual Basic 6.0 and later),
you will need to create a COM .dll that implements the IDTExtensibility2
interface. For more information on the IDTExtensibility2 interface, see the
Microsoft Office 2000/Visual Basic Programmer’s Guide.


Module 10: Creating COM Add-ins

17

Creating COM Add-ins for Multiple Applications
Slide Objective

To describe how a COM
add-in can be developed to
run with multiple Office
applications.

Lead-in

You can develop a single
COM add-in that targets
more than one Office
application.

To Create a COM Add-in for Multiple Applications
Insert into the add-in project a new Add-in Designer for
each target application

Add-in Considerations
Each Add-in Designer in the add-in project represents a
separate add-in that can run in only one Office
application
The .dll can contain multiple add-ins that share forms,
modules, and class modules, but are targeted for
different applications

You can develop a COM add-in that targets multiple Office applications. To
target multiple applications, you must insert into the add-in project a new Addin Designer for each target application. For example, to create a COM add-in
that works with Excel and Word, the add-in project will have two Add-in

Designers, one to target each of these applications.
Essentially, each Add-in Designer in the add-in project represents a separate
add-in that can run in only one Office application. The object models vary in
each Office application, so you need to write application specific code to
perform essentially the same task in each application. The resulting .dll can
contain multiple add-ins that share forms, modules, and class modules, but are
targeted for different applications.

Inserting Additional Add-in Designers into a Project
To insert additional Add-in Designers into a project:
1. On the Insert menu, click Components.
2. In the Components dialog box, click the Designer tab, and then select
Addin Class.
3. In the Project window, right-click the Designers folder for the add-in
project, point to Insert, and then click Addin Class.
4. Set the Application property of the Add-in Designer to the host application
that you want and then set other Add-in Designer properties.
5. Repeat steps 3 through 4 for each additional host application.


18

Module 10: Creating COM Add-ins

Closing a COM Add-in
Slide Objective

To describe and show how
to close a COM add-in and
Outlook 2000.

Lead-in

You may experience
problems when you close
Outlook 2000 when a COM
add-in is running. These
problems are caused by a
conflict of interests between
Outlook 2000 and the COM
add-In.

To Close a COM Add-in
Declare an Explorer object using the WithEvents
keyword
Add code to the Close event of the objExp object that
counts the number of open Explorer objects
Public WithEvents objExp As Outlook.Explorer
Public WithEvents objExp As Outlook.Explorer
Private Sub objExp_Close()
Private Sub objExp_Close()
If OutlookApplication.Explorers.Count = 1 Then
If OutlookApplication.Explorers.Count = 1 Then
objExp.ShutDown
objExp.ShutDown
Set OutlookApplication = Nothing
Set OutlookApplication = Nothing
Closed = True
Closed = True
End If

End If
End Sub
End Sub

When Outlook 2000 is instructed to close, it should close all Explorer and
Inspector windows, and instruct each COM add-in to fire the
OnBeginShutdown event followed by the OnDisconnection event. In some
cases, however, a COM add-in will hold a reference to Outlook 2000 itself.
Outlook 2000, therefore, closes all Explorer and Inspector windows but does
not fire the shutdown sequence because it remains running.
To test for this shutdown problem, on the Outlook 2000 File menu, click Exit
and Log Off. Wait for 20 seconds and then use the Task Manager to see if
Outlook 2000 is still running. If it is still running, either another application is
controlling Outlook 2000—for example Visual Basic or Visual Basic for
Application code in another Office application—or one of the loaded COM
add-ins is not allowing Outlook 2000 close.


Module 10: Creating COM Add-ins

19

Using the Explorers Collection to Solve the Shutdown
Problem
In your Class module, declare an Explorer object by using the WithEvents
keyword.
Public WithEvents objExp As Outlook.Explorer

In the OnConnection event, set the objExp object variable by using the
ActiveExplorer method of the Outlook Application object. Next, add code to

the Close event of the objExp object to count the number of open Explorer
objects. If there is only one Explorer object in the collection as it is about to
close, you can assume Outlook 2000 is about to close and cleanly close your
COM add-in. Outlook 2000 should now close correctly because the references
to it within the COM add-in have been dropped.
The following example uses the Close event of the Explorer object to check
the number of open Explorer objects.
Private Sub objExp_Close()
If OutlookApplication.Explorers.Count = 1 Then
objExp.ShutDown
Set OutlookApplication = Nothing
Closed = True
‘ Closed is a varible used in the
‘ OnDisconnection event to signify
‘ that references have already been
‘ dropped.
End If
End Sub

Important The previous workaround presented makes certain assumptions that
may not always be true. You should carefully test your COM add-in and ensure
that it closes cleanly when operating as both the only installed COM add-in and
when installed with other COM add-ins. You should also consider if Outlook is
used as an Automation server itself and how this might effect the operation of
your COM add-in. (If this is the case, the number of Explorer windows would
be zero but Outlook would not be in a shutdown situation). COM add-ins
operate exactly the same if Outlook is started as an Automation request or by
the user.

20

Module 10: Creating COM Add-ins

Working with a COM Add-in Project
Slide Objective

To outline this topic.

Lead-in

Once you have written the
code for a COM add-in, you
can use the Visual Basic
Editor to debug, compile,
and register it.

Debugging a COM Add-in
Compiling a COM Add-in
Registering a COM Add-in

Once you have written the code for a COM add-in, you can use all of the
features of the Visual Basic Editor to debug, compile, and register it.


Module 10: Creating COM Add-ins

21

Debugging a COM Add-in

Slide Objective

To list the steps to debug a
COM add-in.

Lead-in

While the tools are the
same, the process of
debugging a COM add-in is
slightly different than
debugging a standard Visual
Basic for Applications
project.

To Debug a COM Add-in
1 Set a breakpoint in the OnConnection event.
2 On the Run menu, click Run Project to create an
instance of a debug version of the COM add-in.
3 Start the target application.

You can use all the debugging tools in the Visual Basic Editor to debug a COM
add-in. However, you start a debugging session differently with COM add-ins
than with other projects developed with the Visual Basic Editor.

Starting to Debug Code in a COM Add-in
To start debugging code in a COM add-in:
1. Set a breakpoint anywhere in the code for the OnConnection event.
2. On the Run menu, click Run Project to create an instance of a debug
version of the COM add-in.

3. Start the target application.
The Visual Basic Editor will enter break mode at the breakpoint set in the code
of the OnConnection event.