Export (0) Print
Expand All

Converting InfoPath 2003 Managed Code to the New InfoPath 2007 Object Model

Office 2007

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: Learn how to convert managed code created in InfoPath 2003 to use the new Microsoft Office InfoPath 2007 object model. (16 printed pages)

Microsoft Office InfoPath 2007 supports two managed-code object models for developing business logic (also known as form code) in form templates:

  • The Microsoft Office InfoPath 2003-compatible object model provided by the members of the Microsoft.Office.Interop.InfoPath.SemiTrust namespace

  • The new object model provided by the members of the Microsoft.Office.InfoPath namespace

The object model provided by the Microsoft.Office.Interop.InfoPath.SemiTrust namespace was introduced when InfoPath 2003 Service Pack 1 was released. Writing managed code using InfoPath 2003 requires Visual Studio .NET and the Microsoft Office InfoPath 2003 Toolkit for Visual Studio .NET, or Visual Studio 2005 and the Microsoft Office InfoPath 2003 Toolkit for Visual Studio 2005.

Office InfoPath 2007 opens and runs managed-code form templates that are created with InfoPath 2003, so you do not have to upgrade the form templates if your users do not have to open them in a Web browser. You can also use Office InfoPath 2007 to edit the business logic of InfoPath 2003 managed-code form templates, and to create new managed-code form templates that are backwardly compatible with InfoPath 2003.

However, if you want to deploy a managed-code form template that was created in InfoPath 2003 to Microsoft Office SharePoint Server 2007 or Microsoft Office Forms Server 2007 so that it can be opened in a Web browser, you must upgrade it to use the new object model. When you upgrade the form code, Office InfoPath 2007 automatically updates the project format and rebinds all the event handlers. However, you must rewrite the code in your event handlers and custom functions to use the new object model.

This article describes how to upgrade and convert your form code to use the new InfoPath 2007 object model. For more information about the full range of business logic support in Office InfoPath 2007, see Understanding InfoPath 2007 Object Models and Development Environments.

To upgrade your InfoPath 2003 form code to use the new object model, you must first open your old project correctly. You can do this by using the Microsoft Visual Studio Tools for Applications (VSTA) development environment that is included with Office InfoPath 2007, or by using the Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System or Visual Studio 2008 with Visual Studio Tools for Office development environments as described in the following procedures.

Important noteImportant

Before you can use VSTA or either of the Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System and Visual Studio 2008 with Visual Studio Tools for Office development environments to create and open InfoPath managed-code form templates, you must have the Microsoft .NET Framework 2.0 or later and Microsoft Core XML Services (MSXML) 6.0 installed. You can determine which versions of the .NET Framework are installed on your computer by opening the %SYSTEMROOT%\Microsoft.NET\Framework folder. This folder contains a folder for each version number of the .NET Framework that is installed.

On the MSDN Web site, you can download and install the redistributable packages for MSXML6 and the .NET Framework Version 2.0 or later. If you have Visual Studio 2005 installed, the .NET Framework 2.0 and MSXML6 are installed with it. If you have Visual Studio 2008 installed, the .NET Framework 3.5 and MSXML6 are installed with it.

After you install the .NET Framework 2.0 or later and MSXML6, you must install VSTA and .NET Programmability Support. To do that, select Customize when you first install Office InfoPath 2007, or use Add or Remove Programs to update your installation. To find the option to install VSTA in the 2007 Microsoft Office system Setup program, expand Microsoft Office InfoPath, expand .NET Programmability Support, and then expand .NET Programmability Support for .NET Framework version 2.0.

