.NET Framework Class Library
Trace Class

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

Inheritance Hierarchy
SystemObject
  System.DiagnosticsTrace

Namespace:   System.Diagnostics
Assembly:  System (in System.dll)
Syntax
Public NotInheritable Class Trace
public sealed class Trace
public ref class Trace sealed
[<[%$TOPIC/36hhw2t6_en-us_VS_110_2_0_3_0_0%]>]
type Trace =  class end

The Trace type exposes the following members.

Properties
  NameDescription
Public property Static member Supported by the XNA Framework AutoFlushGets or sets whether Flush should be called on the Listeners after every write.
Public property Static member CorrelationManagerGets the correlation manager for the thread for this trace.
Public property Static member Supported by the XNA Framework IndentLevelGets or sets the indent level.
Public property Static member Supported by the XNA Framework IndentSizeGets or sets the number of spaces in an indent.
Public property Static member Supported by the XNA Framework ListenersGets the collection of listeners that is monitoring the trace output.
Public property Static member UseGlobalLockGets or sets a value indicating whether the global lock should be used.
Top
Methods
  NameDescription
Public method Static member Supported by the XNA Framework Assert(Boolean)Checks for a condition; if the condition is false, displays a message box that shows the call stack.
Public method Static member Supported by the XNA Framework Assert(Boolean, String)Checks for a condition; if the condition is false, outputs a specified message and displays a message box that shows the call stack.
Public method Static member Supported by the XNA Framework Assert(Boolean, String, String)Checks for a condition; if the condition is false, outputs two specified messages and displays a message box that shows the call stack.
Public method Static member Supported by the XNA Framework CloseFlushes the output buffer, and then closes the Listeners.
Public method Supported by the XNA Framework Equals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public method Static member Supported by the XNA Framework Fail(String)Emits the specified error message.
Public method Static member Supported by the XNA Framework Fail(String, String)Emits an error message, and a detailed error message.
Public method Static member Supported by the XNA Framework FlushFlushes the output buffer, and causes buffered data to be written to the Listeners.
Public method Supported by the XNA Framework GetHashCodeServes as the default hash function. (Inherited from Object.)
Public method Supported by the XNA Framework GetTypeGets the Type of the current instance. (Inherited from Object.)
Public method Static member IndentIncreases the current IndentLevel by one.
Public method Static member RefreshRefreshes the trace configuration data.
Public method Supported by the XNA Framework ToStringReturns a string that represents the current object. (Inherited from Object.)
Public method Static member TraceError(String)Writes an error message to the trace listeners in the Listeners collection using the specified message.
Public method Static member TraceError(String, Object)Writes an error message to the trace listeners in the Listeners collection using the specified array of objects and formatting information.
Public method Static member TraceInformation(String)Writes an informational message to the trace listeners in the Listeners collection using the specified message.
Public method Static member TraceInformation(String, Object)Writes an informational message to the trace listeners in the Listeners collection using the specified array of objects and formatting information.
Public method Static member TraceWarning(String)Writes a warning message to the trace listeners in the Listeners collection using the specified message.
Public method Static member TraceWarning(String, Object)Writes a warning message to the trace listeners in the Listeners collection using the specified array of objects and formatting information.
Public method Static member UnindentDecreases the current IndentLevel by one.
Public method Static member Supported by the XNA Framework Write(Object)Writes the value of the object's ToString method to the trace listeners in the Listeners collection.
Public method Static member Supported by the XNA Framework Write(String)Writes a message to the trace listeners in the Listeners collection.
Public method Static member Supported by the XNA Framework Write(Object, String)Writes a category name and the value of the object's ToString method to the trace listeners in the Listeners collection.
Public method Static member Supported by the XNA Framework Write(String, String)Writes a category name and a message to the trace listeners in the Listeners collection.
Public method Static member Supported by the XNA Framework WriteIf(Boolean, Object)Writes the value of the object's ToString method to the trace listeners in the Listeners collection if a condition is true.
Public method Static member Supported by the XNA Framework WriteIf(Boolean, String)Writes a message to the trace listeners in the Listeners collection if a condition is true.
Public method Static member Supported by the XNA Framework WriteIf(Boolean, Object, String)Writes a category name and the value of the object's ToString method to the trace listeners in the Listeners collection if a condition is true.
Public method Static member Supported by the XNA Framework WriteIf(Boolean, String, String)Writes a category name and message to the trace listeners in the Listeners collection if a condition is true.
Public method Static member Supported by the XNA Framework WriteLine(Object)Writes the value of the object's ToString method to the trace listeners in the Listeners collection.
Public method Static member Supported by the XNA Framework WriteLine(String)Writes a message to the trace listeners in the Listeners collection.
Public method Static member Supported by the XNA Framework WriteLine(Object, String)Writes a category name and the value of the object's ToString method to the trace listeners in the Listeners collection.
Public method Static member Supported by the XNA Framework WriteLine(String, String)Writes a category name and message to the trace listeners in the Listeners collection.
Public method Static member Supported by the XNA Framework WriteLineIf(Boolean, Object)Writes the value of the object's ToString method to the trace listeners in the Listeners collection if a condition is true.
Public method Static member Supported by the XNA Framework WriteLineIf(Boolean, String)Writes a message to the trace listeners in the Listeners collection if a condition is true.
Public method Static member Supported by the XNA Framework WriteLineIf(Boolean, Object, String)Writes a category name and the value of the object's ToString method to the trace listeners in the Listeners collection if a condition is true.
Public method Static member Supported by the XNA Framework WriteLineIf(Boolean, String, String)Writes a category name and message to the trace listeners in the Listeners collection if a condition is true.
Top
Remarks

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.

NoteNote

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.

NoteNote

If you add trace listeners to partially trusted code, you will get a SecurityException exception, because adding trace listeners requires UnmanagedCode permission. To trace partially trusted code that is running in a sandbox in Visual Studio, do not add trace listeners. Instead, view the Trace and Debug messages in the Output window.

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:

<configuration>
  <system.diagnostics>
    <trace autoflush="false" indentsize="3" />
  </system.diagnostics>
</configuration>

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.

NoteNote

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.

Examples

The following example uses Trace to indicate the beginning and the end of a program's execution. The example also uses the TraceIndent and TraceUnindent methods to distinguish the tracing output. For a more complete example of the use of Trace, see How to: Add Trace Statements to Application Code.

' Specify /d:TRACE=True when compiling. 

Imports System
Imports System.Diagnostics

Class Test

    Shared Sub Main()

        Trace.Listeners.Add(New TextWriterTraceListener(Console.Out))
        Trace.AutoFlush = True
        Trace.Indent()
        Trace.WriteLine("Entering Main")
        Console.WriteLine("Hello World.")
        Trace.WriteLine("Exiting Main")
        Trace.Unindent()

    End Sub 'Main

End Class
// Specify /d:TRACE when compiling. 

using System;
using System.Diagnostics;

class Test
{
    static void Main()
    {
       Trace.Listeners.Add(new TextWriterTraceListener(Console.Out));
       Trace.AutoFlush = true;
       Trace.Indent();
       Trace.WriteLine("Entering Main");
       Console.WriteLine("Hello World.");
       Trace.WriteLine("Exiting Main"); 
       Trace.Unindent();
    }
}
// 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::Indent();
   Trace::WriteLine( "Entering Main" );
   #endif
   Console::WriteLine( "Hello World." );
   #if defined(TRACE)
   Trace::WriteLine( "Exiting Main" );
   Trace::Unindent();
   #endif
   return 0;
}
Version Information

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1
.NET Framework Security
Platforms

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

Thread Safety

This type is thread safe.