How to: Create a COM Add-in to Add Custom Features to InfoPath

Article
07/24/2014

Applies to: InfoPath 2010 | Office 2010 | Visual Studio 2010

In this article
The IDTExtensibility2 Interface
Registering COM Add-ins
Creating a Managed COM Add-in with Visual Studio 2005 or Visual Studio 2008
Viewing the Registry Settings
Compiling and Distributing the Shared Add-In
Coding in the COM Add-in

Microsoft InfoPath 2010 supports COM Add-ins for extending the form editing user experience. Although support for COM Add-ins was first added in InfoPath 2010, 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 InfoPath is available for the form editing environment. The form design environment cannot be extended by using 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.

Interface	Description
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:

HKEY_CURRENT_USER\Software\Microsoft\Office\InfoPath\AddIns\

For COM Add-ins installed for use by every user of the client computer, the registry key is located in the HKLM registry hive:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\InfoPath\AddIns\

The registry key name corresponds to the ProgIdAttribute of the add-in, and contains the following values.

Name	Type	Description
FriendlyName	String	The name that is displayed in the COM Add-ins dialog box and listed in the Add-ins page of the Trust Center.
Description	String	The string that is displayed 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.

Value	Description
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 or Visual Studio 2008

To create a managed COM add-in using Microsoft Visual Studio 2005 or Visual Studio 2008, create a Shared Add-In project as follows:

Start Visual Studio.
On the File menu, click New Project.
In the Project Types pane of the New Project dialog box, click the Other Projects Types folder, and then click Extensibility.
In the Templates pane, click Shared Add-In.
In the Name box, type a name for the 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, 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 14.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 COM tab, double-click Microsoft.InfoPath 2.0 Type Library, and click OK.
Adding a reference to the Microsoft InfoPath 3.0 Type Library also adds references to three assemblies that must be removed: ADODB, MSHTML, and MSXML2. In Solution Explorer under References, right-click each of these references, and then click Remove.

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 Editor, 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.

Note

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 of the ApplicationEvents object can be used by the COM Add-in to respond to user actions:

Event	Description
NewXDocument Event	Occurs when a new form is created.
Quit Event	Occurs when the user quits InfoPath.
WindowActivate Event	Occurs when any document window is activated.
WindowDeactivate Event	Occurs when any document window is deactivated.
WindowSize Event	Occurs when any document window is resized or moved.
XDocumentBeforeClose Event	Occurs immediately before any open document closes.
XDocumentBeforePrint Event	Occurs immediately before any open document is printed.
XDocumentBeforeSave Event	Occurs immediately before any open document is saved.
XDocumentChange Event	Occurs when a new form is created, when an existing form is opened, or when another form is made the active form.
XDocumentOpen Event	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:

InfoPathApplication = DirectCast( _
   application, Microsoft.Office.Interop.InfoPath._Application3)
InfoPathApplicationEvents = DirectCast( _
   InfoPathApplication.Events, _
   Microsoft.Office.Interop.InfoPath.ApplicationEvents)

InfoPathApplication =
   (Microsoft.Office.Interop.InfoPath._Application3)application;
InfoPathApplicationEvents =
   (Microsoft.Office.Interop.InfoPath.ApplicationEvents)
   InfoPathApplication.Events;

The first line casts the generic application Object received by the add-in to the _Application3 object. The second line casts the Events property of the _Application3 object (represented by the InfoPathApplication variable) to the ApplicationEvents object.

To create event handlers, select InfoPathApplicationEvents from the Class Name drop-down box at the top of the Visual Studio window, and 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:

Private Sub InfoPathApplicationEvents_XDocumentBeforeSave( _
   ByVal pDocument As Microsoft.Office.Interop.InfoPath._XDocument, _
   ByRef pfCancel As Boolean) _
   Handles InfoPathApplicationEvents.XDocumentBeforeSave
End Sub

private void InfoPathApplicationEvents_XDocumentBeforeSave(
   Microsoft.Office.Interop.InfoPath._XDocument pDocument, ref bool pfCancel)
{
}

Any of the events of the ApplicationEvents object can be handled by the COM Add-in using the same method.

Share via