To upgrade InfoPath 2003 managed-code form templates in VSTA

  1. Open Office InfoPath 2007, and in the Getting Started dialog box (or on the File menu), click Design a Form Template.

  2. Under Open a form template, click On My Computer.

  3. Navigate to the project folder where the InfoPath 2003 managed-code form template project is saved.

    By default, this is a folder in C:\Documents and Settings\username\My Documents\Visual Studio Projects on the computer where the project was created. Or, you can move the folder to the location where InfoPath stores VSTA projects, which is C:\Documents and Settings\username\My Documents\InfoPath Projects by default.

    NoteNote

    If you are running Windows Vista, by default, these project folders are located in the C:\Users\username\Documents folder. Additionally, in all versions of Windows, if you changed the default location of the My Documents or Documents folder (using the Location tab of the Properties dialog box for the folder), the project folders are in that location.

  4. Click the manifest.xsf file, and then click Open.

  5. On the Tools menu, point to Programming, and then click Microsoft Visual Studio Tools for Applications.

  6. The message "This form template must be saved before you can add Visual Basic or C# code to it" is displayed. Click OK to continue.

  7. Locate the folder where you want to save the file, name the file, and then click Save.

  8. The message "This code was created with one of the InfoPath 2003 Toolkits for Microsoft Visual Studio. InfoPath needs to migrate the toolkit project to a new format" is displayed. Click OK to continue.

  9. Select the Visual Studio Solution (.sln) file for the project, and then click Open.

  10. The message "Your project has been migrated" is displayed when the migration process is complete. Click OK to continue.

  11. The message "The code in this form uses the InfoPath 2003 object model" is displayed with the prompt "Do you want to upgrade your code to use the Microsoft Office InfoPath object model?" Click Yes to upgrade the form template to use the new InfoPath 2007 managed-code object model provided by the Microsoft.Office.InfoPath namespace.

    Your form code is opened in the VSTA code editor. For your reference, all the code from your previous project is surrounded by #ifInfoPathManagedObjectModel and #endif (C#) statements, or #If InfoPathManagedObjectModel and #End If (Visual Basic) statements. You must rewrite this code to use members of the object model provided by the Microsoft.Office.InfoPath namespace.

To upgrade InfoPath 2003 managed-code form templates in Visual Studio

  1. Open Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System or Visual Studio 2008 with Visual Studio Tools for Office.

  2. On the File menu, click Open Project.

  3. Navigate to the project folder where the InfoPath Toolkit form template project is saved.

    By default, this is a folder in C:\Documents and Settings\username\My Documents\Visual Studio Projects on the computer where the project was created. Or, you can move the folder to the location of your choice.

    NoteNote

    If you are running Windows Vista, by default, this project folder is located in the C:\Users\username\Documents folder. Additionally, in all versions of Windows, if you changed the default location of the My Documents or Documents folder (using the Location tab of the Properties dialog box for the folder), the project folder is in that location.

  4. Click the solution file (.sln) for the project, and then click Open.

  5. In Solution Explorer, expand InfoPath Form Template, and then open manifest.xsf.

  6. On the Tools menu, click Form Options, and then click the Programming category.

  7. Under Programming language, click Upgrade OM.

  8. The message "The code in this form uses the InfoPath 2003 object model" is displayed with the prompt "Do you want to upgrade your code to use the Microsoft Office InfoPath object model?" Click Yes to upgrade the form template to use the new InfoPath 2007 managed-code object model provided by the Microsoft.Office.InfoPath namespace.

    Your form code is opened in the Visual Studio code editor. For your reference, the code from your previous project is surrounded by #if InfoPathManagedObjectModel and #endif (C#) statements, or #If InfoPathManagedObjectModel and #End If (Visual Basic) statements. You must rewrite this code to use members of the object model provided by the Microsoft.Office.InfoPath namespace.

You can also upgrade a form template that you created in Office InfoPath 2007 using the InfoPath 2003 object model, or you can upgrade a form template that you created in InfoPath 2003 but did not upgrade to use the new InfoPath 2007 object model the first time you opened it in Office InfoPath 2007, Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System, or Visual Studio 2008 with Visual Studio Tools for Office. The following procedure shows how to do this.

To upgrade a form template to use the InfoPath 2007 object model after it has been opened in InfoPath 2007

  1. Open the form template in Office InfoPath 2007, Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System, or Visual Studio 2008 with Visual Studio Tools for Office.

  2. On the Tools menu, click Form Options, and then click the Programming category.

  3. Under Programming language, click Upgrade OM.

  4. The message "The code in this form uses the InfoPath 2003 object model" is displayed with the prompt "Do you want to upgrade your code to use the Microsoft Office InfoPath object model?" Click Yes to upgrade the form template to use the new InfoPath 2007 managed-code object model provided by the Microsoft.Office.InfoPath namespace.

    Your form code is opened in the VSTA or Visual Studio code editor. For your reference, the code from your previous project is surrounded by #if InfoPathManagedObjectModel and #endif (C#)statements, or #If InfoPathManagedObjectModel and #End If (Visual Basic) statements. You must rewrite this code to use members of the object model provided by the Microsoft.Office.InfoPath namespace.

