This documentation is archived and is not being maintained.

Trace Listeners

Visual Studio .NET 2003

When using Trace and Debug, you must have a mechanism for collecting and recording the messages that are sent. Trace messages are received by listeners. The purpose of a listener is to collect, store, and route tracing messages. Listeners direct the tracing output to an appropriate target, such as a log, window, or text file.

Listeners are available to both the Debug class and the Trace class, each of which can send its output to a variety of listener objects. There are three types of predefined listeners:

  • A TextWriterTraceListener redirects output to an instance of the TextWriter class or to anything that is a Stream class. It can also write to the console or to a file, because these are Stream classes. For more information on streams, see Stream Class.
  • An EventLogTraceListener redirects output to an event log.
  • A DefaultTraceListener emits Write and WriteLine messages to the OutputDebugString and to the Debugger.Log method. In Visual Studio, this causes the debugging messages to appear in the Output window. Fail and failed Assert messages also emit to the OutputDebugString Windows API and the Debugger.Log method, and also cause a message box to be displayed. This behavior is the default behavior for Debug and Trace messages, because DefaultTraceListener is automatically included in every Listeners collection and is the only listener automatically included.

If you want any listener besides the DefaultTraceListener to receive Debug and Trace output, you must add it to the Listeners collection. For more information, see Creating and Initializing Trace Listeners. Any listener in the Listeners collection gets the same messages from the trace output methods. For example, suppose you set up two listeners: a TextWriterTraceListener and an EventLogTraceListener. Each listener receives the same message. The TextWriterTraceListener would direct its output to a stream, and the EventLogTraceListener would direct its output to an event log.

The following example shows how to send output to the Listeners collection.

' Visual Basic
' Use this example when debugging.
Debug.WriteLine("Error in Widget 42")
' Use this example when tracing.
Trace.WriteLine("Error in Widget 42")

// C#
// Use this example when debugging.
System.Diagnostics.Debug.WriteLine("Error in Widget 42");
// Use this example when tracing.
System.Diagnostics.Trace.WriteLine("Error in Widget 42");

Debug and trace share the same Listeners collection, so if you add a listener object to a Debug.Listeners collection in your application, it gets added to the Trace.Listeners collection as well.

The following example shows how to use a listener to send tracing information to a console:

' Visual Basic
Trace.Listeners.Clear()
Trace.Listeners.Add(New TextWriterTraceListener(Console.Out))

// C#
System.Diagnostics.Trace.Listeners.Clear();
System.Diagnostics.Trace.Listeners.Add(
   new System.Diagnostics.TextWriterTraceListener(Console.Out));

Developer-Defined Listeners

You can define your own listeners by inheriting from the TraceListener base class and overriding its methods with your customized methods. For more information on creating developer-defined listeners, see TraceListener Class in the .NET Framework reference.

See Also

Introduction to Instrumentation and Tracing | Tracing and Instrumenting Applications in Visual Basic and Visual C# | Trace Switches | TextWriterTraceListener Class | EventLogTraceListener Class | DefaultTraceListener Class | TraceListener Class

Show: