跟踪侦听器

注意

本文特定于 .NET Framework。 它不适用于 .NET 的较新版本实现,包括 .NET 6 及更高版本。

使用 Trace、Debug 和 TraceSource 时,必须具有用于收集和记录发送的消息的机制。 跟踪消息可由侦听器接收。 侦听器的用途是收集、存储和路由跟踪消息。 侦听器会将跟踪输出定向到适当的目标,如日志、窗口或文本文件。

侦听器可用于 Debug、Trace 和 TraceSource 类,其中每个类都可以将输出发送到多种侦听器对象。 以下是常用的预定义侦听器:

  • TextWriterTraceListener 将输出重定向到 TextWriter 类的实例或为 Stream 类的任何项。 它也可以写入到控制台或文件,因为它们是 Stream 类。

  • EventLogTraceListener 将输出重定向到事件日志。

  • DefaultTraceListener 向 OutputDebugString 和 Debugger.Log 方法发出 Write 和 WriteLine 消息。 在 Visual Studio 中,这会导致“输出”窗口中显示调试消息。 Fail 和失败的 Assert 消息也发到 OutputDebugString Windows API 和 Debugger.Log 方法,同样将显示消息框。 此行为是 Debug 和 Trace 消息的默认行为,因为 DefaultTraceListener 自动包含在每个 Listeners 集合中,且是自动包含的唯一侦听器。

  • ConsoleTraceListener 将跟踪或调试输出定向到标准输出或标准错误流。

  • DelimitedListTraceListener 将跟踪或调试输出定向到文本编写器(如流编写器)或流(如文件流)。 跟踪输出采用由 Delimiter 属性指定的分隔符分隔的文本格式。

  • XmlWriterTraceListener 将跟踪或调试输出以 XML 编码数据的形式定向到 TextWriterStream,例如 FileStream

如果你希望 DefaultTraceListener 以外的任何侦听器接收 Debug、Trace 和 TraceSource 输出,则必须将其添加到 Listeners 集合。 有关详细信息,请参阅如何:创建和初始化跟踪侦听器如何:将 TraceSource 和筛选器与跟踪侦听器一起使用。 侦听器集合中的任何侦听器均从跟踪输出方法获取相同消息。 例如,假设你设置了两个侦听器:TextWriterTraceListener 和 EventLogTraceListener。 每个侦听器接收相同消息。 TextWriterTraceListener 将输出定向到流,而 EventLogTraceListener 将输出定向到事件日志。

以下示例演示如何将输出发送到 Listeners 集合。

' 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 集合。

以下示例演示如何使用侦听器将跟踪信息发送到控制台:

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));

开发人员定义的侦听器

可以通过从 TraceListener 基类继承并用自定义方法重写其方法来定义侦听器。 有关创建开发人员定义的侦听器的详细信息,请参阅 .NET Framework 参考中的 TraceListener

请参阅