There are a number of differences between form code written against the InfoPath 2003 managed-code object model and the new InfoPath 2007 managed-code object model:

  • Changes to the assemblies and namespaces that are referenced

    During the upgrade process,Office InfoPath 2007 automatically handles changing references and adding the appropriate using or Imports statements to your project. The referenced assemblies share the same name as the namespaces that expose their members. For the members of the InfoPath 2003 managed-code object model (members of the Microsoft.Office.Interop.InfoPath.SemiTrust namespace), the referenced assembly is named Microsoft.Office.Interop.InfoPath.SemiTrust.dll. For members of the new InfoPath 2007 managed-code object model (members of the Microsoft.Office.InfoPath namespace), the referenced assembly is named Microsoft.Office.InfoPath.dll.

  • Changes in the way event handlers are bound

    When you use the InfoPath 2003 object model, InfoPath binds an event handler by decorating it with attributes implemented by the InfoPathEventHandlerAttribute class. When you use the new InfoPath 2007 object model, InfoPath binds an event handler in the form template's InternalStartup method using a statement that identifies the event and its delegate.

Additionally, the names of events have changed in the new object model. For example, the OnValidate() event is now named the Validating() event. When you upgrade an InfoPath 2003 managed-code form template, Office InfoPath 2007 automatically converts the code required for binding your event handlers, but does not convert the event handler code.

  • Changes to the name of the top-level object that represents a form template and how it is accessed in form code

    In the InfoPath 2003 object model, the class that represents the form template is named XDocument. In the InfoPath 2007 object model, the name of the class that represents the form template was changed to XmlForm. Additionally, in the InfoPath 2003 object model, you use a special private member variable named thisXDocument to access the members of the XDocument class that represents the form template where the form code is running. The thisXDocument variable is used from form code written in both Visual Basic and C#. In the InfoPath 2007 object model, you use the this keyword to access the XmlForm class from form code written in C# or the Me keyword from form code written in Visual Basic.

  • Changes to the names of some object model members with corresponding functionality

    As mentioned earlier, the XDocument class was renamed to the XmlForm class. Additionally, the names of the object model members for working with data sources have changed: the member names that contain the word "Adapter" in the InfoPath 2003 object model now contain the word "Connection." For more information about these members, see Working with Data Sources.

    Additionally, InfoPath 2003 object model member names that contain "Solution" now contain "Template" or "FormTemplate" instead. For example, the SolutionObject class is now named the FormTemplate class, and the Solution() property of the XDocument class is now named the Template() property of the XmlForm class.

  • Changes to the way you specify and work with XML data

    The InfoPath 2003 object model uses COM interop wrappers that work with MSXML5, whereas the InfoPath 2007 object model uses the XPathNavigator class of the System.Xml.XPath namespace and members of the System.Xml namespace.

  • Changes to the way optional parameters are specified

    Some members of the InfoPath 2003 object model allow optional parameters. The corresponding members in the InfoPath 2007 object model do not allow optional parameters, and instead have two or more overloaded methods or properties for different sets of parameters. For example, in the InfoPath 2003 object model, there is a single ExecuteAction(String, Object) method, and the varXmlToEdit parameter is optional (you can pass Type.Missing if you do not need to specify which field or group to edit). In the InfoPath 2007 object model, the ExecuteAction(ActionType) method is overloaded, and you must explicitly use the version with the xmlToEdit parameter if you need to specify which field or group to edit. Additionally, for reasons of type safety, if the Item property of a collection can accept either an integer or string value, there is an overloaded member for each data type. For example, the Item(Int32) property of ViewInfoCollection class is overloaded with a version of the property for each data type.

  • Changes to the way you specify a default view

    For more information, see Setting the Default View.

The examples in this section show how to convert a simple code sample that was written using the InfoPath 2003 object model.

This section has three parts:

  • A description of the original example written against the InfoPath 2003 managed-code object model.

  • A description of the changes made by InfoPath after you run the upgrade procedure to convert the code project and rebind the form template's event handlers.

  • A description of the steps required to rewrite the code to use the InfoPath 2007 managed-code object model.

Original InfoPath 2003 Managed Code

When you work with the InfoPath 2003 object model, you use the thisXDocument private member variable to access the XDocument object from form code. Also, you use the same member variable in form code written in both the Visual Basic and C# languages.

The following code example shows an event handler for the OnValidate event written using the InfoPath 2003 object model. It uses the thisXDocument variable to access the DOM() and UI() properties of the XDocument object.

<InfoPathEventHandler( _
   MatchPath:="/my:myFields/my:field1", _
   EventType:=InfoPathEventType.OnValidate)> _
Public Sub field1_OnValidate(ByVal e As DataDOMEvent)
   Dim field1 As IXMLDOMNode = _
      thisXDocument.DOM.selectSingleNode("/my:myFields/my:field1")
   thisXDocument.UI.Alert("The value in field1 is " & field1.text)
End Sub

Changes Made in the Upgrade Procedure

The next example shows what the previous example looks like after you use the upgrade procedure described in the Upgrading a Form Template That Uses the InfoPath 2003 Object Model section of this article.

The example shows the following changes:

  • InfoPath removes the InfoPathEventHandler attributing for binding the event handler. Although the code is not shown, InfoPath replaces this attributing with a statement in the InternalStartup method of the form, which uses the EventManager class to bind the event.

  • The name of the event in the handler signature changes from OnValidate to Validating, and the parameters in the signature change to reflect the definition of the XmlValidatingEventHandler delegate.

  • The DataDOMEvent event object was replaced by the XmlValidatingEventArgs event object (which ultimately derives from the System.EventArgs class in the .NET Framework).

  • All the original code within the event handler is surrounded by #if/#endif (C#) or #If/#End If (Visual Basic) compiler directives. This preserves your original code, but effectively comments it out and prevents it from running.

Public Sub field1_Validating( _
   ByVal sender As Object, ByVal e As XmlValidatingEventArgs)
#If InfoPathManagedObjectModel Then
   Dim field1 As IXMLDOMNode = _
      thisXDocument.DOM.selectSingleNode("/my:myFields/my:field1")
   thisXDocument.UI.Alert("The value in field1 is " & field1.text)
#End If
End Sub

Rewriting the Code

The final example in this section shows what the event handler looks like after it is rewritten to use members of the new InfoPath 2007 object model.

