How to Report an Error

Capturing error details and exceptions is critical to the diagnosis of runtime errors. Without specific details, developers are left to guess and take shots in the dark about the potential problems leaving customers with a sour experience. It's surprising how many developers creating commercial grade software simply do not know how to capture exception details from an application. This article will cover some general techniques that apply to all software -- and some that apply to the tools available with DeployLX.

Take a Screen Shot

The first response when you see any sort of unexpected behavior, exception or error message is to take a screen shot. Don't crop or clean the shot. Send the whole screen. I know -- most of the screen is full of junk that is totally unrelated to the error. However, often bits of other information on the screen help give context and clues to the support engineer trying to diagnose the issue. If you can't send a shot of the whole desktop for security reasons then at least include the entire application window. I can remember in one situation seeing the icon of a virus scanner in the system task area that prompted additional research into compatibility with the tool that ended up solving the problem. It's never wrong to send too much information.

Bad Screen Shot

Good Screen Shot

Record the Activities Prior to the Exception

Write down what you were doing before the exception occurred. The more complete the better. Statements like "I clicked the save button" rarely provide enough context about what led up to the exception to offer any real details. If clicking the save button was the problem it would crash every time and that would have been caught in QC. Instead information like "I was editing a file that I had previously saved and changed the background color from black to blue, then clicked save" is much more helpful.

Reproduction Steps

Providing reproduction steps is often the quickest way to communicate with developers. If you can reproduce the error reliably -- then include detailed instructions on how to reproduce the exception. Assume that the developer doesn't have the software you have and isn't using the same versions of the products you are. Even better -- if you can provide a sample Visual Studio project that demonstrates the error that will almost always allow the support engineer to track down the problem faster.

This is the most neglected step in reporting an issue. Don't skip it. You want the problem resolved as quickly as possible. Give the support engineer everything you can to help them.

Use Any Built in Reporting Tools

If the software includes some sort of bug reporting tool use it! Developers know where likely problems lie and generally include details information about the system and conditions in the bug reports they build into their software. Don't take a screen shot of this. Yeah I know I said take a screen shot immediately but really the error reporting form is not usually the item of interest -- it's usually the window behind it that contains the context information needed to figure out the problem. Plus, most of these tools already include all the information on the form in their diagnostic report.

 

If the application error message does not include any sort of "submit" feature, make sure you try and get as much of the text out of the message box as possible. If there is a "details" button, click it. Some tools like the SQL Server Installer have buttons that let you copy, save, print or email the error. The content generated by those buttons will always be better than a screen shot of the message itself.

Attach a Debugger

Debuggers are incredible tools for solving software problems. If you are experiencing an error on a development machine you should always try to attach a debugger to capture additional information like the complete stack trace -- including method parameter values. Even if the application was launched outside a debugger, attaching is easy. If there is a genuine Exception thrown you'll see window something like the following. Attaching is as easy as selecting Debug the program.

JitWindow

You can attach to a running process directly from Visual Studio by selecting Tools | Attach To Process. For the purposes of error reporting, be sure to select attach to both the Managed and Unmanaged targets.

Get the Entire Exception Details

Once you've attached a debugger to the process you can now capture complete details about the exception. By default, Visual Studio will display the Managed Debug Assistant for unhandled Exceptions.

ExceptionManagedAssistant

For many reports, that's the end of it. But Visual Studio offers so much more!  And all the developer gets is the screen shot of the MDA. Simply using the Copy exception details to the clipboard link on the MDA gathers the entire stack trace and any Inner Exceptions that might have been the original culprit.

Some exceptions carry additional data in their properties. The ReflectionTypeLoadException comes to mind. It's LoaderExceptions property contains details about multiple exceptions that occurred when trying to load the type -- like an FileNotFoundException while trying to find the base type. Selecting the View Detail... option lets you explore these additional details and send screen shots of the details (cause VS doesn't have a copy to clipboard option from the details viewer at this time).

If you have control over code up the call chain from the exception, wrap it in a try...catch block even if only temporarily to gather additional details. Calling ToString() on the exception will generally provide the entire call chain and additional information.

try 
{
    throw new Exception( "Can you find me?" );   
}
catch( Exception ex )
{
    System.Diagnostics.Debug.WriteLine( ex.ToString() );
}
Published : Feb 23, 2009
Views : 16276

Subscribe Subscribe | Blog Home

Downloads

Tags

  • how-to