Module 10: Creating COM Add-ins Contents Overview Introduction to COM Add-ins Developing a COM Add-in 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 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 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 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 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 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 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 56 Module 10: Creating COM Add-ins To set the CustomPropertyPage project properties On the Project menu, click Project1 Properties The Project1 – Project Properties dialog box appears In the Project Name box, type CustomPropertyPage In the Project Description box, type Custom Property Page Click OK To save the CustomPropertyPage project file On the File menu, click Save Project The Save Project As dialog box appears In the Save In list, locate :\Moc\1593a\Labfiles\Lab10a Click Save If you are prompted to add the file to SourceSafe, click No To compile the CustomPropertyPage control On the File menu, click Make CustomPropertyPage.ocx The Make Project dialog box appears Click OK The project is compiled Exit Visual Basic If you are prompted to save changes, click Yes To verify that the MoveApp Settings property page is available Start Outlook 2000 In the Folder List, expand Public Folders, All Public Folders, Business Functions, and MoveApp Right-click the Employee Moves public folder, and then click Properties on the shortcut menu The Employee Moves Properties dialog box appears Click the MoveApp Settings tab There may be a short delay before the tab appears Module 10: Creating COM Add-ins To verify functionality of the MoveApp Settings property page On the MoveApp Settings tab, in the Distribution list name box, type Unknown DL and then click Resolve The Check Names dialog box appears, stating that Outlook 2000 does not recognize Unknown DL as a distribution list To close the Check Names dialog box, click Cancel In the Distribution list name box, delete Unknown DL, and then type Computer Services Manager Click Resolve The distribution list name you typed is resolved and the Resolve button is made inactive To close the Employee Moves Properties dialog box, click OK Exit Outlook 2000 Log off Windows NT 57 58 Module 10: Creating COM Add-ins Lab B: Converting a Visual Basic for Applications Macro to a COM Add-in Slide Objective To introduce the lab Lead-in In this lab, you will convert an existing Visual Basic for Applications macro into a COM add-in Explain the lab objectives Objectives After completing this lab, you will be able to: Convert an existing Visual Basic for Applications macro into a Component Object Mode (COM) add-in Modify code within a COM add-in code module Ensure that a custom COM add-in closes correctly when you exit Outlook 2000 Use code to programmatically create a toolbar button for a custom COM add-in Compile a COM add-in as a dynamic-link library (.dll) file Test a compiled COM add-in Prerequisites This lab is dependent upon the completion of: Lab A, “Configuring the MoveApp Development Environment,” in module of course 1593, Building Collaborative Solutions by Using Microsoft Outlook 2000 Lab A, “Creating the Public Folder Hierarchy for the MoveApp,” in module of this course Module 10: Creating COM Add-ins 59 Scenario In a preceding lab, you created a macro that prints a page of move labels Employees use the labels to identify their boxes, equipment, and so on Information for the labels is retrieved from the MoveApp After labels are printed for an individual, that individual no longer appears in the Labels Not Printed view, allowing the administrator to track who has and does not have labels printed Though the Visual Basic for Applications macro offers the same functionality, the otm file used by Outlook 2000 Visual Basic for Applications is not designed to be deployed In this lab, you will convert the macro to a COM addin so that it may be easily deployed Estimated time to complete this lab: 30 minutes 60 Module 10: Creating COM Add-ins Exercise Converting a VBA Application to a COM Add-in In this exercise, you will use the Add-In Designer file from Microsoft Office 2000 Developer to convert a VBA application to a COM add-in To install the initial VBA project file Verify that you are logged on as Administrator On the taskbar, click Start, and then click Run In the Open box, type :\moc\1593a\labfiles\lab10b where is the drive where the MOC files are installed The Lab10B window appears Copy Vbaproject.otm to the :\Winnt\Profiles\Administrator\Application Data\ Microsoft\Outlook folder, where is the drive where Windows NT Server is installed If the Vbaproject.otm file already exists in the Outlook folder, replace the existing file with the new file Close the Lab10B window To create the COM add-in project Start Outlook 2000 If the macro warning dialog box appears, click Disable Macros On the Tools menu, point to Macro, and then click Visual Basic Editor The Visual Basic Editor starts On the File menu, click New Project The New Project dialog box appears Click the Addin Project icon and then click OK The code window is replaced by the Add-In Designer properties page In the Addin Display Name box, type Move Application Label Generator In the Addin Description box, type Generates the labels required for an office move in the MoveApp In the Application list, click Microsoft Outlook In the Initial Load Behavior list, click Startup Module 10: Creating COM Add-ins 61 To copy the Module1 and ExpClass files into the COM add-in project In the Project Explorer pane, in the Project1 (VBAProject.OTM) project, expand the Modules folder Click Module1 On the File menu, click Export File The Export File dialog box appears Change Save In to :\Moc\1593a\Labfiles\Lab10B, where is the drive where the MOC files are installed Click Save In the Project Explorer pane, expand the Class Modules folder in the Project1 (VBAProject.OTM) project Click ExpClass On the File menu, click Export File The Export File dialog box appears Click Save 10 In the Project Explorer pane, click AddInProject1 (AddInProject1) 11 On the File menu, click Import File The Import File dialog box appears 12 In the Look In list, locate and select :\Moc\1593a\LabfilesLlab10B 13 Click Module1.bas 14 Click Open 15 On the File menu, click Import File The Import File dialog box appears 16 Click ExpClass.cls 17 Click Open To add the IDTExtensibility2 interface event code In the Project Explorer pane, click AddInDesigner1 On the View menu, click Code On the Insert menu, click File The Insert File dialog box appears In the Look In list, locate and select :\Moc\1593a\Labfiles\Lab10B Click designer_code.txt Click Open 62 Module 10: Creating COM Add-ins Exercise Adjusting the Module and ExpClass Files for a COM Add-in In this exercise, you will declare a project-wide variable to hold the reference passed by the IDTExtensibility2 interface for the Outlook 2000 application You will also declare a variable in the ExpClass class module to hold the reference to the CommandBar button This declaration includes the keyword WithEvents to allow the COM add-in to trap the event of the button being pressed The newCBC variable used in the VBA project will be replaced with the oCommandButton variable declared in the Class module To set the references for the add-in project On the Tools menu, click References The References – AddinProject1 dialog box appears In the Available References list, select the Microsoft Office 9.0 Object Library check box In the Available References list, select the Microsoft Outlook 9.0 Object Library check box In Available References list, select the Microsoft Word 9.0 Object Library check box Click OK To modify the Module1 code In the Project Explorer pane, expand AddInProject1 and Modules Under AddInProject1 and Modules, click Module1 On the View menu, click Code In the Code pane, in the Object list, click (General) In the Code pane, in the Procedure list, click (Declarations) After the Option Explicit statement, add a new code line and type the following lines of code: Global strprogid As String Global Closed as Boolean Global OutlookApplication As Outlook.Application Module 10: Creating COM Add-ins 63 To modify the ExpClass code In the Project Explorer pane, expand AddInProject1 and Class Modules, and then click ExpClass On the View menu, click Code In the Code pane, in the Object list, click (General) In the Code pane, in the Procedure list, click (Declarations) After the Public WithEvents oExp As Outlook.Explorer statement (at the top of the code window), add a new line and type the following line of code: Private WithEvents oCommandButton As Office.CommandBarButton On the Edit menu, click Replace The Replace dialog box appears In the Find What box, type newCBC In the Replace With box, type oCommandButton Click Replace All Seven replacements are made 10 Click OK 11 To close the Replace dialog box, click Cancel 12 On the Edit menu, click Find The Find dialog box appears 13 In the Find What box, type Dim oCommandButton 14 Click Find Next 15 Click Cancel 16 Delete the line on which the highlighted text appears 17 In the Code pane, in the Object list, click oCommandButton Private Sub and End Sub statements are added for the oCommandButton_Click event 18 Between the Private Sub and End Sub statements, type Create_Labels 64 Module 10: Creating COM Add-ins Exercise Closing the COM Add-in When you quit Outlook 2000, the OnDisconnection event should fire, allowing the code in this event to correctly close the COM add-in However, the event will not fire because the COM add-in is holding references open to Outlook 2000 To handle this situation, trap the Close event on the Explorers collection and test within this event to see if it is the last explorer being closed If the last explorer is being closed, the COM add-in is no longer necessary and the code will correctly shut down the COM add-in In addition to the OnDisconnection event, the Close event in the Explorer correctly detects Outlook 2000 shutting down and removes the references to the Outlook 2000 application Thus, you must recognize that two different events can potentially attempt to release the same resources, causing a run-time error A global variable (closed) is used to stop the OnDisconnection code from running if references have already been dropped by the Explorer Close event To add code to the Explorer Close event In the Code pane, on the Object list, click oExp In the Code pane, on the Procedures list, click Close Sub and End Sub statements are added for the Explorer Close event Between the Sub and End Sub statements, type the following lines of code: If OutlookApplication.Explorers.Count = Then expobj.shutdown Set OutlookApplication = Nothing closed = True End If On the Insert menu, click Procedure The Add Procedure dialog box appears In the Name box, type Shutdown Click OK Sub and End Sub statements are added for a new procedure named Shutdown On the blank line between the Sub and End Sub statements, type the following lines of code: Set oCommandButton = Nothing Set oExp = Nothing Module 10: Creating COM Add-ins 65 Exercise Adjusting the Creation of the CommandBar Button In this exercise, you will change the OnAction property of the new Command button Previously, in the VBA project, this property contained the name of the macro you want to execute, Create_Labels Now the contents of this property needs to be: "!" This is set in the AddinInstance_OnConnection event and stored in a global variable called strProgId When the button is created, the OnAction property must be set to this variable In the VBA application, Application contains the Outlook 2000 application object This object is passed into the OnConnection event of the IDTExtenisibility2 event and made global to your project using a variable called OutlookApplication You will make the necessary change to the Class_Initalize event To modify the OnAction property On the Edit menu, click Find The Find dialog box appears In the Find What box, type oCommandButton.OnAction Click Find Next Click Cancel Replace the text "Create_Labels" on the highlighted line with the text strProgId To modify the reference to the Outlook Application object In the Code pane, in the Object list, click Class The Code pane displays the Class_Initalize event Within the Class_Initalize event, change Application.ActiveExplorer to OutlookApplication.ActiveExplorer The code should read: Set oExp = OutlookApplication.ActiveExplorer 66 Module 10: Creating COM Add-ins Exercise Compiling the COM Add-in In this exercise, you will compile the project into a dll file To save the project In the Project pane, click AddinProject1 On the File menu, click Save As The Save As dialog box appears In the Save In list, locate and select :\Moc\1593a\Labfiles\Lab10B In the File Name box, type labels Click Save To compile the COM add-in On the File menu, click Make labels.DLL The Make Project dialog box appears Click OK Module 10: Creating COM Add-ins 67 Exercise Removing the VBA Application from Outlook 2000 and Testing the COM Add-in In this exercise, you will remove the Vbaproject.otm file from Outlook 2000 and test the new COM add-in To remove the VBAProject.otm file Close the Visual Basic Editor Close Outlook 2000 When you are prompted to save changes to the labels.vba project, click Yes On the taskbar, click Start, point to Programs, and then click Windows NT Explorer Microsoft Windows NT® Explorer starts Locate and select :\WINNT\Profiles\Administrator\Application Data\Microsoft\Outlook Delete the VBAProject.otm file Close Windows NT Explorer To test the COM add-in Start Outlook 2000 Notice that no macro warning dialog box appears In the Folder List, locate and select the Public Folders\All Public Folders\Business Functions\MoveApp\Employee Moves folder On the Advanced toolbar, in the View list, click Labels Not Printed The Print Labels button appears on the Advanced toolbar In the Views list, click Moves Completed The Print Labels button is removed from the Advanced toolbar In the Views list, click Labels Not Printed Select one or more Move items 68 Module 10: Creating COM Add-ins Click Print Labels Microsoft Word starts and a page of labels is created for each Move item that you selected as shown in the following illustration Exit Word without saving changes Exit Outlook 2000 10 Log off Windows NT Module 10: Creating COM Add-ins 69 Review Slide Objective To reinforce module objectives by reviewing key points Introduction to COM Add-ins Lead-in Developing a COM Add-in The review questions cover some of the key concepts taught in the module Working with a COM Add-in Project Working with Command Bars Creating Custom Property Pages for Outlook 2000 In what way COM add-ins in Office 2000 differ from add-ins supported by earlier versions of Office? In Office 2000, all of the applications now support a common add-in architecture and development environment What is the purpose of the IDTExtensibility2 interface? It provides a programming interface for integrating COM add-ins with their host application and makes a set of events available to manage Office applications What are the five methods the IDTExtensibility2 interface makes available? OnConnection, OnStartupCOmplete, OnAddInnsUpdate, OnBeginShutdown, and OnDisconnection What is a benefit of building your COM add-ins in Visual Basic 6.0 or Office 2000 Developer with the Add-in Designer? The dll that is created is self-registering 70 Module 10: Creating COM Add-ins Where in the registry would you go to see if a COM add-in has been registered? \HKEY_CLASSES_ROOT\project name.addin designer name In what ways can you now edit command bars in Outlook 2000? You can create new command bars, create a new menu bar, modify shortcut menus, and modify existing command bars ... 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. .. 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 Comparing COM Add-ins. .. 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 Comparing COM Add-ins and Visual