The code shows the following changes:

  • The #if/#endif (C#) and #If/#End If (Visual Basic) compiler directives are removed to uncomment the code.

  • The this (C#) or Me (Visual Basic) keywords are used to access members of the new XmlForm object, which replaces the XDocument object when you are working with the InfoPath 2007 object model.

  • The code for accessing the value of field1 has changed. For more information about how this works, see the Getting Started with XPathNavigator and System.Xml section in this article.

  • The UI object and Alert(String) method no longer exist in the new object model; they are replaced by a call to the Show method of the MessageBox class.

Public Sub field1_Validating( _
   ByVal sender As Object, ByVal e As XmlValidatingEventArgs)
   Dim field1 As XPathNavigator = _
      Me.CreateNavigator().SelectSingleNode( _
      "/my:myFields/my:field1",Me.NamespaceManager)
   MessageBox.Show("The value in field1 is " + field1.Value)
End Sub

NoteNote

The MessageBox.Show method is not supported for browser-enabled form templates. If you want to convert your form template code so that it can be opened in a Web browser from Microsoft Office SharePoint Server 2007 or Microsoft Office Forms Server 2007, you must convert code that uses the UI.Alert method to display the message some other way. One method is to display the message by writing it to a node that is bound to another control on the form. Or, if the information is a validation error, you can add that information to the FormErrorCollection class associated with the form by using the Errors() property to access the collection, and then using the Add(XPathNavigator, String, String) method.

For most controls, InfoPath provides a tooltip to display such an error to the user. Additionally, when a form is open in InfoPath, users can display any errors in the form's collection by using the Go to Next Error and Show Error Message commands on the Tools menu. Similarly, when a form is open in the browser, users can press CTRL+ALT+R to go to the next error or CTRL+SHIFT+I to display a message box that contains error details.

When you are working with XML data using the InfoPath 2003 object model, you use an MSXML5-based object model. For example, to read and write a field's value using the members of the Microsoft.Office.Interop.InfoPath.SemiTrust namespace, you use the DOM() property to access the form's underlying XML document, and then use the selectSingleNode method to access the field and assign it to an IXMLDOMNode object, as shown in the following example.

Dim xpath As String = "/my:myFields/my:field1"
Dim field1 As IXMLDOMNode = thisXDocument.DOM.selectSingleNode(xpath)
Dim oldValue As String = field1.text ' Read
field1.text = "New Value"            ' Write

The InfoPath 2007 object model provided by members of the Microsoft.Office.InfoPath namespace uses the XPathNavigator class of the System.Xml.XPath namespace to work with form data sources.

The following example shows how to do the same thing as the previous example using the new object model.

Dim xpath As String = "/my:myFields/my:field1"
Dim field1 As XPathNavigator = _
   MainDataSource.CreateNavigator().SelectSingleNode( _
   xpath, NamespaceManager)
Dim oldValue As String = field1.Value ' Read
field1.SetValue("New Value")          ' Write

Table 1 summarizes the differences between using the InfoPath 2003 object model and the InfoPath 2007 object model for basic field data access.

Table 1. Summary of Basic Field Data Access Differences

Operation

InfoPath 2003 OM

InfoPath 2007 OM

Access form data source

thisXDocument.DOM

this.MainDataSource

Select node

IXMLDOMNode

XPathNavigator

Read node

field1.text

field1.Value

Set node

field1.text

field1.SetValue

For detailed information and examples of using the XPathNavigator class to work with XML data using members of the new InfoPath 2007 object model, see Working with XML Data Using the XPathNavigator Class in InfoPath 2007 Form Templates.

Some object model members that are used for working with data sources have been rearchitected and renamed in the InfoPath 2007 object model, but in most respects they remain functionally similar to InfoPath 2003 object model members. The following list summarizes the most important differences.

  • The DataObjectsCollection object and the DataSourceObject object from the InfoPath 2003 object model were renamed to make them consistent with one another. They are now named the DataSourceCollection object and the DataSource object in the InfoPath 2007 object model.

  • The DataAdaptersCollection object in the InfoPath 2003 object model was renamed to the DataConnectionCollection object. This was done to match the term "Data Connection" that is used for the Data Connections command on the Tools menu and in other user interface text. Also, the base class from which all "Data Connection" objects are derived is exposed as the DataConnection class.

  • The various "Data Adapter" objects, such as the ADOAdapterObject object, have also been renamed, replacing "Adapter" with "Connection" to match the user interface term. Additionally, except for the WebServiceConnection class, there are now separate objects for submitting to, or querying from, a data connection. For example, where the InfoPath 2003 object model has a single ADOAdapterObject, the InfoPath 2007 object model has two objects: the AdoQueryConnection object and the AdoSubmitConnection object. The classes for data connections that support only one kind of operation, such as the connection to a SharePoint list, are now explicitly named using the operation they support: SharepointListQueryConnection.

  • The methods for querying or submitting data, such as the Query() method and the Submit() method of the ADOAdapterObject object in the InfoPath 2003 object model, have been replaced with the Execute() method of the DataConnection base class. The Execute method is inherited by all classes that represent data connections and is exposed as an inherited method of that class, such as the EmailSubmitConnection.Execute() method. Depending on the kind of data connection represented by the inheriting class, the Execute method performs the declared submit or query operation appropriate to that connection.

  • As you do with other members of the InfoPath 2007 object model, you now use the this or Me keywords to access the DataSourceCollection object using the DataSources() property of the XmlForm class. Also, instead of using MSXML5-based data operations to work with the XML data of an external data source, you now use the XPathNavigator class and System.Xml.

For more information about working with external data sources using the new InfoPath 2007 object model, see How to: Access External Data Sources.

When you use the InfoPath 2003 managed-code object model, you set the default view by setting the IsDefault() property of the ViewInfoObject class that represents the view to true as shown in the following example.

Dim viewName As String = thisXDocument.DOM.selectSingleNode( _
   "/my:myFields/my:DefaultViewName").text
thisXDocument.ViewInfos(viewName).IsDefault = True

When you use the new InfoPath 2007 object model, the IsDefault property is no longer available; it has been replaced by the SetDefaultView(ViewInfo) method of the LoadingEventArgs class. The SetDefaultView method is available only from an event handler for the Loading() event, as shown in the following example.

Public Sub FormEvents_Loading(ByVal sender As Object, _
   ByVal e As LoadingEventArgs)
   Dim viewName As String = _
      MainDataSource.CreateNavigator().SelectSingleNode( _
      "/my:myFields/my:DefaultViewName", NamespaceManager).Value;
   e.SetDefaultView("viewName")
End Sub

In addition to converting your form code to the new InfoPath 2007 object model, you must also make sure that the design of your form template conforms to certain limits required to work in a Web browser. Office InfoPath 2007 provides a compatibility setting and the Design Checker task pane to help you make sure that your form template will run when it is opened in a Web browser.

For information about how to use these features and how to write form code that works when a form template is deployed to Microsoft Office SharePoint Server 2007 or Microsoft Office Forms Server 2007, see the following resources:

You can use Office InfoPath 2007 to open managed-code form templates that were created with InfoPath 2003. However, if you want to deploy one of these form templates to Microsoft Office SharePoint Server 2007 or Microsoft Office Forms Server 2007 so that it can be opened in a Web browser, you must first upgrade the form template, and then rewrite the form code to use the new InfoPath 2007 managed-code object model. This article contains the steps to open and upgrade InfoPath 2003 managed-code form template projects, and information about how to rewrite your form code to use the new InfoPath 2007 object model.

Show:
© 2014 Microsoft