Muokkaa

Jaa

Trace Listeners

  • Artikkeli

Note

This article is specific to .NET Framework. It doesn't apply to newer implementations of .NET, including .NET 6 and later versions.

When using Trace, Debug and TraceSource, 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 the Debug, Trace, and TraceSource classes, each of which can send its output to a variety of listener objects. The following are the commonly used 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.

  • 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.

  • A ConsoleTraceListener directs tracing or debugging output to either the standard output or the standard error stream.

  • A DelimitedListTraceListener directs tracing or debugging output to a text writer, such as a stream writer, or to a stream, such as a file stream. The trace output is in a delimited text format that uses the delimiter specified by the Delimiter property.

  • An XmlWriterTraceListener directs tracing or debugging output as XML-encoded data to a TextWriter or to a Stream, such as a FileStream.

If you want any listener besides the DefaultTraceListener to receive Debug, Trace and TraceSource output, you must add it to the Listeners collection. For more information, see How to: Create and Initialize Trace Listeners and How to: Use TraceSource and Filters with 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.

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

// 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:

Trace.Listeners.Clear()
Trace.Listeners.Add(New TextWriterTraceListener(Console.Out))

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 in the .NET Framework reference.

See also