Wrapping an Exception

  • Article
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.

A frequently required exception-handling task is wrapping one exception with a different exception. Wrapping an exception creates a new exception of a defined type and sets the original exception as the InnerException object of the new exception. Use the wrapping capability in situations where the original exception type must be mapped to a new exception type for use by other tiers within the architecture of the application. You can encapsulate and interpret details of the underlying layer's original exception without losing any details about that exception. You can wrap the original exception either in an existing exception type or in a custom exception type that you create. The following explains a situation when you would want to wrap an exception:

  1. A business service named Update Customer calls a data layer service.
  2. The data layer service fails and throws an exception. This could be any one of many exceptions that indicate that the update failed. Some sets of these exceptions indicate that recovery may be possible with a retry (for example, if a record is locked) while others are non-recoverable (for example, if there is a concurrency violation or a dirty record).
  3. The exception handler maps and wraps these sets of exceptions into two exception types, RecoverableUpdateException and FatalUpdateException.
  4. The business service handles the exception based on the wrapping type and takes the appropriate action, even though it is insulated from detailed knowledge of the underlying failure.

Typical Goals

You want to wrap one exception within another. Your application has code in its catch blocks similar to the following.

catch(SomeException e)
{
    CustomException myException = new CustomException(e);
    throw myException;
}

'Usage
Catch e As SomeException
  Dim myException As CustomException = New CustomException(e)
  Throw myException
End Try

Solution

Use the wrap handler in your exception handling chain.

QuickStart

For an extended example of how to use the Exception Handling Application Block to wrap an exception, see the QuickStart walkthrough, Walkthrough: Wrapping One Exception in Another.

Using the Wrap Handler

The following procedure describes how to use the wrap handler.

To use the wrap handler

  1. Create an exception handling policy that includes the appropriate exception types for your application. For more information, see Entering Configuration Information.

  2. Configure the exception type, specifying the PostHandlingAction as ThrowNewException. This means that the application block throws the new exception that has been created by wrapping the original exception. The throw occurs after the entire chain of handlers runs.

  3. Add a new wrap handler for the specified exception types.

  4. Configure the wrap handler. Add the exception message to be used and the exception type that will wrap the original exception.

  5. Modify your application code to execute the new policy when an exception occurs, as shown in the following code. Substitute the name of your own policy for "Wrap Policy."

    try
{
  // Run code.
}
catch(Exception ex)
{
  bool rethrow = ExceptionPolicy.HandleException(ex, "Wrap Policy");
  if (rethrow)
    throw;
}

    'Usage
Try
  ' Run code.
Catch ex As Exception
  Dim rethrow As Boolean = ExceptionPolicy.HandleException(ex, "Wrap Policy")
  If (rethrow) Then
    Throw
  End If
End Try

Usage Notes

Consider the following information when you configure the application block to use a wrap handler:

  • Typically, exceptions should be wrapped after they are logged in their original state.
  • To help in the management and tracking of exceptions, the application block generates a HandlingInstanceID object that you can use to map to the original exception. To use the HandlingInstanceID, you must include the {handlingInstanceID} token in the exception message that is in the configuration file. The HandlingInstanceID is of type GUID. For more information, see Assisting Support Staff.
  • If the post handling action is set to ThrowNewException, the exception thrown by the application block is the final exception that results from running the entire chain of handlers. For example, if the chain specifies that exception A is to be wrapped with exception B, and a later handler replaces exception B with exception C, the application block throws exception C when the post handling action is set to ThrowNewException.
  • If the post handling action is set to NotifyRethrow, the application block returns true to the calling code. This allows the code to throw the original exception.
  • Application code should always check the return value instead of assuming that it is the same value as the configured value. Even if the configuration data changes, if the application code checks the return value, the application code will function correctly and will not need to be modified.
  • The exception type used to wrap another exception must have a constructor that accepts two parameters: a string and an exception object. This means that you must provide this constructor overload for all custom exception types that are used to wrap other exceptions.
  • If you use the Unity Integration approach to create instances of objects from the Exception Handling Application Block, you must use the non-static façade named ExceptionManager instead of the ExceptionPolicy class static façade.