Examining the Exception Management Application Block (EMAB)

By Scott Mitchell

Introduction

In an earlier article - An Introduction and Overview of the Microsoft Application Blocks - author John Jakovich showcased Microsoft's application blocks, mentioning their benefits. Application blocks are Visual Studio .NET Projects available for free from Microsoft that can be used in your ASP.NET Web applications. These application blocks are created to solve a common programming task, and highlight Microsoft's recommended "best practices."

- continued -

Microsoft has released a number of applications blocks to date. The most pertinent one to ASP.NET developers, in my opinion, is the Data Access Application Block (or DAAB), which John Jakovich discusses in Examining the Data Access Application Block. The DAAB provides a class with methods to access data from a SQL Server database with just one line of code, thereby reducing the tedium associated with writing data access code. This article looks at another application block that you can start using in your ASP.NET Web applications today - the Exception Management Application Block (or EMAB).

The Goal of the Exception Management Application Block

While we all like to think that we write bug free code, even the most skilled developer's code will, at times, contain flaws. These flaws - such as an incorrect connection string, not checking to see if an object is Nothing or null before using it, or attempting to access an array with an invalid index - all result in exceptions. Even if you are the best coder in the world, exceptions can still arise due to conditions out of your control, such as the database server crashing, or someone accidentally deleting a needed file from the Web server. The point is, exceptions happen.

What do you do when an exception happens in one of your ASP.NET Web applications? Is an administrator notified of the exception? Do you record the transaction in a database or in the Web server's Event Log, to maintain a history of exceptions. Imagine you wanted to record all exceptions to a database. To accomplish this you'd need to place code that might cause an exception in a Try ... Catch block, and in the Catch portion you'd record the information to the database. The following code illustrates this:

Try ... code that might cause an exception ... Catch ex as Exception ... connect to database ... ... insert a row into an ExceptionLog table, adding details about the exception ... End Try

The problem with the above code is that it tightly couples the behavior with the code. That is, imagine that you added this code to all of the ASP.NET page's code behind files' methods. Then, right as you finished, your boss said, "On second thought we want to not publish the details in the database, but rather just have the administrator emailed." Arghrhghgh!! Now you have to go back and change each and every ASP.NET code-behind class' methods - what a pain!

A better approach is to encapsulate the exception publishing action in a separate class. Then, if you needed to change the behavior that should occur when publishing an exception, you'd only need to make one change - the class designed to publish information about the exception. Enter the Exception Management Application Block...

The Exception Management Application Block (EMAB) is an application block designed to "publish" exception information. "Publishing" might involve recording the exception's details to a database, paging the system administrator, adding an entry to the Event Log, or some other custom task. The point is, with the EMAB you can write a class yourself to indicate precisely what "publishing" an exception involves.

Using the EMAB in an ASP.NET Web application is fairly straightforward. We'll talk about downloading and installing the EMAB shortly, but for now let's look at the code that will be used in an ASP.NET Web page to publish an exception:

Try ... code that might cause an exception ... Catch ex as Exception ExceptionManager.Publish(ex) End Try

The EMAB provides a class, ExceptionManager, that has a Publish() method that accepts an Exception instance. It then "publishes" the exception information. (Again, what, precisely, publishing means can be customized.) The nice thing about the EMAB is that if you need to add or change what, exactly, publishing an exception entails, you need to only make a change to the publisher (more on this later), rather than to any code in the ASP.NET Web application.

Downloading and Installing the Exception Management Application Block

You can download the EMAB from Microsoft at http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=8CA8EB6E-6F4A-43DF-ADEB-8F22CA173E02. The download comes as an MSI file. Once you double-click the MSI file, it will prompt you for a directory location and then copy the EMAB Visual Studio .NET project to that directory. The EMAB - as with all of the Microsoft application blocks - provides two Visual Studio .NET projects: one in C# and one in VB.NET.

Once you have downloaded and created the Visual Studio .NET projects, you need to compile the project before you can use the EMAB in an ASP.NET Web application. To do this, open the Visual Studio .NET project in whatever language you prefer (you can do this through the Start menu), go to the Build menu and choose Build Solution. This will compile the project into an assembly (.dll file).

To use the EMAB in an ASP.NET Web application, open up the ASP.NET Web application and then add the EMAB assembly to the Web application's References folder. To accomplish this, right-click on the References folder, click on the Browse button and navigate to the EMAB assembly. Once you have added the assembly you'll still need to specify some configuration settings in the Web application's Web.config file before using the EMAB. We'll get to these settings in a moment, but first let's look at how to define how exceptions are published with the EMAB.

Default and Custom Publishers

