Error Cross-Reference Generator

Intent

Generate a unique ID to display to the user and store with any logged exception, which allows the user to report a specific ID to support personnel for tracking purposes.

Problem

Bad things happen to good sites. Eventually your Web site will experience an exception. The challenge is providing the users the information they need to help support personnel with the information to diagnose a problem and, ultimately, either correct the problem for the user or provide the developers with enough information to reproduce the problem.

Unfortunately, it is difficult to determine the right amount of information to provide to the user. Any technical information provided can be either overwhelming to the end user or even used against your site in a potential security exploit. If you provide too little information, either the tech support person cannot diagnose or the developer cannot track the error.

This pattern allows you to generate a unique ID for each exception that occurs. This ID should be included with every log of the exception information, as well as for the display of the exception message back to the user. In this way, the user can provide the ID to support personnel. The support personnel can use the ID to review any exception logs. If necessary, the support person can pass the information along to the developer for further investigation.

Forces

Use the Error Cross-Reference Generator when:

• You have one or more logs of error information to organize.

• Your application might have exceptions you want to identify categorically

Structure

The main class of the Error Cross-Reference Generator (Figure 3.8) provides one method, NextID, that does all of the work of the pattern. It is assumed that each ID generated will be "unique enough" in the context of the application. In other words, it will generate an ID that provides a unique ID without creating an extremely long value for a user to read back. The application must be sure to use the same ID in its response to the user as it does when logging errors.

Figure 3.8. Error Cross-Reference Generator structure.

Consequences

The Error Cross-Reference Generator has the following benefits and liabilities:

1. Provides a simple mechanism for correlating user errors to error logs . By generating a unique ID that can be displayed to the user and stored in the logs, any errors stored in the logs can be tied back to the individual user.

2. Requires an algorithm for generating the ID . The algorithm needs to balance the need for uniqueness and ability for the user to read back the ID. An ID that is too long will make it easy for the ID to be read back incorrectly, making it next to impossible to track it back to the event logs.

Participants

• Application ”self-explanatory

• Error Cross-Reference Generator ” self-explanatory

Implementation

Our sample shows the Error Cross-Reference Generator pattern as used by WebForm Template pattern described below. In this example (Figure 3.9), the Generator is used by the base class for all Web forms in the site to ensure that all exceptions provide a consistent display that includes the Error ID.

Figure 3.9. Error Cross-Reference Generator implementation example.

When an exception is thrown and renders the page or when one of the derived classes calls the SetError method, the TemplateBase class retrieves an ID from the Generator and stores it to make sure that only one ID will be used for all errors on the same page to be displayed to the user.

Listing 3.11 Calling the Error Cross-Reference Generator.

 // We only want to retrieve this once. if (mErrorXRef.Length == 0)    mErrorXRef = ErrorXRefGenerator.NextID(); return mErrorXRef; 

The method we use to generate the ID in our sample is to combine a time-based value with a random number. The time value we use is the total number of seconds since the beginning of the month. Obviously, this value will repeat each month, but the application itself will display the actual date and time with the error message. The second part, the random number, is just in case we have more than one exception during a second. These are formatted as hexadecimal strings to shorten the value to be read back.

Related Patterns

• WebForm Template (Eshelman)

• Template Method (GoF)