.NET 2.0+

Writing Debug and Trace Messages

Complex software can be made easier to debug and monitor with the use of logging code. Such code outputs information about an application to the screen or to a location that can be examined during debugging or when the software is in a live environment.

What are Debug and Trace Messages?

If you are developing complex software, it is useful to add logging capabilities. The logs generated can be viewed to determine the operation of the software that is difficult to understand through the user interface alone. When debugging, these logged messages can be very useful to help in identifying problems. To assist you in creating logs and monitoring the operation and performance of your software, the .NET framework includes facilities for outputting debug and trace messages.

Debug messages are created using the Debug class in the System.Diagnostics namespace. By default, when using the debugger within Visual Studio, these messages are displayed in the Output window if running software in debug mode. However, listeners can be added that write messages to other locations, such as text files. The methods used to generate the messages are decorated with the Condition attribute and the DEBUG symbol, so are not called when the program is compiled in release mode. This ensures that debug messages are not seen by the end-user and do not cause any performance impact.

Trace messages are written using the Trace class in the same namespace. They are different to Debug messages because they are included in the code when the TRACE symbol is defined, as it is by default for Visual Studio users. Trace messages can exist in code that has been compiled in either debug or release mode. They are useful when you do wish to log information from the software that you distribute to end-users.

Writing Messages

The simplest use of debug messages is to display information in the Output window when running a program in the debugger. As the classes used to do this are found in the System.Diagnostics namespace, you should add the following using directive to the code:

You can now use the static Write and WriteLine methods of the Debug or Trace class to output information. The Write method can be used with a single parameter of any type. When a string is used, its contents are written to the Output window. With other types, the result of calling the object's ToString method is displayed. The following commands demonstrate the method's use for both the Debug and Trace classes.

Debug.Write("Application started (Debug)");
Trace.Write("Application stopped (Trace)");

The Write method outputs the string with no trailing carriage return or line feed. This allows several writes to be used to generate a single line of text. If you prefer to start a new line after writing a message, use the WriteLine method instead. As with Write, this method is available in both the Debug and Trace classes. For clarity, the remaining examples will show only the Debug variety.

Categories

You can categorise your messages by adding a second parameter to either the Write or WriteLine methods. This parameter should be a string containing any category name. When using the default listener, the category name is shown in the Output window before the message. For other listeners, the output may vary.

Debug.Write("Application started", "Debug");
Debug.WriteLine("Application stopped", "Debug");

Indentation

To improve the readability of log files you can add indentation. It is often useful to match the indentation of the debug or trace messages to the indentation of your code, or to indent at the start of a method and remove the indentation before returning. Indentation can easily be included with the Indent and Unindent methods.

Debug.WriteLine("Application started", "Application");
Debug.Indent();
Debug.WriteLine("Processing input XML", "File Import");
Debug.WriteLine("Imported 300 row(s)", "File Import");
Debug.Unindent();
Debug.WriteLine("Application stopped", "Application");