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

将侦听器添加到跟踪源的 Listeners 集合中。Adds a listener to the Listeners collection for a trace source.

<configuration>
  <system.diagnostics>
    <sources>
      <source>
        <listeners>
          <add>

语法Syntax

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

特性和元素Attributes and Elements

下列各节描述了特性、子元素和父元素。The following sections describe attributes, child elements, and parent elements.

特性Attributes

属性Attribute 描述Description
type 必需的属性,除非引用集合中的侦听器 sharedListeners ,在这种情况下,你只需按名称引用它 (请参阅 示例) 。Required attribute, unless you're referencing a listener in the sharedListeners collection, in which case you only need to refer to it by name (see the Example).

指定侦听器的类型。Specifies the type of the listener. 必须使用满足指定 完全限定的类型名称中指定的要求的字符串。You must use a string that meets the requirements specified in Specifying Fully Qualified Type Names.
initializeData 可选特性。Optional attribute.

传递到指定类的构造函数的字符串。The string passed to the constructor for the specified class. ConfigurationException如果类不具有采用字符串的构造函数,则会引发。A ConfigurationException is thrown if the class does not have a constructor that takes a string.
name 可选特性。Optional attribute.

指定侦听器的名称。Specifies the name of the listener.
traceOutputOptions 可选特性。Optional attribute.

指定 TraceOutputOptions 跟踪侦听器的属性值。Specifies the TraceOutputOptions property value for the trace listener.
[自定义属性][custom attributes] 可选属性。Optional attributes.

为该侦听器的方法所标识的侦听器特定的特性指定值 GetSupportedAttributesSpecifies the value for listener-specific attributes identified by the GetSupportedAttributes method for that listener. Delimiter 是类独有的额外特性的一个示例 DelimitedListTraceListenerDelimiter is an example of an extra attribute unique to the DelimitedListTraceListener class.

子元素Child Elements

元素Element 描述Description
<filter> 将筛选器添加到跟踪源的 Listeners 集合中的侦听器。Adds a filter to a listener in the Listeners collection for a trace source.

父元素Parent Elements

元素Element 描述Description
configuration 公共语言运行时和 .NET Framework 应用程序所使用的每个配置文件中的根元素。The root element in every configuration file used by the common language runtime and .NET Framework applications.
system.diagnostics 指定用于收集、存储和路由消息的跟踪侦听器以及对跟踪开关设置的级别。Specifies trace listeners that collect, store, and route messages and the level where a trace switch is set.
sources 包含用于启动跟踪消息的跟踪源。Contains trace sources that initiate tracing messages.
source 指定用于启动跟踪消息的跟踪源。Specifies a trace source that initiates tracing messages.
listeners 指定用于收集、存储和路由消息的侦听器。Specifies listeners that collect, store, and route messages.

备注Remarks

随 .NET Framework 附带的侦听器类派生自 TraceListener 类。The listener classes shipped with the .NET Framework derive from the TraceListener class.

如果未指定 name 跟踪侦听器的属性,则 Name 跟踪侦听器的属性默认为空字符串 ( "" ) 。If you do not specify the name attribute of the trace listener, the Name property of the trace listener defaults to an empty string (""). 如果你的应用程序只有一个侦听器,则可以在不指定名称的情况下添加它,并且可以通过为名称指定空字符串来删除它。If your application has only one listener, you can add it without specifying a name, and you can remove it by specifying an empty string for the name. 但是,如果你的应用程序有多个侦听器,则应为每个跟踪侦听器指定唯一的名称,以便你可以在集合中标识和管理单个跟踪侦听器 TraceSource.ListenersHowever, if your application has more than one listener, you should specify a unique name for each trace listener, which allows you to identify and manage individual trace listeners in the TraceSource.Listeners collection.

备注

添加具有相同类型且具有相同名称的多个跟踪侦听器会导致只将该类型和名称的一个跟踪侦听器添加到 Listeners 集合中。Adding more than one trace listener of the same type and with the same name results in only one trace listener of that type and name being added to the Listeners collection. 但是,可以通过编程方式将多个相同的侦听器添加到 Listeners 集合中。However, you can programmatically add multiple identical listeners to the Listeners collection.

该属性的值 initializeData 取决于所创建的侦听器的类型。The value for the initializeData attribute depends on the type of listener you create. 并非所有跟踪侦听器都要求您指定 initializeDataNot all trace listeners require that you specify initializeData.

备注

使用 initializeData 属性时,可能会收到编译器警告 "未声明 ' initializeData ' 特性"。When you use the initializeData attribute, you may get the compiler warning "The 'initializeData' attribute is not declared." 之所以出现此警告,是因为配置设置是针对抽象基类验证的 TraceListener ,后者不识别 initializeData 属性。This warning occurs because the configuration settings are validated against the abstract base class TraceListener, which does not recognize the initializeData attribute. 通常,对于具有采用参数的构造函数的跟踪侦听器实现,你可以忽略此警告。Typically, you can ignore this warning for trace listener implementations that have a constructor that takes a parameter.

下表显示了 .NET Framework 附带的跟踪侦听器,并描述了其属性的值 initializeDataThe following table shows the trace listeners that are included with the .NET Framework and describes the value of their initializeData attributes.

跟踪侦听器类Trace listener class initializeData 特性值initializeData attribute value
System.Diagnostics.ConsoleTraceListener useErrorStream构造函数的值 ConsoleTraceListenerThe useErrorStream value for the ConsoleTraceListener constructor. initializeData 属性设置为 " true " 可将跟踪和调试输出写入标准错误流; 将该属性设置为 " false " 可写入标准输出流。Set the initializeData attribute to "true" to write trace and debug output to the standard error stream; set it to "false" to write to the standard output stream.
System.Diagnostics.DelimitedListTraceListener DelimitedListTraceListener 写入的文件名。The name of the file the DelimitedListTraceListener writes to.
System.Diagnostics.EventLogTraceListener 现有的事件日志源的名称。The name of an existing event log source.
System.Diagnostics.EventSchemaTraceListener 写入的文件的名称 EventSchemaTraceListenerThe name of the file that the EventSchemaTraceListener writes to.
System.Diagnostics.TextWriterTraceListener 写入的文件的名称 TextWriterTraceListenerThe name of the file that the TextWriterTraceListener writes to.
System.Diagnostics.XmlWriterTraceListener 写入的文件的名称 XmlWriterTraceListenerThe name of the file that the XmlWriterTraceListener writes to.

配置文件Configuration File

此元素可在计算机配置文件中使用 ( # A0) 和应用程序配置文件。This element can be used in the machine configuration file (Machine.config) and the application configuration file.

示例Example

下面的示例演示如何使用 <add> 元素将侦听器 consoletextListener 集合添加到 Listeners 跟踪源的集合中 TraceSourceAppThe following example shows how to use <add> elements to add the listeners console and textListener to the Listeners collection for the trace source TraceSourceApp. textListener侦听器将跟踪输出写入文件 myListener。The textListener listener writes trace output to the file 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>

请参阅See also