<add> Element for <sharedListeners>

Article
09/15/2021

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>

Share via