Edit

Share via


How to: Create and Initialize Trace Listeners

Note

This article is specific to .NET Framework. It doesn't apply to newer implementations of .NET, including .NET 6 and later versions.

The System.Diagnostics.Debug and System.Diagnostics.Trace classes send messages to objects called listeners that receive and process these messages. One such listener, the System.Diagnostics.DefaultTraceListener, is automatically created and initialized when tracing or debugging is enabled. 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 application's needs. For example, if you want a text record of all trace output, create a TextWriterTraceListener listener, which writes all output to a new text file when it is enabled. On the other hand, if you want to view output only during application execution, create a ConsoleTraceListener listener, which directs all output to a console window. The EventLogTraceListener can direct trace output to an event log. For more information, see Trace Listeners.

You can create trace listeners in an application configuration file or in your code. We recommend the use of application configuration files, because they let you add, modify, or remove trace listeners without having to change your code.

To create and use a trace listener by 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 the text file TextWriterOutput.log.

    <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