The Exception Handling Handler

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.

The Exception Handling Handler provides the capability to manage and process exceptions in a standard way. This handler uses the Exception Handling Application Block, taking advantage of the wide range of options that it supports.

The Exception Handling Handler applies after invocation of the selected method or access to the selected property of the target object. If the method or property accessor raises an exception, the Exception Handling Handler will invoke a named exception handling policy defined within the Exception Handling Application Block. This policy may ignore the exception, return the original exception, or replace it with a new exception. The Exception Handling Handler then packages the exception (if the Exception Handling Application Block returns one) into the message passed back to the previous handler in the chain.

Note

Each instance of the Exception Handling Handler maintains its own hierarchy of exception policies and any dependent objects. When using the Logging Handler with the Exception Handling Application Block, each Exception Handling Handler instance will contain its own LogWriter instance and set of TraceListeners. If the Logging Application Block is configured to use a Flat File Trace Listener or a Rolling Flat File Trace Listener, you may see multiple log files with GUIDs in their file names because multiple instances of the trace listeners are not able to write to the configured log file at the same time.

Behavior of the Exception Handling Handler

In more detail, the Exception Handling Handler does the following:

• It reads the name of the exception policy to use, as configured in the Exception Handling Application Block, from the Policy Injection Application Block configuration.
• It does nothing if the target method or property accessor does not throw an exception.
• If the target method or property accessor throws an exception, it does the following:
  • It passes the exception to the Exception Handling Application Block for processing in accordance with the specified exception policy.
  • It wraps the exception returned by the Exception Handling Application Block in a message and returns it to the previous handler, which may act upon it.
• If the Exception Handling Application Block does not return an exception, it does the following:
  • If the target method does not return a result, it passes a null message back to the previous handler in the handler pipeline.
  • If the target method returns a result, it generates an InvalidOperationException, wraps it in a message, and returns it to the previous handler.

Configuration Settings of the Exception Handling Handler

The following configuration setting is available for the Exception Handling Handler:

• ExceptionPolicy (String). This is the name of the exception policy to use, as configured in the Exception Handling Application Block.
• Order (Integer). This value specifies the position of the handler within the policy handler chain. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain. To specify an explicit order, set the Order property for each handler starting from 1. If you specify the same value for the Order property of two handlers in the same policy, the application block will add them to the policy handler chain in the order defined in the configuration.

The next procedure describes how to configure the Exception Handling Handler using the Configuration Console or the Visual Studio Configuration Editor.

To configure the Exception Handling Handler

1. If you have not already added the Exception Handling Application Block to the configuration of your application, do this first. You must add at least one exception policy to the Exception Handling Application Block to use the Exception Handling Handler with the Policy Injection Application Block. For details about configuring exception-handling policies, see Entering Configuration Information in the documentation for the Exception Handling Application Block.
2. Right-click the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click Exception Handling Handler.
3. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Name property, and then change the default name to the name you want to use for the new handler.
4. Select the ExceptionPolicy property, and then select the exception handling policy you want to use from the list. The list shows the policies you previously configured for the Exception Handling Application Block.
5. (Optional) Enter a numeric value for the Order property if you want to specify the position of the handler within the policy handler chain. Set the Order property for each handler starting from 1.

Attribute-based Targeting with the Exception Handling Handler

The following code shows the use of the ExceptionCallHandler attribute on a simple method. This attribute can also be applied to the class declaration, in which case it applies to all members of that class. The policy name is a mandatory parameter.

[ExceptionCallHandler("exception-policy-name")]
public void Deposit(decimal depositAmount)
{
  balance += depositAmount;
}

'Usage
<ExceptionCallHandler("exception-policy-name")> _
Public Sub Deposit(Decimal depositAmount)
  balance += depositAmount
End Sub

The following table describes the properties of the ExceptionCallHandlerAttribute class.

Property	Description
PolicyName	String. The name of the exception handling policy to use, as configured in the Exception Handling Application Block.
Order	Integer. The position of the handler within the policy handler chain, starting from 1. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain.