Share via


<add> Element for <listeners> for <trace>

Adds a listener to the Listeners collection.

<configuration> Element
  <system.diagnostics> Element
    <trace> Element
      <listeners> Element for <trace>
        <add> Element for <listeners> for <trace>

<add name="name" 
     type="trace listener class name, 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.

name

Optional attribute.

Specifies the name of the listener.

traceOutputOptions

Optional attribute.

Specifies the TraceOutputOptions property value for the trace listener.

Child Elements

Element

Description

<filter> Element for <add> for <listeners> for <trace>

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

Parent Elements

Element

Description

configuration

The root element in every configuration file used by the common language runtime and .NET Framework applications.

listeners

Specifies a listener that collects, stores, and routes messages. Listeners direct the tracing output to an appropriate target.

system.diagnostics

Specifies the root element for the ASP.NET configuration section.

trace

Contains listeners that collect, store, and route tracing messages.

Remarks

The Debug and Trace classes share the same Listeners collection. If you add a listener object to the collection in one of these classes, the other class uses the same listener. The listener classes derive from the TraceListener class.

If you do not specify the name attribute of the trace listener, the Name 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 remove it by specifying an empty string for the name. However, if your application has more than one listener, you should specify unique names for each trace listener, which allows you to identify and manage individual trace listeners within the Listeners and Listeners collections.

Note

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

System.Diagnostics.ConsoleTraceListener

The useErrorStream value for the ConsoleTraceListener constructor. Set the initializeData attribute to "true" to write trace and debug output to Console.Error; "false" to write to Console.Out.

System.Diagnostics.DelimitedListTraceListener

The name of the file the DelimitedListTraceListener writes to.

System.Diagnostics.EventLogTraceListener

The name of 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.

System.Diagnostics.XmlWriterTraceListener

The name of the file that the XmlWriterTraceListener writes to.

Example

The following example shows how to use <add> elements to add the listeners MyListener and MyEventListener to the Listeners collection. MyListener creates a file called MyListener.log and writes the output to the file. MyEventListener creates an entry in the event log.

<configuration>
   <system.diagnostics>
      <trace autoflush="true" indentsize="0">
         <listeners>
            <add name="myListener" type="System.Diagnostics.TextWriterTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="c:\myListener.log" />
            <add name="MyEventListener"
                 type="System.Diagnostics.EventLogTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"                 initializeData="MyConfigEventLog"/>
            <add name="configConsoleListener"
                 type="System.Diagnostics.ConsoleTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
         </listeners>
      </trace>
   </system.diagnostics>
</configuration>

See Also

Concepts

Trace Listeners

Reference

Trace and Debug Settings Schema

Trace

Debug

EventLogTraceListener

ConsoleTraceListener

TextWriterTraceListener

Change History

Date

History

Reason

December 2008

Added traceOutputOptions to Attributes section.

Customer feedback.