<add> Element for <sharedListeners>

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.

<configuration> Element
  <system.diagnostics> Element
    <sharedListeners> Element
      <add> Element for <listeners> for <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
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 that you specify initializeData.

Note

When you use the initializeData attribute, you may get the compiler warning "The 'initializeData' attribute is not declared." 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.

The 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 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.EventSchemaTraceListener	The name of the file that the EventSchemaTraceListener writes to.
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