How To: Create a COM Add-in to Add Custom Features to InfoPath
Microsoft Office InfoPath 2007 supports COM Add-ins for extending the form editing user experience. Although this is new to Office InfoPath 2007, other Office applications such as Microsoft Office Word and Microsoft Office Excel have supported COM add-ins since Office 2000.
COM Add-in support in Office InfoPath 2007 is available in the form editing environment. The form design environment is not able to be extended through the use of COM Add-ins.
The IDTExtensibility2 interface
The InfoPath editing environment provides support for the IDTExtensibility2 interface, which must be implemented by developers of COM Add-ins. IDTExtensibility2 is a dual-interface object that provides five methods which act as events within the editing environment. These methods allow the COM add-in to respond to environment startup and shutdown conditions, listed in the following table.
|OnAddInsUpdate (ByVal custom() As Variant)||Occurs when an add-in is loaded or unloaded in the environment.|
|OnBeginShutdown (ByVal custom() As Variant)||Occurs when the environment is being shut down.|
|OnConnection(ByVal Application As Object, ByVal ConnectMode As ext_ConnectMode, ByVal AddInInst As Object, ByVal custom() As Variant)||Occurs when an add-in is loaded in the environment.|
|OnDisconnection (ByVal RemoveMode As ext_DisconnectMode, ByVal custom() As Variant)||Occurs when an add-in is unloaded from the environment.|
|OnStartupComplete (ByVal custom() As Variant)||Occurs when the environment has completed starting.|
Registering COM Add-ins
All Office applications, including InfoPath, use the registry to list add-ins in the COM Add-Ins collection, to store the connect state, and to store the boot or demand load information. For InfoPath COM Add-ins, the name of each add-in appears under the following key:
For COM Add-ins installed for use by every user of the client computer, the registry key is located in the HKLM registry hive:
The registry key name corresponds to the ProgIdAttribute of the add-in, and contains the following values.
|FriendlyName||String||The name that will appear in the COM Add-ins dialog box and listed in the Add-ins page of the Trust Center.|
|Description||String||The string that will appear when the Add-in is selected in the Trust Center.|
|LoadBehavior||DWORD||Specifies the way the COM Add-in is loaded. The value can be a combination of 0, 1, 2, 8, and 16. See the table below for more information.|
The DWORD value for LoadBehavior should contain a value describing how the COM Add-in loads in the editing environment. The value can be from the table below, or a combination of values from the table. For example, a COM Add-in created in Visual Studio 2005 will have a LoadBehavior of "3" loaded at application startup and be connected.
|0||Disconnected. The Add-in shows as Inactive in the COM Add-in dialog box.|
|1||Connected. The Add-in shows as Active in the COM Add-in dialog box.|
|2||Load at Startup. The Add-in is loaded and connected when the host application starts.|
|8||Load on Demand. The Add-in is loaded and connected when the host application requires it, for example when a user clicks a button that uses functionality in the Add-in.|
|16||Connect first time. The add-in will be loaded and connected the first time the user runs the host application after registering the add-in.|
Creating a managed COM Add-in with Visual Studio 2005
To create a managed COM add-in using Microsoft Visual Studio 2005, create a Visual Studio Shared Add-In project as follows:
- Click Start, point to All Programs, point to Microsoft Visual Studio 2005, and click Microsoft Visual Studio 2005.
- Click New Project on the File menu.
- In the Project Types pane of the New Project dialog box, expand Other Projects Types, and then click Extensibility.
- In the Templates pane, click Shared Add-In.
- In the Name box, type a name for the Shared Add-In project.
- In the Location box, type a folder path or click Browse and select a folder path, and then click OK. The Shared Add-in Wizard appears.
- Click Next in the Shared Add-in Wizard. The Select a Programming Language page appears.
- Click Create an Add-in using Visual Basic, and then click Next. The Select An Application Host page appears.
- Uncheck the boxes next to each application except Microsoft InfoPath, and then click Next. The Enter a Name and Description page appears.
- In the What is the name of your Add-In box, type the name of your COM Add-in.
- In the What is the description of your Add-In box, type the description for your COM Add-in, and click Next. The Choose Add-In Options page appears.
- Check the I would like my Add-in to load when the host application loads and My Add-in should be available to all users of the computer it was installed on, not just the person who installs it boxes.
- Click Next to review the Summary page, then click Finish.
After the project is created by Visual Studio, you will see two projects in the Solution Explorer window. The first project is the project for the COM Add-in; the second project is a setup project for deploying the COM Add-in. The Shared Add-in Wizard only inserts a reference to the Microsoft Office 12.0 Object Library, so it is necessary to insert a reference to the InfoPath object library using the following steps:
- Double-click My Project to display the add-in project properties. Click the References tab to display the references automatically added to the project.
- Click the Add button to display the Add Reference dialog box.
- On the .NET tab, double-click Microsoft.Office.Interop.InfoPath, and click OK.
|To create unmanaged COM Add-ins, see Creating a Microsoft Office 2000 COM Add-in in the MSDN library.|
Viewing the Registry Settings
To view the registry settings that will be created when the COM Add-in is installed, follow these steps:
- Right-click the root node of the setup project in the Solution Explorer, click View, then click Registry.
- In the left-hand pane, click the plus to expand HKEY_LOCAL_MACHINE, Software, Microsoft, InfoPath, then AddIns.
- Click the name corresponding to your shared add-in project's ProgID.
To change any of these properties, right-click the property, click Properties Window, and change the Value box in the Properties Window.
Compiling and Distributing the Shared Add-In
To compile the managed COM Add-in for testing on the computer on which the Shared Add-In project was developed, right-click the root node of the Shared Add-In project in the Solution Explorer and click Build. If the project builds with no errors, you can start the InfoPath editing environment and begin using the managed COM Add-in. If you have an instance of InfoPath running, close it before building the project. It may also be necessary to open the COM Add-ins dialog box to verify that the COM Add-in is registered. To open the COM Add-ins dialog box, follow these steps:
- Open the InfoPath editing environment. The easiest way to do this is to open an existing form template, which will create a new form based on that form template.
- Click Trust Center on the Tools menu.
- Click the Add-ins category on the left.
- In the Manage section near the bottom of the Trust Center dialog box, select COM Add-ins from the list and click the Go button.
- In the COM Add-ins dialog box, you will see the name of your recently-built add-in and there should be a check box next to it. If there is no check box next to it, the COM Add-in failed to load due to an error, which will be listed in the Load Behavior section of the dialog box.
To compile the managed COM add-in for use on a computer other than the computer on which the Shared Add-In project was developed, you must follow additional steps to secure your code. For information on securing Shared Add-In projects for use on other computers, see the following three articles:
- Deployment of Managed COM Add-Ins in Office XP
- Using the COM Add-in Shim Solution to Deploy Managed COM Add-ins in Office XP
- Isolating Office Extensions with the COM Shim Wizard
Important Not isolating the COM Add-in may cause memory leaks and application instability.
|If the .NET Framework or other required assemblies from the setup project are not already installed on target computers, the .msi file may not install properly. Also, you cannot distribute the .msi file and then attempt to install the .msi file. You must also distribute the other support files in the same folder as the original .msi file generated by Visual Studio.|
Coding in the COM Add-in
Application events that occur in the InfoPath form editing environment can be captured by a COM Add-in. The following events in the ApplicationEvents object can be used by the COM Add-in to respond to user actions:
|NewXDocument||Occurs when a new form is created.|
|Quit||Occurs when the user quits InfoPath.|
|WindowActivate||Occurs when any document window is activated.|
|WindowDeactivate||Occurs when any document window is deactivated.|
|WindowSize||Occurs when any document window is resized or moved.|
|XDocumentBeforeClose||Occurs immediately before any open document closes.|
|XDocumentBeforePrint||Occurs immediately before any open document is printed.|
|XDocumentBeforeSave||Occurs immediately before any open document is saved.|
|XDocumentChange||Occurs when a new form is created, when an existing form is opened, or when another form is made the active form.|
|XDocumentOpen||Occurs when a document is opened.|
To capture these events in the COM Add-in, you must declare the following class-level variables in your Connect class:
In the OnConnection procedure, you will need the following two lines:
To create event handlers, select InfoPathApplicationEvents from the Class Name drop-down box at the top of the Visual Studio window, then select the event you want to handle in the Method Name drop-down box at the top of the Visual Studio window. For example, if you need to control when a form is saved, you handle the XDocumentBeforeSave event. Selecting XDocumentBeforeSave from the Method Name drop-down automatically inserts the following procedure:
Any of the events of the ApplicationEvents object can be handled by the COM Add-in using the same method.
Additional Resources for Developing COM Add-ins
The following list includes links for learning more about COM Add-ins, as well as step-by-step examples of creating COM Add-ins for Office applications.