Handle Errors Using the InfoPath 2003 Object Model

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 2003-compatible object model supports error handling through the use of the ErrorObject object in association with the ErrorsCollection collection.

In InfoPath, errors can occur 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 DataDOMEventObject object, or when an error is created using the Add method of the ErrorsCollection collection.

Overview of the ErrorsCollection Collection

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

Overview of the ErrorObject Object

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

Using the ErrorsCollection and ErrorObject

The ErrorsCollection collection is accessed through the Errors property of the XDocument object. The ErrorsCollection collection is associated with a form's underlying XML document so that when an error occurs, it occurs within the XML document. The following example demonstrates how a Visual C# foreach 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 ShortErrorMessage property of the ErrorObject object, displays a message box to the user.

public void CheckErrors(IXMLDOMNode xmlNode)
{
   foreach(ErrorObject err in thisXDocument.Errors)
   {
      if(xmlNode==err.Node)
         thisXDocument.UI.Alert("The following error has occured: "
             + err.ShortErrorMessage + ".");
   }
}

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

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 DataDOMEventObject object, or by using the Add method of the ErrorsCollection collection. For information about using the ReportError or Add methods, click the 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.

DataAdapters dataAdapters;
dataAdapters = thisXDocument.DataAdapters; 
XMLFileAdapterObject queryXMLFile = 
   (XMLFileAdapterObject)dataAdapters["form1"];
// Perform the query.
try
{
   queryXMLFile.Query();
}
catch (Exception ex)
{
   thisXDocument.UI.Alert("Failed to query.\n\n" + ex.Message);
}
// Perform the submit.
try
{
   queryXMLFile.Submit();
}
catch (Exception ex)
{
   thisXDocument.UI.Alert("Failed to submit.\n\n" + ex.Message);
}

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.