Handle Errors

When creating custom applications, developers must often perform error handling that involves writing programming code to check for errors raised by the application or to create and raise custom errors. The InfoPath object model provided by the Microsoft.Office.InfoPath namespace supports error handling through the use of the FormError class in association with the FormErrorCollection class.

In InfoPath, errors can occur for the following reasons:

• When data entered into a form fails XML schema validation.

• When a custom validation constraint fails.

• When an error is generated by the ReportError method of the XmlValidatingEventArgs event object.

• When a user-defined error is created using the Add method of the FormErrorCollection class.

Overview of the FormErrorCollection Class

The FormErrorCollection class provides the following methods and properties, which form developers can use to manage the FormError objects that the collection contains.

Overview of the FormError Class

The FormError class provides the following properties, which form developers can use to access information about the error that was raised.

Using the FormErrorCollection and FormError Classes

The FormErrorCollection object associated with a form is accessed through the Errors property of the XmlForm object. The FormErrorCollection object is associated with a form's underlying XML document so that when an error occurs, it and any additional errors can be accessed and managed within the current XML document. The following example demonstrates how a loop can be used to check the errors that may exist in a form's underlying XML document. If there are errors, the function loops through each of them, and, using the Message property of the FormError object, displays a message box to the user.

public void CheckErrors(XPathNavigator xmlNode)
{
   foreach(FormError err in this.Errors)
   {
      if(xmlNode.InnerXml == err.Site.InnerXml)
         MessageBox.Show("The following error has occured: "
             + err.Message);
   }
}

Public Sub CheckErrors(ByVal xmlNode As XPathNavigator)
   Dim err As FormError
   For Each err In Me.Errors
      If xmlNode.InnerXml = err.Site.InnerXml Then
         MessageBox.Show("The following error has occured: " _
             & err.Message)
   End If
End Sub

The preceding function could be called from one of the form's data validation event handlers. For example, when used in the event handler for the Changed event of a field in the form, the call to the function would pass the XML node argument using the Site property of the XmlEventArgs event object as follows.

CheckErrors(e.Site);

CheckErrors(e.Site)

In addition to handling errors generated by InfoPath, form developers can also generate custom errors by using the ReportError(XPathNavigator, Boolean, String) method of the XmlValidatingEventArgs event object, or by using the Add method of the FormErrorCollection class. For information about using the ReportError(XPathNavigator, Boolean, String) or Add methods, click the links for those methods at the beginning of this topic.

Handling Managed-Code Exceptions

You can use try-catch exception handling to handle exceptions raised in managed-code form template as shown in the following code example.

FileQueryConnection queryXMLFile = 
   (FileQueryConnection)this.DataConnections["form1"];
// Perform the query.
try
{
   queryXMLFile.Execute();
}
catch (Exception ex)
{
   MessageBox.Show("Failed to query." + System.Environment.NewLine 
      + ex.Message);
}

Dim queryXMLFile As FileQueryConnection = _
   DirectCast(Me.DataConnections("form1"), FileQueryConnection)
' Perform the query.
Try
   queryXMLFile.Execute();
Catch ex As Exception
   MessageBox.Show("Failed to query." & System.Environment.NewLine 
      & ex.Message)
End Try

If you do not use try-catch exception handling in your form code, InfoPath will display information about unhandled exceptions in the InfoPath error dialog box while debugging and previewing. Additionally, by default, unhandled exceptions are not displayed in the InfoPath error dialog box at run time when you deploy your managed-code form template. To display information about unhandled exceptions at run time, use the following procedure.

Enable notifications for unhandled managed-code exceptions at run time

1. Open the InfoPath designer, and then click the File tab.

2. Click Options, and then click InfoPath Options under the General category.

3. On the Advanced tab, select the Show a notification for Visual Basic and C# code errors check box.