.NET Reference Guide

The Exception Management Application Block

Last updated Nov 18, 2004.

The use of exceptions in .NET programming allows you to confine error handling to one or a small number of program areas. This is in contrast to environments that depend on HRESULT or other return codes that must be checked for each operating system call. With exceptions, rather than checking each function's return value, you write your code with the assumption that everything went right. You then wrap that code with an exception handler that will process any error conditions that arise. In simple programs, you often can get away with a single exception handler. More complex programs require multiple exception blocks. See the Exceptions topic for an introduction to exception handling.

Although naked .NET exceptions are useful for simplifying error handling, there is no provision for publishing the exceptions that occur. If you want all exceptions to be written to the event log or logged to a file, you have to write a considerable amount of custom code that is somewhat complex and difficult to get right.

Enter the Exception Management Application Block for .NET. This application block provides a simple, extensible, and configurable framework for handling and publishing exceptions. With a single line of application code in your exception handler, you can publish exception information to the system event log in a standard format. With slightly more work, you can create your own exception publisher that does whatever you want with the exception. For example, you could write the information to a log file or send an email to those responsible for the application. The Exception Management Application Block helps you:

• Manage exceptions consistently and efficiently.

• Isolate exception management code from business logic.

• Handle and log exceptions with a minimum of custom code.

Although it's possible to create your own exception publishing interface without the Exception Management Application Block, doing so effectively and efficiently is somewhat difficult. The Exception Management Application Block is free, tested code that is used with great success in many .NET applications. Although the code is supported "as-is", many programmers use it and provide informal support on Microsoft newsgroups. Official support is available from Microsoft for a fee.

A Sample Catch Statement

A typical try/catch block that uses the Exception Management Application Block would look like this:

[C#]

try
{
  // application code here
}
catch (Exception ex)
{
  ExceptionManager.Publish(ex)
}

[Visual Basic]

Try
  ' application code here
Catch ex as Exception
  ExceptionManager.Publish(ex)
End Try

That assumes, of course, that you've included a reference to the Exception Management Application Block in your code, and that you've configured it correctly.

Installation

You can download the Exception Management Application Block from the Microsoft Download Center link above. When you run the install package, it will install the application block code, documentation, and examples on your system. The following items are installed:

• Exception Management Application Block source code in C# and Visual Basic

• Quickstart Samples in C# and Visual Basic

• Documentation

The documentation is quite extensive. It includes sections on developing applications, deployment and configuration, and internal design of the Exception Management Application Block. The reference section documents all of the classes and interfaces that are implemented by the package.

After you've run the install package, you have three options for including the code in your project. You can:

• Copy the Exception Management Application Block project files from the install directory to your own application's directory, and include it as a project in your solution.

• Compile the project and copy the resulting assemblies to your application's directory and make file references to them.

• Compile the project and install the assemblies in the global assembly cache. Again, you would create a file reference in your project.

The supplied documentation covers each of these options quite well.

There is one final step you need to take before your programs can use the ExceptionManager class. You have to invoke the ExceptionManagerInstaller class to create the event sources that the default exception publisher uses. This is done at install time rather than at run time so that the application program doesn't need the elevated privileges required for creating event sources. If you use a .NET Setup and Deployment project to create a Windows Installer file for your application, the ExceptionManagerInstaller class will be set up automatically. If you use some other method of installation (XCOPY deployment, for example), then you need to run the Installutil.exe system utility to install against the Exception Management assembly.

Using the Exception Management Application Block

Once you've installed the application block, you can begin using it in your programs. You can publish any exception with the ExceptionPublisher class. For example, here's a simple program that throws an exception and publishes it to the event log using the default publisher:

[C#]

using System;
using Microsoft.ApplicationBlocks.ExceptionManagement;

namespace exb_cs
{
  class Class1
  {
    [STAThread]
    static void Main(string[] args)
    {
      try
      {
        GoDoSomething();
      }
      catch (Exception ex)
      {
        ExceptionManager.Publish(ex);
      }
    }

    static void GoDoSomething()
    {
      throw new ApplicationException("Big bad error here");
    }
  }
}

[Visual Basic]

Imports Microsoft.ApplicationBlocks.ExceptionManagement

Module Module1
  Sub Main()
    Try
      GoDoSomething()
    Catch ex As Exception
      ExceptionManager.Publish(ex)
    End Try
  End Sub

  Sub GoDoSomething()
    Throw New ApplicationException("Big bad error here.")
  End Sub

End Module

This program doesn't do anything but throw an exception. If you run it, it will just return to the command line. However, it publishes the exception in the event log. If you start the event viewer (from the Administrative Tools menu) and look in the Application Log, you will see the exception, as shown in the figure below.

Figure 38

If you double-click on the event, the Event Properties window appears, giving you more detail about the exception. For a naked .NET exception, the information is the same as what you'd see if you called ex.ToString() on the exception object.

Although you can use the ExceptionManager to publish standard .NET Exception types like ApplicationException as shown above, the Exception Management Applicaton Block documentation recommends that you instead derive your application's exceptions from BaseApplicationException. Doing so provides some additional contextual information in the exception object itself, which can be quite useful when you're reviewing an exception log.

Configuration

The default configuration uses the default publisher to publish exceptions to the Application event log. This method is used when there are no exception management settings in the application's configuration file, or if there is no configuration file at all. However, there are several settings that you can use to change how exceptions are published.

The code below shows how to include exception management in your application configuration file.

<configuration>
 <configSections>
  <section name="exceptionManagement"
       type="Microsoft.ApplicationBlocks.ExceptionManagement.ExceptionManagerSectionHandler,
          Microsoft.ApplicationBlocks.ExceptionManagement" />

 </configSections>

 <exceptionManagement mode="on/off">
  <publisher mode="on/off" assembly="AssemblyName" type="TypeName" 
        exclude="(+)Type;(+)Type" include="(+)Type;(+)Type" 
        exceptionFormat="xml" 
        customattr = "value" />

 </exceptionManagement>
</configuration>

The first part, configSections defines the section name and the assembly to which it pertains. The exceptionManagement section contains the exception management configuration settings. Note that the settings in the sample code above describe the syntax. This is not an actual configuration file. Configuration settings allow you to turn the publisher on or off, specify what types of exceptions are included or excluded from the publisher, and the format to be used for the log data. If you set exceptionFormat to "xml", then the log information is streamed in XML format.

If you're using the default publisher to publish exceptions to the Application log, you probably won't need to configure it. If you create a custom publisher, though, then you'll need to enable it through the configuration file. You can create and enable multiple publishers and configure them to publish all exceptions, or have some exceptions go to one publisher and other exceptions go to a different publisher.