跟踪侦听器Trace Listeners

使用 Trace、Debug 和 TraceSource 时,必须具有用于收集和记录发送的消息的机制。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.

侦听器可用于 Debug、Trace 和 TraceSource 类,其中每个类都可以将输出发送到多种侦听器对象。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:

  • TextWriterTraceListener 将输出重定向到 TextWriter 类的实例或为 Stream 类的任何项。A TextWriterTraceListener redirects output to an instance of the TextWriter class or to anything that is a Stream class. 它也可以写入到控制台或文件,因为它们是 Stream 类。It can also write to the console or to a file, because these are Stream classes.

  • EventLogTraceListener 将输出重定向到事件日志。An EventLogTraceListener redirects output to an event log.

  • DefaultTraceListener 向 OutputDebugString 和 Debugger.Log 方法发出 Write 和 WriteLine 消息。A DefaultTraceListener emits Write and WriteLine messages to the OutputDebugString and to the Debugger.Log method. 在 Visual Studio 中,这会导致“输出”窗口中显示调试消息。In Visual Studio, this causes the debugging messages to appear in the Output window. Fail 和失败的 Assert 消息也发到 OutputDebugString Windows API 和 Debugger.Log 方法,同样将显示消息框。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. 此行为是 Debug 和 Trace 消息的默认行为,因为 DefaultTraceListener 自动包含在每个 Listeners 集合中,且是自动包含的唯一侦听器。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.

  • ConsoleTraceListener 将跟踪或调试输出定向到标准输出或标准错误流。A ConsoleTraceListener directs tracing or debugging output to either the standard output or the standard error stream.

  • DelimitedListTraceListener 将跟踪或调试输出定向到文本编写器(如流编写器)或流(如文件流)。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. 跟踪输出采用由 Delimiter 属性指定的分隔符分隔的文本格式。The trace output is in a delimited text format that uses the delimiter specified by the Delimiter property.

  • XmlWriterTraceListener 将跟踪或调试输出以 XML 编码数据的形式定向到 TextWriterStream,例如 FileStreamAn XmlWriterTraceListener directs tracing or debugging output as XML-encoded data to a TextWriter or to a Stream, such as a FileStream.

如果你希望 DefaultTraceListener 以外的任何侦听器接收 Debug、Trace 和 TraceSource 输出,则必须将其添加到 Listeners 集合。If you want any listener besides the DefaultTraceListener to receive Debug, Trace and TraceSource output, you must add it to the Listeners collection. 有关详细信息,请参阅如何:创建和初始化跟踪侦听器以及如何:将 TraceSource 和筛选器与跟踪侦听器一起使用。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. 例如,假设你设置了两个侦听器:TextWriterTraceListener 和 EventLogTraceListener。For example, suppose you set up two listeners: a TextWriterTraceListener and an EventLogTraceListener. 每个侦听器接收相同消息。Each listener receives the same message. TextWriterTraceListener 将输出定向到流,而 EventLogTraceListener 将输出定向到事件日志。The TextWriterTraceListener would direct its output to a stream, and the EventLogTraceListener would direct its output to an event log.

以下示例演示如何将输出发送到 Listeners 集合。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");  

调试和跟踪共享一个 Listeners 集合,因此,如果你在应用程序中将侦听器对象添加到 Debug.Listeners 集合,则它也将被添加到 Trace.Listeners 集合。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

可以通过从 TraceListener 基类继承并用自定义方法重写其方法来定义侦听器。You can define your own listeners by inheriting from the TraceListener base class and overriding its methods with your customized methods. 有关创建开发人员定义的侦听器的详细信息,请参阅 .NET Framework 参考中的 TraceListenerFor more information on creating developer-defined listeners, see TraceListener in the .NET Framework reference.

请参阅See also