In-Depth

Use InfoPath With VS.NET 2003

InfoPath SP1 and the new .NET 2003 Toolkit let you implement business logic behind InfoPath forms with managed VB.NET or C# code instead of JScript or VBScript event handlers.

Technology Toolbox: VB.NET, C#, XML, InfoPath 2003 Service Pack 1 (SP-1) Preview, InfoPath 2003 Toolkit for Visual Studio .NET, Visual Studio .NET 2003

Many Microsoft service packs only fix bugs and plug security holes. Microsoft Office InfoPath 2003 Service Pack 1 (SP-1) is an exception—it includes a full-scale upgrade of Microsoft's innovative XML-based data gathering and structural editing application. InfoPath SP-1 adds more than a dozen new declarative form design and deployment features to InfoPath 1.0. You can download and install a preview of InfoPath 2003 SP-1 that's planned for release in late June 2004 (. InfoPath SP-1 is a standalone version that doesn't require Office 2003 or the InfoPath 2003 release version. If you've installed InfoPath, you must remove it prior to running the SP-1 setup program.

Better yet, Microsoft has also released the Microsoft Office InfoPath 2003 Toolkit for Visual Studio .NET. Add this to SP-1, and you get the most significant new feature for Visual Studio developers: support for Visual Studio .NET 2003 and .NET Framework 1.1. InfoPath SP-1 now becomes the third Office System 2003 application to support VS.NET 2003 and .NET Framework 1.1. The Toolkit lets form developers implement business logic behind InfoPath forms with managed VB.NET or C# code instead of JScript or VBScript event handlers.

I'll give you an overview of the Toolkit and show how it integrates with InfoPath SP-1's XML data sources. I'll also describe briefly InfoPath SP-1's other important form design and deployment features. You'll get the most out of this discussion if you have some experience with InfoPath 1.0's form design mode.

You start by downloading the 138 MB InfoPath 2003 SP-1 preview, removing your original release version of InfoPath (if it's installed), and running Ipprev.exe. Then download and install the Toolkit (Ipvsproj.exe), which requires VS.NET 2003. The Toolkit installation adds a Microsoft Office InfoPath Projects node to Visual Studio's New Project dialog. Visual Basic Projects and Visual C# Projects subnodes display an InfoPath Form Template icon. Perhaps you've installed the Microsoft Visual Studio Tools for the Microsoft Office System (VSTO). If so, you'll find that creating a new InfoPath project resembles starting a Word document or template, or an Excel workbook project.

Double-clicking on the InfoPath icon creates a default InfoPathProject1 and displays a Microsoft Office Project Wizard dialog. The dialog lets you either create a new form or copy an existing InfoPath 1.0 or 1.1 form template file (FormName.xsn or manifest.xsf) to the project. The wizard upgrades version 1.0 template copies automatically. Click on Finish to extract or copy the template files to the project folder. The wizard adds Imports, Namespace ProjectName and Public Class ProjectName elements to the FormCode.vb file automatically.

The _Startup event handler assigns the form's Application instance to the thisApplication variable and the XDocument. This is how the event handler informs XDocument of the current state of the form's data source. Press F5 to build and run the project. The process opens an InfoPath window in design mode and displays a form preview.

Solution Explorer displays all form and project files (see Figure 1). The Project folder also includes the ProjectName.dll assembly file and, when you build the project in Debug mode, the ProjectName.pdb symbol file. These files don't appear in Solution Explorer if you don't choose Project, Show All Files. Building a project creates InfoPath's compressed ProjectName.xsn cabinet file in the ...\bin\Debug or ...\bin\Release folder; XSN files include the DLL and, if required, the PDB file to provide single-file deployment for production forms.

Projects disable JScript or VBScript code behind copied forms. However, the projects include the JS or VBS files in Solution Explorer for reference when you migrate script event handlers to managed code. You can import VBScript event-handling code into VB.NET event handlers. Most imported VBScript code builds with a few minor changes and Option Strict Off to permit late binding (see Listing 1).

Autogenerate Event Handlers
InfoPath projects include a Microsoft.Office.Interop.InfoPath.SemiTrust namespace reference and corresponding Imports statement. The namespace includes .NET wrapper classes for InfoPath COM objects categorized as Classes, Interfaces, Enums, and Delegates. Classes provide access to the Application object (see Figure 2). Classes also provide access to other InfoPath collections and their members, such as XDocuments and XDocument. Delegates represent the 13 events whose handlers you add from button and data source fields, from group properties dialogs, or from the Tools | Programming menu choice in the InfoPath designer. Examples of such events include OnClick for buttons and OnBeforeChange for the InfoPath data source.

Here's an autogenerated event-handling stub for a button click: 

' The following function handler is 
' created by Microsoft Office InfoPath. 
' Do not modify the type or number of 
' arguments.
<InfoPathEventHandler(MatchPath:= _
     "btnQuery", EventType:= _
     InfoPathEventType.OnClick)> _
     Public Sub btnQuery_OnClick(ByVal _
     e As DocActionEvent)
     ' Write your code here.
End Sub

The event handler's MatchPath: attribute value specifies the XPath expression for the element that raises the event. The EventType value represents a delegate—in this case, _ButtonEventSink_OnClickEventHandler. This value returns a DocActionEvent instance to the e argument. DocActionEvents for buttons have ReturnStatus (Boolean), Source (IXMLDOMNode), and XDocument (XDocument) properties.

The default event handler for the OnAfterChange event of the data source's OrderID attribute value returns a DataDOMEvent object to the e argument: 

<InfoPathEventHandler(MatchPath:= _
     "/dfs:myFields/dfs:dataFields/ _
     d:Orders/@OrderID", _
     EventType:=InfoPathEventType. _
     OnAfterChange)> Public Sub _
     Orders_OrderID_attr_OnAfterChange _
     (ByVal e As DataDOMEvent)

At this point, you write some code to restore the global state, then continue: 

If (e.IsUndoRedo) Then
     ' An undo or redo operation has 
     ' occurred and the DOM is read-only.
     Return
End If

Now a field change has occurred and the DOM is writeable. Write code here to respond to these changes and take you to the end of the subroutine.

The DataDOMEvent object has 22 properties and 14 methods. The e.DOM property returns the same IXMLDOMDocument instance as thisApplication.DOM. You can add code to modify the values of specified fields by the e.XDocument.DOM.selectSingleNode or getElementsByTagName method. InfoPath SP-1 uses Microsoft XML Core Services (MSXML) 5.0 to add support for inline schemas in ADO.NET DataSet objects returned by ASP.NET Web services. You'll need some familiarity with MSXML 4.0 or later programming to work with COM-based IXMLDOMNode and IXMLDOMDocument objects.

I'll describe InfoPath SP-1's new declarative form design features shortly. These features reduce—but don't eliminate—the need for script or managed code behind complex forms. For example, you now can assign the system date and time as a date picker's default value. Simply specify the Now() function in the control's Insert Formula dialog. I've created two sample projects to demonstrate form features that require coding. Both sample projects require installation of InfoPath SP-1 and the Toolkit.

Use Event Handlers to Validate
My Rss2Production project generates custom-formatted RSS 2.0 rss.xml files with XHTML-encoded <body> elements for Web content syndication (see Figure 3). The project uses event handlers to copy the content of the <description> field as the default value of the <body> field (see Listing 2). Event handlers also validate rss.xml against Jorgen Thelin's RSS 2.0 schema, and save a fully formatted rss.xml file to a Web server's root directory. Custom toolbar buttons require OnClick event handlers. You add their definition manually to the manifest.xsf file.

The NWOrdersWSProject.sln solution is a Web service client that consumes the NWOrdersWS ASP.NET Web service from the OakLeaf XML Web service demonstration site. The project uses VB.NET event handlers to implement an Insert Order operation, compare Order Date and Required Date values, and display the repeating table's Product Name and Unit Price from a single secondary data source (see Listing 3). These event handlers also show the running sum of line-item extended amounts in a table footer expression box (see Figure 4). You must modify the ViewName.xsl file's XSLT code for it to call the function that calculates the expression box's value.

The code must run with full-trust security permissions. Permissions are required for projects using managed code to access local machine resources directly—such as the file system—or to pass objects from ViewName.xsl to functions in managed code (to populate expression boxes). The SemiTrust part of the namespace reference corresponds to InfoPath's default domain-level security setting.

Both of my sample projects must run with full trust. Otherwise, you'll get security violation error messages when you execute an event handler or function that requires full trust. You get permission to debug full-trust forms in Visual Studio by using the .NET Framework 1.1 Configuration tool. This tool lets you add an InfoPath Form Templates code group to the My Computer\Runtime Security Policy\Machine\Code Groups\All_Code node. Then you assign full trust to the code group. (The sample code download includes a readme.txt file with detailed instructions for adding the code group.)

Granting forms full trust with InfoPath 1.0 requires running Regform.exe to create a Windows Installer or JScript file for deploying custom-installed forms on users' computers. You must redeploy such forms to every user every time you upgrade one of them. SP-1 lets you enable full trust by signing a form with a code-signing certificate. Users can cache the signed form from a server share, Web server, or Windows SharePoint Services site. Template changes update locally cached versions automatically when users open a new or existing form.

Exploit InfoPath's New Declarative Features
A new "Fill Out a Form" dialog box appears whenever you open InfoPath. The dialog box gives users the choice of displaying their most recently used forms, favorite forms, InfoPath sample forms, all your forms, or only the forms you designate by a custom category. Links to common tasks make it easy for users to fill out, design, or get updates to the selected form. Users have the option of preventing the "Fill Out a Form" dialog from appearing. A form conflict dialog lets them choose between multiple versions of the same form. AutoSave/AutoRecover handles system or application crashes efficiently.

InfoPath SP-1's upgraded capabilities now let you add an unlimited number of data validation expressions to groups and fields. Event-based rules let you display messages, change a field's value, query or submit with a specified data connection, or open a new form to complete. You can employ conditional formatting for almost every control type and bring up the Insert Formula dialog to add XPath expressions for setting default values.

User roles let you assign Active Directory security groups to roles you define by name, and specify a match or no match to the User's Current Role value in Condition dialogs. You can do the same thing with user accounts or usernames in a data source field. You also gain the flexibility of being able to assign digital signatures to individual data blocks. Otherwise, you'd only be able to sign the entire form. Now you can even specify multiple signatures as independent, sequence-independent (co-sign), or sequence-dependent (counter-sign).

I've only touched on the depth and variety of InfoPath's new and improved declarative design features. InfoPath SP-1 does offer a backward-compatibility option for creating forms that don't add the new features, which might be useful in some circumstances. However, I doubt many InfoPath developers will choose to forego the extended feature set. The benefits far outweigh the hassle of having to apply SP-1 to all InfoPath user machines when you implement the new features.

Now it's your turn to download and install InfoPath 2003 SP-1 and the InfoPath 2003 Toolkit for Visual Studio .NET. Give InfoPath 2003 SP-1's new managed code and declarative form design features a test drive. I believe you'll agree that the SP-1 upgrade delivers much more than a typical service pack or point release. Actually, I'd call it InfoPath 2.0. InfoPath 1.0 was an interesting new product, but it was hampered with a number of inconveniences and limitations. With InfoPath SP-1, Microsoft got it right the second time—thereby maintaining a longstanding Microsoft tradition.

Most   Popular