How to: Create and Initialize Trace Listeners

The Debug and Trace classes send messages to objects called listeners, which receive and process these messages. One such listener, the DefaultTraceListener, is automatically created and initialized when tracing or debugging is enabled; For more information, see Trace Listeners. If you want Trace or Debug output to be directed to any additional sources, you must create and initialize additional trace listeners.

The listeners you create should reflect your individual needs. For example, you might want a text record of all trace output. In this case, you would create a listener that writes all output to a new text file when it is enabled. On the other hand, you might only want to view output during application execution. In that case, you might create a listener that directs all output to a console window. The EventLogTraceListener can direct trace output to an event log, and the TextWriterTraceListener can write trace output to a stream.

You can create trace listeners in an application configuration file or in your code. We recommend that you use an application configuration file. This enables you to add, modify, or remove the trace listeners without having to change your code.

To create and use a trace listener using a configuration file

1. Declare your trace listener in your application configuration file. If the listener you are creating requires any other objects, declare them as well. The following example shows how to create a listener called myListener that writes to a text file.

   <configuration>
     <system.diagnostics>
       <trace autoflush="false" indentsize="4">
         <listeners>
           <add name="myListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="TextWriterOutput.log" />
           <remove name="Default" />
         </listeners>
       </trace>
     </system.diagnostics>
   </configuration>
   

2. Use the Trace class in your code to write a message to the trace listeners.

   Trace.TraceInformation("Test message.")
   ' You must close or flush the trace to empty the output buffer.
   Trace.Flush()
   

   Trace.TraceInformation("Test message.");
   // You must close or flush the trace to empty the output buffer.
   Trace.Flush();
   

To create and use a trace listener in code

• Add the trace listener to the Listeners collection and send trace information to the listeners.

  Trace.Listeners.Add(New TextWriterTraceListener("TextWriterOutput.log", "myListener"))
  Trace.TraceInformation("Test message.")
  ' You must close or flush the trace to empty the output buffer.
  Trace.Flush()
  

  Trace.Listeners.Add(new TextWriterTraceListener("TextWriterOutput.log", "myListener"));
  Trace.TraceInformation("Test message.");
  // You must close or flush the trace to empty the output buffer.
  Trace.Flush();
  

  - or -

• If you do not want your listener to receive trace output, do not add it to the Listeners collection. You can emit output through a listener independent of the Listeners collection by calling the listener's own output methods. The following example shows how to write a line to a listener that is not in the Listeners collection.

  Dim myListener As New TextWriterTraceListener("TextWriterOutput.log", "myListener")
  myListener.WriteLine("Test message.")
  ' You must close or flush the trace listener to empty the output buffer.
  myListener.Flush()
  

  TextWriterTraceListener myListener = new TextWriterTraceListener("TextWriterOutput.log", "myListener");
  myListener.WriteLine("Test message.");
  // You must close or flush the trace listener to empty the output buffer.
  myListener.Flush();
  

See Also

Tasks

How to: Trace Code in an Application

How to: Add Trace Statements to Application Code

Concepts

Trace Listeners

Trace Switches

Other Resources

Tracing and Instrumenting Applications

Change History