Partager via

<add> Element for <listeners> for <source>

  • Article

Adds a listener to the Listeners collection for a trace source.

<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

Required attribute.

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

Specifies the TraceOutputOptions property value for the trace listener.

[custom attributes]

Optional attributes.

Specifies the value for listener-specific attributes identified by the GetSupportedAttributes method for that listener. Delimiter is an example of an extra attribute unique to the DelimitedListTraceListener class.

Child Elements

Element Description

<filter> Element for <add> for <listeners> for <source>

Adds a filter to a listener in the Listeners collection for a trace source.

Parent Elements

Element Description

configuration

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

The listener classes shipped with the .NET Framework derive from the TraceListener class.

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. However, 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 System.Diagnostics.TraceSource.Listeners collection.

NoteNote

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. However you can programmatically add multiple identical listeners to the Listeners collection.

The value for the initializeData attribute depends on the type of listener you create. Not all trace listeners require you to specify initializeData. The following table shows the trace listeners that ship with the .NET Framework and describes the value of their initializeData attributes.

Trace listener class initializeData attribute value

System.Diagnostics.ConsoleTraceListener

The useErrorStream value for the ConsoleTraceListener constructor. 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

The name of the file the DelimitedListTraceListener writes to.

System.Diagnostics.EventLogTraceListener

The name of an existing event log source.

System.Diagnostics.TextWriterTraceListener

The name of the file that the TextWriterTraceListener writes to.

System.Diagnostics.XmlWriterTraceListener

The name of the file that the XmlWriterTraceListener writes to.

Configuration File

This element can be used in the machine configuration file (Machine.config) and the application configuration file.

Example

The following example shows how to use <add> elements to add the listeners console and textListener to the Listeners collection for the trace source TraceSourceApp. 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

Reference

Trace and Debug Settings Schema
TraceSource
TraceListener

Concepts

Trace Listeners