Replacing an Exception

A frequently required exception-handling task is to replace the original exception with another exception. For example, if an exception is going to cross a trust boundary, you may not want to send the original exception because it contains sensitive information.

Typical Goals

You want to replace the original exception, which contains sensitive or unnecessary information, with another that is more appropriate. Your application has code in its catch blocks similar to the following.

catch(SomeException e)
{
    CustomException myException = new CustomException("Unable to access the configured data source");
    throw myException;
}

'Usage
Catch e As SomeException
  Dim myException As CustomException = New CustomException("Unable to access the configured data source")
  Throw myException
End Try

Solution

Use the replace handler in your exception handling chain. Execute the policy before propagating the exception out of the application layer.

QuickStart

For an extended example of how to use the Exception Handling Application Block to replace an exception, see the QuickStart walkthrough, Walkthrough: Replacing One Exception with Another.

Using the Replace Handler

The following procedure describes how to use the replace handler.

To use the replace handler

1. Create an exception handling policy with 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 causes the application block to throw the new exception that has been created by replacing the original exception. The throw occurs after the entire chain of handlers runs.

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

4. Configure the replace handler. Add the exception message to be used and the exception type that will be used to replace the originating exception.

5. Modify your application code to execute the new policy when an exception occurs. The following code shows how to do this. Replace the name "Replace Policy" with the name of your own replacement policy.

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

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

Usage Notes

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

• Typically, exceptions are replaced after they are logged in their original state.
• To help in the management and tracking of exceptions, the application block generates a HandlingInstanceID that you can use to map to the originating 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.
• The exception that the application block throws is the final exception that results after the entire chain of handlers runs. For example, if the chain specifies that exception A is to be replaced with exception B, and a later handler replaces exception B with exception C, exception C will be thrown.
• Application code should always check the return value and not assume that it is the same value as the configured value. This means that, even if the configuration data changes, the application code will function correctly and will not need to be modified.
• The constructor for the replace handler accepts only one argument of type string. This means that you must provide this constructor overload for all custom exception types that are used to replace 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.