Edit

<add> Element for <sharedListeners>

  • Article

Adds a listener to the sharedListeners collection. sharedListeners is a collection of listeners that any <source> or <trace> 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> or <trace>. It is not possible to get the listeners in the sharedListeners collection in code at run time.

<configuration>
  <system.diagnostics>
    <sharedListeners>
      <add>

Syntax

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

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.
traceOutputOptions Optional attribute.

The string representation of one or more TraceOptions enumeration members that indicates the data to be written to the trace output. Multiple items are separated by commas. The default value is "None".

Child Elements

Element Description
<filter> 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 TextWriterTraceListenertextListener 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