Adding a New Exception Formatter

Microsoft Enterprise Library 5.0

DropDown image DropDownHover image Collapse image Expand image CollapseAll image ExpandAll image Copy image CopyHover image

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 block includes the classes TextExceptionFormatter and XmlExceptionFormatter, both of which derive from the ExceptionFormatter class.

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. A HandlingInstanceId equal to Guid.Empty can be ignored.

The logging exception handler does not add 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 parameters of type TextWriter, Exception, and Guid, as shown in the following code.

C# Copy Code
public MyExceptionFormatter(TextWriter writer, Exception ex, Guid handlingInstanceId)
  : base(ex, handlingInstanceId)
{
  ...
}
Visual Basic Copy Code
Public Sub New(writer As TextWriter, ex As Exception, handlingInstanceId As Guid)
  MyBase.New(ex, handlingInstanceId)
  ... 
End Sub

Note:
If you have custom formatters designed for use with versions of Enterprise Library prior to version 4.1, you must update them so that the handling instance ID is not lost.

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.

C# Copy Code
public class AppTextExceptionFormatter : TextExceptionFormatter
{
  public AppTextExceptionFormatter(TextWriter writer, Exception exception, Guid handlingInstanceId)
    : base (writer, exception, handlingInstanceId) 
  {
  }

  protected override void WriteStackTrace(string stackTrace) 
  {
  }
}
Visual Basic Copy Code
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 WriteStackTrace(ByVal stackTrace As String)
  End Sub

End Class