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

  • 项目

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

<配置>
  <system.diagnostics>
    <sources>
      <source>
        <listeners>
          <add>

语法

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

特性和元素

下列各节描述了特性、子元素和父元素。

特性

属性 说明
type 必需属性，除非引用 sharedListeners 集合中的侦听器，在这种情况下，你只需按名称引用它（请参阅示例）。

指定侦听器的类型。 必须使用一个满足指定完全限定的类型名称中指定的要求的字符串。
initializeData 可选特性。

传递给指定类的构造函数的字符串。 如果类没有采用字符串的构造函数，则会引发 ConfigurationException。
name 可选特性。

指定侦听器的名称。
traceOutputOptions 可选特性。

指定跟踪侦听器的 TraceOutputOptions 属性值。
[自定义属性] 可选属性。

为该侦听器的 GetSupportedAttributes 方法所标识的侦听器特定的属性指定值。 Delimiter 是 DelimitedListTraceListener 类特有的额外属性示例。

子元素

元素 说明
<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。

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

请参阅