How to: Handle Errors

Article
06/23/2010

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 an 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.

Name	Description
Add method (+3 overloads)	Creates a FormError object and adds it to the collection.
Delete method (+1 overload)	Deletes the specified user-defined error from the collection.
DeleteAll method	Deletes all FormError objects contained in the collection.
GetErrors (+1 overload)	Returns all FormError objects of the specified name or type from the collection.
Count property	Gets a count of the number of ErrorObject objects contained in the collection.
Item property	Gets a reference to an ErrorObject object based on the specified index number.

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.

Name	Description
DetailedMessage property	Gets or sets the detailed error message of the FormError object.
ErrorCode property	Gets or sets the error code of the FormError object.
Site property	Gets an XPathNavigator object that is positioned at the node associated with the FormError object.
Message property	Gets or sets the short error message of the FormError object.
FormErrorType property	Gets the type of the FormError object.

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 method of the XmlValidatingEventArgs event object, or by using the Add method of the FormErrorCollection class. For information about using the ReportError 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

Open InfoPath.
On the Tools menu, click Options.
On the Advanced tab, select the Show a notification for Visual Basic and C# code errors check box.

Share via