This documentation is archived and is not being maintained.

Trace Class

Updated: August 2008

Provides a set of methods and properties that help you trace the execution of your code. This class cannot be inherited.

Namespace:  System.Diagnostics
Assembly:  System (in System.dll)

public ref class Trace sealed

You can use the properties and methods in the Trace class to instrument release builds. Instrumentation allows you to monitor the health of your application running in real-life settings. Tracing helps you isolate problems and fix them without disturbing a running system.

This class provides methods to display an Assert dialog box, and to emit an assertion that will always Fail. This class provides write methods in the following variations: Write, WriteLine, WriteIf, and WriteLineIf.

The BooleanSwitch and TraceSwitch classes provide means to dynamically control the tracing output. You can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch, see the Switch class and the How to: Configure Trace Switches topic.

You can customize the tracing output's target by adding TraceListener instances to or removing instances from the Listeners collection. The Listeners collection is shared by both the Debug and the Trace classes; adding a trace listener to either class adds the listener to both. By default, trace output is emitted using the DefaultTraceListener class.


Adding a trace listener to the Listeners collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the Trace methods in try/catch blocks to detect and handle any exceptions from trace listeners.

The Trace class provides properties to get or set the level of Indent, the IndentSize, and whether to AutoFlush after each write.

To set the AutoFlush and IndentSize for Trace, you can edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example:

    <trace autoflush="false" indentsize="3" />

The ConditionalAttribute attribute is applied to the methods of Trace. Compilers that support ConditionalAttribute ignore calls to these methods unless "TRACE" is defined as a conditional compilation symbol. Refer to a compiler's documentation to determine whether ConditionalAttribute is supported and the syntax for defining a conditional compilation symbol.


In Visual Studio projects, by default, the "DEBUG" conditional compilation symbol is defined for debug builds, and the "TRACE" symbol is defined for both debug and release builds. For information about how to disable this behavior, see the Visual Studio documentation.

To define the "TRACE" conditional compilation symbol in C#, add the /d:TRACE option to the compiler command line when you compile your code using a command line, or add #define TRACE to the top of your file. In Visual Basic, add the /d:TRACE=True option to the compiler command line or add #Const TRACE=True to the file.

ConditionalAttribute is not supported by the C++ compiler. To provide equivalent functionality, you must enclose calls to the methods of Trace in an #if defined(TRACE) ... #endif block, and add the /DTRACE option to the compiler command line or add #define TRACE to the file.

Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows CE Platform Note: The .NET Compact Framework does not support tracing features that use a configuration file.

The following example uses Trace to indicate the beginning and the end of a program's execution. The example also uses Indent and Unindent to distinguish the tracing output.

// Specify /DTRACE when compiling.

#using <System.dll>
using namespace System;
using namespace System::Diagnostics;

int main()
   #if defined(TRACE)
   Trace::Listeners->Add( gcnew TextWriterTraceListener( Console::Out ) );
   Trace::AutoFlush = true;
   Trace::WriteLine( "Entering Main" );
   Console::WriteLine( "Hello World." );
   #if defined(TRACE)
   Trace::WriteLine( "Exiting Main" );
   return 0;


This type is thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0




August 2008

Added note about exceptions thrown by listeners.

Customer feedback.

September 2008

Added information about the Listeners collection being shared with Debug.

Customer feedback.