Exception Management Application Block for .NET<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />
<?xml:namespace prefix = v ns = "urn:schemas-microsoft-com:vml" />Related Links
Application Architecture for .NET: Designing Applications and Services
Kenny Jones, Graeme Malcolm, Alex Mackman, Edward Jezierski
Microsoft Corporation
April 2002
Summary: The Exception Management Application Block provides a simple yet extensible framework for handling exceptions. With a single line of application code you can easily log exception information to the Event Log or extend it by creating your own components that log exception details to other data sources or notify operators, without affecting your application code. The Exception Management Application Block can easily be used as a building block in your own .NET application. (18 printed pages)
Introduction
Are you involved in the design and development of .NET applications? Have you ever felt that you spend too much time writing error handling code? Have you struggled to diagnose problems in your applications due to a lack of detailed and consolidated diagnostic information? If so, the Exception Management Application Block for .NET is for you.
The Exception Management Application Block is an exception management framework that can easily be used as a building block in your own .NET application. If you use it, you will reduce the amount of custom error handling code you need to create, test, and maintain. You will also make your application more robust and easier to debug.
Specifically, the Exception Management Application Block helps you:
· Manage exceptions in an efficient and consistent way.
· Isolate exception management code from business logic code.
· Handle and log exceptions with a minimal amount of custom code.
In an application that references the Exception Management Application Block, you can publish an exception (for logging or operator notification) in a single line of code, as follows:
The remainder of this overview is divided into the following sections:
What Does the Exception Management Application Block Include?
Downloading and Installing the Exception Management Application Block
Using the Exception Management Application Block
Configuring the Exception Management Application Block
Extending the Exception Management Application Block
What Does the Exception Management Application Block Include?
The Exception Management Application Block consists of three Microsoft® Visual Studio® .NET projects, full source code, and comprehensive documentation.
Note You can customize the provided source code to suit individual requirements. However, note that the Exception Management Application Block is fully configurable through standard .NET XML configuration files and requires little, if any, internal customization.
The Visual Studio .NET Projects
Note that Microsoft Visual Basic® and Visual C#™ versions of the following projects are available within the Exception Management Application Block download:
· Microsoft.ApplicationBlocks.ExceptionManagement. Build this project to build the Microsoft.ApplicationBlocks.ExceptionManagement.dll assembly. This assembly contains the primary ExceptionManager class through which you publish exceptions, together with a DefaultPublisher class used to write exception details to the Windows Event Log and an ExceptionManagerInstaller class used at installation time to create Event sources for use with the Event Log.
· Microsoft.ApplicationBlocks.ExceptionManagement.Interfaces. Build this project to build the Microsoft.ApplicationBlocks.ExceptionManagement.Interfaces assembly. This assembly contains the interfaces that are implemented by publisher classes. This includes the DefaultPublisher class and optionally your own custom publishers.
· Exception Management Quick Start Samples. This project provides a set of quick start samples designed to show you how to use the Exception Management Application Block. Build this project to create a simple client application. This helps increase your understanding of how the Exception Management Application Block works and you can use it as a troubleshooting aid.
The Documentation
Comprehensive documentation is provided. This includes the following main sections:
· Developing Applications with the Exception Management Application Block. This section includes quick start samples, covering a range of common use cases that help you start to use the Exception Management Application Block quickly and easily. This section also explains how to extend the block by developing your own custom publisher components.
· Design and Implementation of the Exception Management Application Block. This section includes background design philosophy information that provides insights into the design and implementation of the Exception Management Application Block.
· Deployment and Operations. This section includes installation information; it discusses deployment options, use of the Global Assembly Cache, and the creation of Event sources by the installer class. It also includes configuration, security, and troubleshooting topics.
· Reference. This is a comprehensive API reference section that details the classes and interfaces comprising the Exception Management Application Block.
System Requirements
To run the Exception Management Application Block, you need the following:
· Microsoft Windows® 2000, Windows XP Professional
· The RTM version of the .NET Framework SDK
· The RTM version of Visual Studio .NET (recommended but not required)
Downloading and Installing the Exception Management Application Block
A Windows Installer file containing the Exception Management Application Block projects, source code and comprehensive documentation is available.
The install process creates a Microsoft Application Blocks for .NET submenu on your Programs menu. On the Microsoft Application Blocks for .NET submenu, there is an Exception Management submenu that includes options to launch the documentation and to launch the Exception Management Application Block Visual Studio.NET solution.
Go to MS.com Downloads to open the download.
Using the Exception Management Application Block
This section discusses how to use the basic features of the Exception Management Application Block. Additional information about these and other related topics can be found in the documentation included with the Exception Management Application Block download.
The topics discussed in this section include:
· Referencing the Exception Management Application Block
Publishing Exceptions
Figure 1 illustrates how the Exception Management Application block integrates seamlessly with your application and illustrates the chain of Events that occur when your application throws an exception.
Figure 1. Using the Exception Management Application Block
The flow of logic shown in Figure 1 to publish an exception is as follows:
1. The application throws an exception, which can be derived from the BaseApplicationException class provided in the Exception Management Application Block.
Note The Exception Manager can publish exceptions of type System.Exception (or any derived type) but you are encouraged to derive your own exception types from BaseApplicationException in order to benefit from additional contextual information provided by this class.
2. The application calls the Publish method of the ExceptionManager class.
3. The ExceptionManager class uses the ExceptionManagerSectionHandler class to retrieve the application's exception management settings. You can create these in any of the standard .NET XML configuration files at either the application or computer level.
4. The exception management settings in the application's configuration file (if any) are read to determine how the exception should be published.
5. If no settings are found, the exception is published in the Windows Event Log by using the DefaultPublisher class. If the application has exception management settings configured, the publishers listed in the configuration file, which can include the DefaultPublisher class and custom publisher classes, are used to publish the exception. All publishers implement at least one of the interfaces defined in the Interfaces assembly.
6. If an exception occurs while publishing through a custom publisher, the exception manager raises a CustomPublisherException and uses the default publisher to publish it in the Windows Event Log.
Referencing the Exception Management Application Block
To use the Exception Management Application Block, you must:
1. Build the Microsoft.ApplicationBlocks.ExceptionManagement project to generate the Microsoft.ApplicationBlocks.ExceptionManagement.dll assembly.
2. Set a reference to the Microsoft.ApplicationBlocks.ExceptionManagement.dll assembly.
3. Add a C# using or Visual Basic Imports statement to reference the Microsoft.ApplicationBlocks.ExceptionManagement namespace.
You can now publish exceptions by calling the Publish method of the ExceptionManager class. Because this is a static / Shared method, you do not need to instantiate an instance of the ExceptionManager class and can publish an exception through the type name in a single line of code.
Configuring the Exception Manager Application Block
The behavior of the Exception Management Application Block is controlled using standard .NET XML application configuration files; web.config for an ASP.NET application, or appname.exe.config for a Windows application. You can also apply configuration settings at the computer level by using machine.config.
Note If you do not supply any configuration settings, the Exception Manager simply uses the default publisher to publish exception details to the Windows Event Log.
Configuration Format
The exception management settings in the configuration file have the following format:
A <configSettings> element is used to associate the <exceptionManagement> element with the ExceptionManagerSectionHandler class, which is responsible for reading the settings from the <exceptionManagement> section of the configuration file.
For complete details of all the configuration options, see the documentation that is supplied with the Exception Management Application Block. In summary:
The mode attribute of the <exceptionManagement> element can be used to enable or disable the publication of all exceptions. Each custom publisher is identified with a <publisher> element beneath <exceptionManagement>. With the <publisher> element, you can customize individual publishers. For example, you can:
· Enable or disable selected publishers.
· Exclude or include specific exception types.
· Specify whether or not the exception details should be published in XML format.
· Define custom attributes that are passed by the Exception Manager to individual publishers. These can be used for any purpose. For example, you may want to supply an e-mail address to be used for operator notification purposes or the name of a custom log file.
Extending the Exception Management Application Block
You may be satisfied with the functionality of the default publisher, which writes exception details to the Windows Event Log. However, you may want to develop your own custom publishers to log exception details to alternate locations or perhaps to notify operators, maybe through Windows Management Instrumentation (WMI), that an exception has occurred.
Creating a Custom Publisher
To create a custom publisher, you must create a class that implements either the IExceptionPublisher or the IExceptionXmlPublisher interface defined within the Microsoft.ApplicationBlocks.ExceptionManagement.Interfaces.dll assembly.
If you want to receive exception details in XML format, implement IExceptionXmlPublisher, otherwise implement IExceptionPublisher. Each interface includes a single method called Publish, through which you receive exception details together with other optional configuration settings and custom attributes.
The following example shows a simple implementation of the IExceptionPublisher interface.
Configuring a Custom Publisher
After you create a custom publisher component, you need to hook it up with the Exception Manager. You do this by using a standard .NET XML configuration file. The following configuration file fragment shows how to configure the custom publisher shown previously.
Notice that a custom attribute called fileName is used to configure the name of the exception log for this custom publisher. This setting is passed to the publisher through the Publish method of the IExceptionPublisher interface.
Note To turn this custom publisher into an XML publisher that receives exception details in XML format, you need to implement the IExceptionXmlPublisher interface, and then add the exceptionFormat="xml" attribute to the <publisher> element in the configuration file. For more information, see the "Creating and Configuring an XML-Based Custom Publisher" section within the Exception Management Application Block documentation.
Internal Design
The main elements of the Exception Management Application Block are the following:
· The BaseApplicationException class. This class should be used as the base class for all of your custom application-defined exception classes. It ensures that all exceptions provide a minimum level of contextual information.
· The ExceptionManagerSectionHandler class. This class is responsible for reading configuration information from Microsoft .NET-based XML configuration files. You can configure various aspects of the Exception Management Application Block by using XML configuration files.
· The ExceptionManager class. This class is used to manage the process of publishing exception information. Its primary purpose is to invoke publishers including the default publisher class and any registered custom publisher classes, which you can create to log information to specific locations or notify operators; for example, through e-mail.
· The ExceptionManagerInstaller class. This installer class is used at installation time to create the Event sources required by the default publisher (and possibly custom publishers) to write exception details to the Windows Event Log. Event sources are created at installation time (and not run time) because it cannot be guaranteed that the security context of the Exception Manager at run time will provide sufficient access rights to be able to create Event sources.
· The DefaultPublisher class. This class provides basic publisher functionality, and in the absence of custom publishers is used by the ExceptionManager class to publish exception details. It logs exception details to the Microsoft Windows Event Log.
· The IExceptionPublisher and IExceptionXmlPublisher interfaces. Publisher classes implement these.
Figure 2 illustrates the main elements of the Exception Management Application Block.
Figure 2. The Main Elements of the Exception Management Application Block
The BaseApplicationException Class
The ExceptionManagement assembly provides a base application exception class called BaseApplicationException, which is designed to provide a base implementation for exceptions in your application. You are encouraged to derive from this class when you create custom exceptions to ensure that each custom exception raised in your application provides the base level of contextual information required for logging purposes. This contextual information includes:
· The computer name where the exception was created.
· The date and time when the exception occurred.
· The name of the application domain that was hosting your application.
· The thread identity where the exception occurred.
· The Windows identity of the thread.
· Additional custom information.
The BaseApplicationException class is also serializable, which means its state can be passed over a .NET remoting boundary.
The ExceptionManagerSectionHandler Class
The ExceptionManagerSectionHandler class is responsible for reading the configuration details from the <exceptionManagement> element within the configuration file.
This class is associated with the <exceptionManagement> section via a standard <section> element within the <configSections> of the configuration file.
The ExceptionManager Class
This class is at the heart of the Exception Manager assembly. It is through this class that you publish exceptions. The class is responsible for assimilating exception details and forwarding them to each configured publisher. In the absence of any configured custom publishers, the ExceptionManager class publishes to the default publisher.
The ExceptionManagerInstaller Class
This class is an installer class annotated with the RunInstaller(True) attribute. Its purpose is to create the Event sources required by the default publisher when writing to the Windows Event Log. You must ensure that the installer class is instantiated. This may or may not happen automatically and depends on how you install the Exception Manager assembly. For example:
· If you package the assembly within a Windows Installer file, the Windows Installer automatically instantiates the installer class.
· If you install the assembly by copying it to its target location (for example, using xcopy deployment), the installer class is not automatically instantiated. In this event, you should run the Installutil.exe system utility, which instantiates any installer classes within a specified assembly.
The DefaultPublisher Class
This class implements the IExceptionPublisher interface and provides publication functionality by logging exception details to the Windows Event Log. In the absence of any further configured custom publishers, this is the only publisher used.
You can configure the default publisher (alongside other custom publishers) by creating a <publisher> element for it in the configuration file. For example, this allows you to control the Event source name and log name that is used. For more details, see the "Configuring the Exception Management Application Block" section within the Exception Management Application Block documentation.
The IExceptionPublisher and IExceptionXmlPublisher Interfaces
These are the interfaces that publishers implement. A default publisher that logs exception details to the Windows Event Log is supplied, but you may want to develop your own custom publishers. For example, you may want to implement a custom publisher that publishes Event details by using Windows Management Instrumentation (WMI).
XML publishers that want to receive exception details in XML format implement IExceptionXmlPublisher while others (including the DefaultPublisher class) implement IExceptionPublisher. For full details of these interfaces, refer to the Exception Management Application Block documentation.
Frequently Asked Questions
What's new in this release?
The RTM release of Exception Management Application Block includes the following new features and changes from the Beta 2 release:
· The publisher interface names have changed from IPublishException and IPublishXmlException to IExceptionPublisher and IExceptionXmlPublisher respectively. This is to conform to .NET conventions, which state that only exception object types should end with the word "exception".
· The Microsoft.ApplicationBlocks.ExceptionManagement assembly now contains an installer class called ExceptionManagerInstaller. This is used at installation time to create the Event sources used by the default publisher to write to the Windows Event Log. You must ensure that this class is instantiated by your installation process.
The Beta 2 release of the Exception Management Application Block created event sources at runtime, which can cause problems for ASP.NET Web applications running with the default ASPNET account.
For more information about this issue, see Does the reduced privileges of the ASPNET account, used to run the ASP.NET worker process, cause problems for the exception manager when I'm using it within an ASP.NET Web application?
For more information about installation and deployment issues, see Can I use XCOPY deployment to deploy the exception management assemblies?
· The exclude and include attributes on the <publisher> element of the configuration file now allow you to exclude or include specific exception types, together with any type that derives from the specified exception type. You can indicate this by prefixing the type name in the configuration file with a + character.
For more information, see the "Configuring the Exception Management Application Block" topic, within the Deployment and Operations section of the documentation.
· The SerializeToXml method of the ExceptionManager class is now a public method, which allows you to easily serialize exception objects to XML. This was previously a private method.
Can I use XCOPY deployment to deploy the exception management assemblies?
Yes, with a caveat. As part of the installation process, you must ensure that the supplied installer class (ExceptionManagerInstaller) is instantiated in order to allow it to create the Event sources used by the default publisher when writing to the Windows Event Log. If you deploy the Exception Manager assembly within a Windows Installer package, the Windows Installer automatically instantiates the installer class. However, if you use xcopy deployment, you must manually instantiate the installer component by using the Installutil.exe system utility at install time. For more information, refer to the Exception Manager Application Block documentation.
Does the reduced privileges of the ASPNET account, used to run the ASP.NET worker process, cause problems for the exception manager when I'm using it within an ASP.NET Web application?
No. This was a problem with the Beta 2 release of the Exception Manager Application Block when used in conjunction with the RTM version of the .NET Framework (where the logon session that hosts the ASP.NET worker process changed from SYSTEM to ASPNET in order to provide a more secure security context).
The problem occurred because the Beta 2 release of the Exception Management Application Block created Event sources at run time when writing exceptions to the Windows Event Log. While the SYSTEM logon session provided the necessary access rights to create Event sources, the ASPNET logon does not.
To overcome this problem, the RTM release of the Exception Manager creates Event sources at installation time when administrative rights means that there is no problem creating Event sources. However, you must ensure that the supplied installer class is executed. For more information, see Can I use XCOPY deployment to deploy the exception management assemblies?
Do I need to configure the Exception Manager by using a .NET XML configuration file?
No. If you don't supply any configuration information, the exception manager publishes exception details to the Windows Event Log by using the supplied default publisher component. If you create your own custom publishers, these must be hooked up to the exception manager with configuration settings. You can also use configuration settings to fine tune the behavior of the exception manager. For example, you can determine precisely which exception types should be published and which should be ignored. You can also supply custom attributes which can be used by publishers, for example to control which Event Log is used to log exception details.
When excluding or including specific exception types do I have to list each type explicitly in the configuration file?
No. You can use the wild character "*" to exclude or include all exception types. Furthermore, you can prefix a specific type name with a "+" character to indicate that you want this type and any type derived from it either included or excluded. For more information, see the "Configuring the Exception Management Application Block" section within the Exception Manager Application Block documentation.
Are there any other application blocks?
The Exception Management Application Block is one of several Application Blocks that are being released. These Application Blocks solve the common problems that developers face from one project to the next. They can be plugged into .NET applications quickly and easily.
Feedback and Support
Questions? Comments? Suggestions? For feedback on the Exception Management Application Block, please send an e-mail message to [email protected].
The Application Blocks for .NET are designed to jumpstart development of .NET distributed applications. The sample code and documentation is provided "as-is." Support is available through Microsoft Product Support for a fee.
A newsgroup has also been created to assist you with the Application Blocks for .NET. Use this newsgroup to consult with your counterparts, peers, and Microsoft Support Professionals in an online, open forum.
Everyone else benefits from your questions and comments, and our development team is monitoring the newsgroup on a daily basis:
Newsgroup: Web-Based Reader
http://msdn.microsoft.com/newsgroups/loadframes.asp?icp=msdn&slcid=us&newsgroup=microsoft.public.dotnet.distributed_apps
Newsgroup: NNTP Reader
news://msnews.microsoft.com/microsoft.public.dotnet.distributed_apps
Do you want to learn and harness the power of .NET? Work side by side with technology experts at the Microsoft Technology Centers to learn development best practices. For more information, please visit http://www.microsoft.com/usa/mtc/.
More Information
The Exception Management Application Block has been designed and developed based on the best practices and general design principles discussed in the Exception Management in .NET Architecture Guide. Read this guide to learn more about exception management.
Collaborators
Many thanks to the following contributors and reviewers: Susan Warren, Brad Abrams, Andy Dunn, Michael Day, Krzysztof Cwalina, Steve Busby, Chris Brooks, Andrew Roubin (Vorsite Corp.), Jeffrey Richter (Wintellect), Bernard Chen (Sapient), and Matt Drucker (Turner Broadcasting).
Thanks, also, to the content team: Tina Burden (Entirenet), Shylender Ramamurthy (Infosys Technologies Ltd), and Filiberto Selvas Patino.