<source> 的 <listeners> 的 <add> 元素

项目
08/12/2011

将侦听器添加到跟踪源的 Listeners 集合。

<add name="name" 
  type="TraceListenerClassName, Version, Culture, PublicKeyToken"
  initializeData="data"/>

特性和元素

以下几节描述了属性、子元素和父元素。

特性

特性	说明
type	必选特性。指定侦听器的类型。必须使用满足指定完全限定的类型名称中指定的要求的字符串。
initializeData	可选特性。传递到指定类的构造函数的字符串。如果该类没有接受字符串的构造函数，则会引发 ConfigurationException。
name	可选特性。指定侦听器的名称。
traceOutputOptions	可选特性。指定跟踪源的 TraceOutputOptions 属性值。
[自定义特性]	可选特性。指定由该侦听器的 GetSupportedAttributes 方法所标识的特定于侦听器的特性的值。 Delimiter 是 DelimitedListTraceListener 类所特有的额外特性的示例。

子元素

元素	说明
<source> 的 <listeners> 的 <add> 的 <filter> 元素	向跟踪源的 Listeners 集合中的侦听器添加筛选器。

父元素

元素	说明
configuration	公共语言运行时和 .NET Framework 应用程序所使用的每个配置文件中的根元素。
system.diagnostics	指定对消息进行收集、存储和路由的跟踪侦听器以及设置跟踪开关的级别。
sources	包含启动跟踪消息的跟踪源。
source	指定启动跟踪消息的跟踪源。
listeners	指定对消息进行收集、存储和路由的侦听器。

备注

随 .NET Framework 一起提供的侦听器类从 TraceListener 类派生。

如果不指定跟踪侦听器的 name 特性，则跟踪侦听器的 Name 属性会默认为空字符串 ("")。如果应用程序只有一个侦听器，则可以在不指定名称的情况下添加它，还可以通过指定空字符串作为名称来移除它。但是，如果应用程序有多个侦听器，则应该为每个跟踪侦听器指定唯一名称，这样，便可以在 TraceSource.Listeners 集合中标识和管理各个跟踪侦听器。

注意
添加多个相同类型和相同名称的跟踪侦听器将导致仅有一个该类型和名称的侦听器被添加到 Listeners 集合中。但是可以通过编程方式向 Listeners 集合添加多个完全相同的侦听器。

initializeData 特性的值取决于您创建的侦听器的类型。并非所有跟踪侦听器都要求您指定 initializeData。

注意
当您使用 initializeData 特性时，可能会收到编译器警告“未声明‘initializeData’特性”。出现此警告是因为，在根据抽象基类 TraceListener 验证配置设置时，该基类不能识别 initializeData 特性。通常，如果跟踪侦听器实现具有带参数的构造函数，则可以忽略此警告。

下表说明 .NET Framework 中包含的跟踪侦听器，同时描述了这些侦听器的 initializeData 特性值。

跟踪侦听器类	initializeData 特性值
System.Diagnostics.ConsoleTraceListener	ConsoleTraceListener 构造函数的 useErrorStream 值。将 initializeData 特性设置为“true”可将跟踪和调试输出写入标准错误流；将它设置为“false”可写入标准输出流。
System.Diagnostics.DelimitedListTraceListener	DelimitedListTraceListener 写入的文件的名称。
System.Diagnostics.EventLogTraceListener	现有事件日志源的名称。
System.Diagnostics.EventSchemaTraceListener	EventSchemaTraceListener 写入的文件的名称。
System.Diagnostics.TextWriterTraceListener	TextWriterTraceListener 写入的文件的名称。
System.Diagnostics.XmlWriterTraceListener	XmlWriterTraceListener 写入的文件的名称。

配置文件

此元素可用于计算机配置文件 (Machine.config) 和应用程序配置文件。

示例

下面的示例演示如何使用 <add> 元素将侦听器 console 和 textListener 添加到跟踪源 TraceSourceApp 的 Listeners 集合中。 textListener 侦听器将跟踪输出写入文件 myListener.log。

<configuration>
  <system.diagnostics>
    <sources>
      <source name="TraceSourceApp" switchName="sourceSwitch" 
        switchType="System.Diagnostics.SourceSwitch">
        <listeners>
          <add name="console" 
            type="System.Diagnostics.ConsoleTraceListener"/>
          <add name="textListener"/>
          <remove name="Default"/>
        </listeners>
      </source>
    </sources>
    <sharedListeners>
      <add name="textListener" 
        type="System.Diagnostics.TextWriterTraceListener" 
        initializeData="myListener.log"/>
    </sharedListeners>
    <switches>
      <add name="sourceSwitch" value="Warning"/>
    </switches>
  </system.diagnostics>
</configuration>