<add> Element for <sharedListeners>

  • Article

Adds a listener to the sharedListeners collection. sharedListeners is a collection of listeners that any <source> Element or <trace> Element can reference. By default, listeners in the sharedListeners collection are not placed in a Listeners collection. They must be added by name to the <source> Element or <trace> Element. It is not possible to get the listeners in the sharedListeners collection in code at run time.

<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

name

Required attribute.

Specifies the name of the listener that is used to add the shared listener to a Listeners collection.

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.

Child Elements

Element Description

<filter> Element for <add> for <sharedListeners>

Adds a filter to a listener in the sharedListeners collection.

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.

sharedListeners

A collection of listeners that any source or trace element can reference.

Remarks

The listener classes shipped with the .NET Framework derive from the TraceListener class. The value for the name attribute is used to add the shared listener to a Listeners collection for either a trace or a trace source. 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

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.

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.

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 TextWriterTraceListener textListener to the sharedListeners collection. textListener is added by name 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