Adding a New Exception Formatter

Retired Content
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.
The latest Enterprise Library information can be found at the Enterprise Library site.

To add a new exception formatter, you must create a new exception class that derives from the ExceptionFormatter class. Your new class can derive directly from ExceptionFormatter or from one of the exception formatters that ship with the Exception Handling Application Block. The application block includes the classes TextExceptionFormatter and XmlExceptionFormatter, both of which derive from the ExceptionFormatter class.

Beginning with Enterprise Library 4.1 exception formatters must include the handling instance ID, HandlingInstanceId. The handling instance ID value is generated on each exception handling request. Each individual exception formatter handles the handling instance ID as appropriate for that formatter. The XmlExceptionFormatter adds it as an attribute of the top-level Exception element, while the TextFormatter adds it as the first line of text. An HandlingInstanceId equal to Guid.Empty can be ignored.

Beginning with Enterprise Library 4.1 the logging exception handler no longer adds the exception handling ID to the message to log. The formatter handles the ID. Exception Formatter types used with the Logging exception handler must implement a constructor with the parameters TextWriter, Exception, and Guid.

There is no backwards compatibility support. Creators of custom formatters must update them to be used with the newer version so that the handling instance ID is not lost because a formatter does not support it.

The ExceptionFormatter.CreateMessage method now has the to the Guid handlingInstanceID as shown in the following code snippet.

protected virtual ExceptionFormatter CreateFormatter(
            StringWriter writer,
            Exception exception,
            Guid handlingInstanceID)

'Usage
Protected Overridable Property CreateFormatter(() As ExceptionFormatter
End Property
            StringWriter writer,
            Exception exception,
            Guid handlingInstanceID)

Creating a New Exception Formatter Class

This procedure describes the general steps you should take to create a custom formatter.

To create a new exception formatter class

1. Create a new class that derives from ExceptionFormatter.
2. Override the methods declared for formatting the exception information. The ExceptionFormatter class declares several abstract and virtual methods used for constructing formatted exception information. For a list and description of the methods that can be overridden, see ExceptionFormatter in the Reference section.

The following code shows a custom exception formatter that overrides the WriteStackTrace method to exclude stack trace information.

public class AppTextExceptionFormatter : TextExceptionFormatter
{
  public AppTextExceptionFormatter(TextWriter writer, Exception exception, Guid handlingInstanceID)
    : base (writer, exception, handlingInstanceID) 
  {
  }

  protected override void WriteStackTrace(string stackTrace) 
  {
  }
}

'Usage
Public Class AppTextExceptionFormatter
  Inherits TextExceptionFormatter

  Public Sub New(ByVal writer As TextWriter, ByVal e As Exception, ByVal handlingInstanceID As Guid)
    MyBase.new(writer, e, handlingInstanceID)
  End Sub

    Protected Overrides Sub WriteStackTrac(ByVal stackTrace As String)
    End Sub

End Class