Assisting Support Staff

When you use the Exception Handling Application Block, a frequently required task is to allow support staff to access detailed information to assist users when exceptions occur. When an exception occurs that cannot be handled, users are generally shown a friendly error message. Users may have to call support staff, and support staff may need more than the user error message to determine what went wrong and how to fix the problem. This scenario demonstrates how to match the user's error message with the detailed exception log that can be accessed by support staff.

Typical Goals

You want support staff to be able to match a user-friendly error message with the detailed information contained in the original exception that is in the exception log.

Solution

To help with the management and tracking of exceptions, the application block generates a HandlingInstanceID for every exception handled. You can use the HandlingInstanceID to map the error message to the specific exception that has occurred. The HandlingInstanceID is unique for each handled exception and its related handling chain inside the Exception Handling Application Block.

The HandlingInstanceID is passed to every handler of the specified exception handling chain. Therefore, after you capture the original exception information and its associated HandlingInstanceID, you will be able to track that particular exception throughout your handling actions. For example, you might log the original exception with the HandlingInstanceID and later display the HandlingInstanceID in a message to the user. That same HandlingInstanceID, logged with the original exception as the first step in the chain, lets you track the original exception that caused the user and support notifications.

QuickStart

For an extended example of how to use the HandlingInstanceID to allow support staff to access detailed information, see the QuickStart walkthrough, Walkthrough: Notifying the User.

Assisting Support Staff

The following procedure describes how to assist support staff by providing information about exceptions.

To assist support staff

1. Use the configuration tools to create an exception handling policy with the relevant exception types for your application. For more information, see Entering Configuration Information.
2. Configure the exception type. Specify the appropriate PostHandlingAction. Specifying None indicates that the application block will not take any further action after the exception handler chain runs. This is appropriate when the message containing the handlingInstanceID will be displayed by an exception handler in the same exception handler chain. Specifying ThrowNewException causes the application block to throw the new exception containing the message with the handlingInstanceID after the entire chain of handlers runs. This is appropriate when the message containing the handlingInstanceID will be displayed by a UI component that is not a part of the current exception handler chain.
3. Add a logging handler to capture the initial exception information.
4. Add a new replace handler for the specified exception types.
5. Configure the replace handler, including the token {handlingInstanceID} within the body of the message. When the replace handler runs, the token will be replaced with the correlation identifier generated by the application block.
6. Add a custom exception handler that will display the exception message to the user. For information about how to create a custom handler for displaying exception messages, see Notifying the User.
7. Modify your application code to execute the new policy when an exception occurs.

The following code shows how to pass an exception that can be replaced to the Exception Handling Application Block. The code checks the true or false value returned from the HandleException method, indicating whether the configuration specifies that the original exception will be thrown again.

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 send a notification to a user and include information intended for the support staff:

• Display the handlingInstanceID in a form or text box so that a user can easily copy it to the clipboard.
• Prompt the user to enter the actions that he or she performed when the exception occurred. Log this information to a location where the support staff can retrieve it and correlate it with the original exception.