Hosting the InfoPath 2007 Form Editing Environment in a Custom Windows Form Application

Article
05/05/2014

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Summary: The Microsoft Office InfoPath 2007 form editing environment can be hosted in a custom Windows Form application by using the FormControl. Learn how to incorporate this control into your application, work with the XML data generated by the FormControl, and use the IOleCommandTarget interface to replicate functionality of the Office InfoPath 2007 form editing environment menu and toolbar commands. (9 printed pages)

Mike Talley, Microsoft Corporation

Mark Roberts, Microsoft Corporation

Updated September 2007

**Applies to:**Microsoft Office InfoPath 2007

Download the installation packages for the sample applications that demonstrate how to use the FormControl managed class (InfoPath2007UsingIOLECommands_RTM.exe) and the InfoPathEditorObject COM control (InfoPath2007UsingIOLECommandsCOM_RTM.exe) to mirror functionality of the InfoPath editing environment: InfoPath 2007 Sample: Using IOLECommands with the InfoPath Form Control.

Contents

Overview
Adding the FormControl to the Visual Studio 2005 Toolbox
Adding the FormControl to Your Application
Loading an InfoPath Form Template into the Control
Handling the XML Data Submitted by the Form
Using the IOleCommandTarget Interface to Provide Extra Functionality
InfoPath Features Not Available in the FormControl
Licensing Considerations
Conclusion
Additional Resources

Overview

The hostable editor feature of Microsoft Office InfoPath 2007 enables developers to integrate the InfoPath form editing environment into custom applications. Developers who write traditional COM-based applications can use the InfoPathEditorObject object that is available by referencing IPEDITOR.DLL, and developers who write Microsoft .NET Framework-based applications can use the Microsoft.Office.InfoPath.FormControl.dll assembly, which provides managed types based on the COM interface. This latter FormControl object contains the same functionality as the InfoPathEditorObject object, but the types and their associated members are different.

In this article, you will learn primarily about the FormControl object and how to incorporate it into your custom .NET Framework-based applications. The downloads associated with this article contain custom applications that provide COM and .NET functions for replicating the InfoPath form editing environment commands through the use of the COM IOleCommandTarget interface. Every command that is supported by Office InfoPath 2007 is included in the sample application. It is made available for developers to examine and learn how to customize their .NET Framework-based and COM-based applications that incorporate the hostable editor.

Requirements:

Microsoft Office InfoPath 2007

Microsoft Visual Studio 2005

Adding the FormControl to the Visual Studio 2005 Toolbox

Start by creating a Microsoft Visual C# Windows project in Microsoft Visual Studio 2005 using the Windows Application template. Before you can add the FormControl to your application, you need to add the control to the Visual Studio Toolbox using the following procedure.

To add the FormControl to the Toolbox

In the Toolbox, expand the General section.
Right-click below the expanded General section, and then click Choose Items.
In the Choose Toolbox Items dialog box, click the Browse button.
Locate the assembly Microsoft.Office.InfoPath.FormControl.dll, typically found at C:\Program Files\Microsoft Office\Office12.
Select the DLL and click Open.
Ensure that the check box next to FormControl is checked, as shown in Figure 1, and then click OK.

Figure 1. Selecting the FormControl

Aa701079.OfficeInfoPath2007HostingInfoPathForms_Fig01(en-us,office.12).gif

The FormControl now appears in the Toolbox.

Adding the FormControl to Your Application

Adding the FormControl to your application is like adding any other control. Drag the control to your Windows form, and then place and resize the control to accommodate the expected size of the InfoPath form template that you intend to load into the control. You can add more than one FormControl to the form, but for the purposes of this demonstration, only one FormControl will be present on the form.

Loading an InfoPath Form Template into the Control

After you add the FormControl to the Windows form, loading an existing InfoPath form template into the FormControl is the same as using the InfoPath object model.

To load an InfoPath form template into the FormControl

Add the following line after the last using statement.