The ExceptionManager class, itself, does not publish exception information. Rather, when its Publish() method is invoked, it examines the Web application's Web.config file to determine what publisher to use to publish the exception's details. A publisher is a class that implements the IExceptionPublisher interface. This interface defines a single method - Publish(Exception). The EMAB comes with a default publisher that publishes the exception information to the Web server's Event Log.

The good news, however, is that you can create your own custom publisher. This is accomplished by creating a class that implements IExceptionPublisher and putting the logic in the class's Publish() method. Want your exception information to be logged to a database? Write in the ADO.NET commands to accomplish this in the Publish() method (using the Data Access Application Block, ideally). Want to have the administrator emailed? Put the code here in the Publish() method. Since you are creating the class, you can specify precisely how an exception is "published."

A Note About the Default Publisher and Web Applications

Since the default publisher writes to the Event Log, the process using the EMAB must have adequate permissions to access the machine's Event Log. Read the Frequently Asked Questions section on the Exception Management Application Block homepage for more information on this issue. Essentially you'll need to run an installer that configures Event sources that the ASPNET account can access.

Configuring the Exception Management Application Block

To use the EMAB in an ASP.NET Web application you need to add some settings to the Web.config file to indicate that the EMAB should be used and what, if any, custom publishers should be used. The basic settings in the Web.config look like the following:

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

The <section> element in the <configSections> section specifies that there is an <exceptionManagement> section. The <exceptionManagement> section, then, indicates that the EMAB should perform exception publishing. This configuration uses just the default publisher. You can also indicate that one or more custom publishers should be used through the following syntax:

<configuration> ... <exceptionManagement mode="on"> <publisher assembly="assembly" type="namespace.className" /> </exceptionManagement> ... </configuration>

Here a single, custom publisher is used. Assuming you've created a custom publisher class, you simply specify its assembly and type in the appropriate attributes of the <publisher> element.

A Real-World Example of the Exception Management Application Block in Action!

I've used the EMAB in several projects I've worked on. Typically I create a custom publisher that adds the exception's details to a database table. The following shows my custom publisher class, my Web.config settings, and an example ASP.NET Web page.

Custom Publisher

Imports Microsoft.ApplicationBlocks.ExceptionManagement Imports System.Web Imports System.Data.SqlClient Imports Microsoft.ApplicationBlocks.Data Public Class DBExceptionPublisher Implements IExceptionPublisher Public Sub Publish(ByVal exception As System.Exception, _ ByVal additionalInfo As NameValueCollection, _ ByVal configSettings As NameValueCollection) _ Implements IExceptionPublisher.Publish Try SqlHelper.ExecuteNonQuery(GlobalConnectionString, CommandType.StoredProcedure, "sp_AddException", _ New SqlParameter("@Message", exception.Message)) Catch ex As Exception HttpContext.Current.Response.Write("FATAL ERROR:<br>" & _ ex.StackTrace & "<br><br>" & ex.Message) HttpContext.Current.Response.Flush() HttpContext.Current.Response.End() End Try End Sub End Class

The above is a very simple custom publisher (a shortened version of the custom publisher I use in practice). Notice that the class implements the IExceptionPublisher interface (which is defined in the Microsoft.ApplicationBlocks.ExceptionManagement namespace). The Publish() method uses the DAAB to run the sp_AddException stored procedure, passing in the Exception's Message property. (In a real scenario, you'd likely be interested in additional Exception properties...) Note that it, itself, uses a Try ... Catch block - this is because there may be an exception in accessing the database! In such a case, an ugly FATAL ERROR message is emitted to the end user's screen. (It would be prudent to email the administrator here, and perhaps redirect the user to a prettier error page.)

Once this class has been created and compiled, the next step is to configure the ASP.NET Web application's Web.config file. Assuming that the DBExceptionPublisher is compiled into an assembly named MyProjectExceptionBlock, with a default namespace of MyProjectExceptionBlock, the configuration syntax would look like:

Web.configfile <configuration> ... <exceptionManagement mode="on"> <publisher assembly="MyProjectExceptionBlock" type="MyProjectExceptionBlock.DBExceptionPublisher" /> </exceptionManagement> ... </configuration>

Finally, let's look at an example ASP.NET Web page's code-behind class. Again, notice that to publish an exception we simply call the ExceptionManagement class's Publish() method. This consults the Web.config file, loads the proper custom publisher, and invokes its Publish() method, thereby publishing the exception details into the database.

An ASP.NET Web page code-behind class Imports Microsoft.ApplicationBlocks.ExceptionManagement Public Class logon Inherits System.Web.UI.Page Private Sub Page_Load(ByVal sender as Object, ByVal e as EventArgs) Try ... do something that might cause an exception ... Catch ex as Exception ExceptionManager.Publish(ex) End Try End Sub ... End Class

Happy Programming!

By Scott Mitchell