[C#]
```
using Microsoft.Office.InfoPath;
```
Add the following Visual C# code to your form code, where the myForm variable is the location of the form template, and formControl1 is the name of the FormControl instance.

[C#]
```
string myForm = "C:\\Template1.xsn";
// Open a form based on the solution.
formControl1.NewFromFormTemplate(myForm);
```
If your form has multiple views, you can switch views by adding the following code, where the variables myView1 and myView2 represent the names of the views in the form.

[C#]
```
string myView1 = "Overview";
string myView2 = "Details";
// Switch the view to the "Details" view.
formControl1.XmlForm.ViewInfos.SwitchView(myView2);
```

Note
You can access the underlying XML document that is associated with the form by using the properties and methods of the XmlForm class, which you access by using the XmlForm property of the FormControl. The object model of the FormControl is based on the fully managed object model available in InfoPath 2007, which is provided by the Microsoft.Office.InfoPath namespace. You cannot use Microsoft JScript and Microsoft Visual Basic Scripting Edition (VBScript) or managed code and the Microsoft.Office.Interop.InfoPath.SemiTrust object model with the FormControl. Switching views immediately after the form loads may result in an error. If you need to switch views based on user roles, use the built-in User Roles and Rules features ((On the Tools menu, click Form Options, click Open and Save, and then click Rules)). You can switch views after a form is opened by using the SwitchView(System.String) method of the ViewInfoCollection class, as shown in the previous code example.

You can access the underlying XML document that is associated with the form by using the properties and methods of the XmlForm class, which you access by using the XmlForm property of the FormControl. The object model of the FormControl is based on the fully managed object model available in InfoPath 2007, which is provided by the Microsoft.Office.InfoPath namespace. You cannot use Microsoft JScript and Microsoft Visual Basic Scripting Edition (VBScript) or managed code and the Microsoft.Office.Interop.InfoPath.SemiTrust object model with the FormControl.

Switching views immediately after the form loads may result in an error. If you need to switch views based on user roles, use the built-in User Roles and Rules features ((On the Tools menu, click Form Options, click Open and Save, and then click Rules)). You can switch views after a form is opened by using the SwitchView(System.String) method of the ViewInfoCollection class, as shown in the previous code example.

Handling the XML Data Submitted by the Form

Office InfoPath 2007 contains a new type of data connection for submitting the XML data generated by the form to the hosting environment. This new data connection, which is represented by the SubmitToHostConnection class, has the corresponding submitToHostAdapter element entry in the manifest.xsf file.

<xsf:submitToHostAdapter name="Submit" submitAllowed="yes"></xsf:submitToHostAdapter>

Adding a SubmitToHostConnection in InfoPath 2007

The following procedure describes how to set up a new SubmitToHostConnection data connection.

To set up a new SubmitToHostConnection data connection

Open an InfoPath form template in design mode.
On the Tools menu, click Data Connections.
Click Add.
In the Data Connection Wizard, select the options Create a new connection to and Submit data, and then click Next.
Select To the hosting environment, such as an ASP.NET page or a hosting application, as shown in Figure 2, and then click Next.

Figure 2. Submitting data to the host
Type a name for the new data connection, and then click Finish.

After you create the submit data connection, enable the form to submit its XML data to the hosting environment by following these steps:
On the Tools menu, click Submit Options.
Select the Allow users to submit this form check box.
Select Hosting environment from the first drop-down box, and then select the name you gave to the SubmitToHostConnection data connection from the second drop-down box.

The dialog box should resemble Figure 3.

Figure 3. Selecting a data connection
Click OK.
Save the form template in a location that you will use to load it into the FormControl in your custom application.

Handling the FormControl Submit Operation in the Hosting Application

To handle the XML data submitted from the form, the FormControl includes a method called SetSubmitToHostEventHandler, which is called from the Load event of the application's main form.

[C#]

    private void Form1_Load(object sender, EventArgs e)
    {
        formControl1.SetSubmitToHostEventHandler(this);
    }

The second item to add to the hosting form code is the interface of the event, inherited by the form.

[C#]

public partial class Form1 : Form, Microsoft.Office.Interop.InfoPath.ISubmitToHostEventHandler

You will need a method to handle the event, such as the following, which you can insert by right-clicking the ISubmitToHostEventHandler text that you previously inserted and clicking Implement Interface.

[C#]

    public int SubmitToHostEventHandler(object sender, string adapterName, out string errorMessage)
    {
        MessageBox.Show("Submit handled from: " + adapterName.ToString());
        errorMessage = "";
        return 1;
    }

Using the IOleCommandTarget Interface to Provide Extra Functionality

The HostedApplication sample application contains the source code of a Windows application that demonstrates how to call all supported InfoPath commands from the FormControl by using the IOleCommandTarget interface. As shown in Figure 4, this application hosts an instance of the FormControl and includes toolbars and buttons to demonstrate many InfoPath editing features that you can enable with the IOleCommandTarget interface.

Figure 4. An instance of the FormControl

Aa701079.OfficeInfoPath2007HostingInfoPathForms_Fig04(en-us,office.12).gif

Using the IOleCommandTarget Interface in Your Custom Application

Calling InfoPath commands with the IOleCommandTarget interface from the FormControl in your own application requires five steps:

Import the FormController.cs, NativeCommands.cs, and Exceptions.cs resource files into your Visual Studio solution.
Add a using statement to your main form code.
Confirm the references to the four InfoPath assemblies.
Add initialization code in the application code.
Call a command from the FormController class.

The details of each of these steps are described in the following sections.

Importing the FormController.cs and NativeCommands.cs Resource Files into Your Visual Studio Solution

Download the InfoPath2007UsingIOLECommands_RTM.exe installation package that contains the source code for the HostedApplication sample application from the URL referenced at the beginning of this article. After you have extracted the files from the package, open your Visual Studio solution, use the Add Existing Item command on the Project menu, and then browse to the solution location to add the FormController.cs, NativeCommands.cs, and Exceptions.cs code files to your solution. By default, the HostedApplication solution is installed in the C:\2007 Office System Developer Resources\Code Samples\InfoPath2007UsingIOLECommands_RTM folder.

After you have added the three files to your solution, open each file and modify its namespace to match the namespace of your custom application. For example, if the namespace of your form project is "MyCustomXmlEditor" you would replace namespace HostedApplication with namespace MyCustomXmlEditor.

Adding a Using Statement to Your Main Form Code

After the last using statement in your form code, add the following line.

using System.Runtime.InteropServices;

Confirm References to Four Assemblies

After adding the FormControl instance to your project, you should have the following InfoPath assemblies in the references for your project:

Microsoft.Office.InfoPath
Microsoft.Office.InfoPath.Client.Internal.Host
Microsoft.Office.InfoPath.FormControl
Microsoft.Office.Interop.InfoPath

If you do not see these four references, add them by right-clicking the References folder, selecting Add Reference, and browsing the available assemblies on the .NET tab of the Add Reference dialog box. If you do not see a particular assembly, use the Browse tab of the dialog box to find the assemblies in the installation drive:\Program Files\Microsoft Office\Office12\ folder, where installation drive is the location where you have installed the version of the 2007 Microsoft Office system that contains Office InfoPath 2007.

Adding Initialization Code in the Application Code

The NativeCommands.cs file contains a class called NativeCommands, which imports and implements the IOleCommandTarget interface and its core methods: QueryStatus and Exec.

The NativeCommands class performs three operations:

Executes an InfoPath command, such as clicking the Bold button. This is performed using a call to the ExecuteCommand method.
Gets the state of a command, such as whether the Bold button is enabled before attempting to execute the command. This is performed using a call to the IsCommandOn method, which in turn calls the QueryCommandStatus(OLECMD[] commands) method that checks if the command is Supported (supported in the current context), Enabled (enabled in the current context), or Latched (is an on/off toggle, and is currently on).
Determines whether the command is applicable in the current context. For example, the Bold command cannot be used on text in a Text Box control. This is performed using a call to the QueryCommandStatus(FormControlCommandIds.CommandIds commandId) method, which checks if the command is Supported and Enabled. The commandId values that are used to call this version of the QueryCommandStatus method are defined by the enumeration, which is part of the FormControlCommandIds.CommandIdsFormControl object model.

Note

The NativeCommands class depends on the HostedException class, which is defined in the Exceptions.cs file, for handling exceptions.

Note
The NativeCommands class depends on the HostedException class, which is defined in the Exceptions.cs file, for handling exceptions.

The FormController.cs file contains a class named FormController, which inherits the NativeCommands class. The FormController class contains a wrapper for each command that is supported by the FormControl, and also other logic that makes using the wrapper methods easier than calling the IOleCommandTarget interface directly. However, you can still use the sample application that accompanies this article as a tool for learning how to call commands directly.

To access these command wrappers, add the following line of code to the beginning of your form code's class to create private variable for calling members of the FormController class.

private FormController formController;

Then add the following line of code to your application's main form code Load event handler, replacing formControl1 with the name of the FormControl instance in your application, to initialize the formController variable.

formController = new FormController(formControl1);

Using FormController Commands to Add Functionality to the FormControl

After you have set up your custom application to use the command wrappers in the FormController class, you can use them to send commands to the FormControl instance in your custom application. For example, if you added a button to your application to make selected text bold in the FormControl, the code for the button would be as follows:

formController.ToggleFontFormattingBold();

Note
You can use the Object Browser to view the methods and properties defined in the FormController class, each of which provides a summary description of its behavior.

Further Exploration

You can learn more about how to use the FormControl in a custom Windows application by opening the HostedApplication sample project using the HostedApplication.sln file that is located in the C:\2007 Office System Developer Resources\Code Samples\InfoPath2007UsingIOLECommands_RTM folder.

You can learn more about how to use the InfoPathEditor COM object in a custom COM application by running the InfoPath2007UsingIOLECommandsCOM_RTM.exe installation package, and then opening the HostIP.sln file from the C:\2007 Office System Developer Resources\Code Samples\InfoPath2007UsingIOLECommandsCOM_RTM folder. The HostIP sample project is a Visual C++ solution that demonstrates how to use the InfoPathEditor COM object and IOleCommandTarget interface to host the Office InfoPath 2007 form editing environment in a COM application.

InfoPath Features Not Available in the FormControl

A number of InfoPath editor features do not work when you are hosting the FormControl in a custom application. The following items either do not function or are not provided automatically and require you to use the IOleCommandTarget interface to replicate the InfoPath form editing environment:

There are no menus or toolbars, but you can replicate this functionality by using custom menus and buttons along with their respective commands and the IOleCommandTarget interface.
There is no ink entry mode.
There are no custom or built-in task panes.
The object model is limited to the XmlForm object and below.
Forms protected with Information Rights Management (IRM) do not load.

Licensing Considerations

To use the FormControl in custom Windows applications, Office InfoPath 2007 is required to be installed on the computer that is used for developing the Windows application and on each computer that is used to run the compiled Windows application. If Office InfoPath 2007 is not installed on either the developer's or user's computers, the FormControl will not load. Furthermore, the assemblies associated with the FormControl cannot be redistributed (they must be installed by installing Office InfoPath 2007 itself).

Conclusion

If you need to host the InfoPath 2007 form editing environment in a custom Windows Forms application, the FormControl allows you to access the InfoPath object model and capture data submitted from an InfoPath form. Additionally, you can use the IOLECommandTarget interface to replicate the commands of the InfoPath 2007 form editing environment while maintaining control of the user experience.

Additional Resources

InfoPath Developer Portal

Information about InfoPath developer resources.
InfoPath Developer Reference for Managed Code

Overviews, programming tasks, and class library reference information to help you build Office InfoPath 2007 form templates that contain business logic written in Visual Basic or Visual C#.
Microsoft Office Online InfoPath Portal

Office Online site that provides information about InfoPath form design, declarative logic, and other features that are available through the InfoPath user interface.

Hosting the InfoPath 2007 Form Editing Environment in a Custom Windows Form Application

Overview

Adding the FormControl to the Visual Studio 2005 Toolbox

To add the FormControl to the Toolbox

Adding the FormControl to Your Application

Loading an InfoPath Form Template into the Control

To load an InfoPath form template into the FormControl

Handling the XML Data Submitted by the Form

Adding a SubmitToHostConnection in InfoPath 2007

To set up a new SubmitToHostConnection data connection

Handling the FormControl Submit Operation in the Hosting Application

Using the IOleCommandTarget Interface to Provide Extra Functionality

Using the IOleCommandTarget Interface in Your Custom Application

Importing the FormController.cs and NativeCommands.cs Resource Files into Your Visual Studio Solution

Adding a Using Statement to Your Main Form Code

Confirm References to Four Assemblies

Adding Initialization Code in the Application Code

Using FormController Commands to Add Functionality to the FormControl

Further Exploration

InfoPath Features Not Available in the FormControl

Licensing Considerations

Conclusion

Additional Resources

Additional resources