C# Reference ยท Exceptions and Diagnostics
Debug and Trace
Reference for System.Diagnostics.Debug and Trace in C#: conditional compilation, WriteLine and WriteLineIf, trace listeners, indentation and Release-build behavior.
System.Diagnostics.Debug and System.Diagnostics.Trace are two static classes with almost identical members for writing diagnostic messages and checking assumptions. The difference is when the compiler keeps the calls. Debug methods exist only in builds that define the DEBUG symbol (normally the Debug configuration). Trace methods exist when TRACE is defined, which SDK-style projects define in both Debug and Release by default (the runner calls the compiler directly and defines neither).
Both send their text to a collection of listeners (Trace.Listeners, shared by the two classes). By default there is one listener that writes to an attached debugger's output window. You can add listeners that write to the console, a file or the event log.
Debug.WriteLine("only in Debug builds"); Trace.WriteLine("also in Release builds");
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
[Conditional("DEBUG")] static void Debug.WriteLine(string? message); [Conditional("DEBUG")] static void Debug.WriteLine(string? message, string? category); [Conditional("DEBUG")] static void Debug.WriteLineIf(bool condition, string? message); [Conditional("DEBUG")] static void Debug.Print(string format, params object?[] args); [Conditional("DEBUG")] static void Debug.Indent(); [Conditional("DEBUG")] static void Debug.Unindent(); [Conditional("TRACE")] static void Trace.WriteLine(string? message); [Conditional("TRACE")] static void Trace.TraceInformation(string message); [Conditional("TRACE")] static void Trace.TraceWarning(string message); [Conditional("TRACE")] static void Trace.TraceError(string message); static TraceListenerCollection Trace.Listeners { get; } static bool Trace.AutoFlush { get; set; } static int Trace.IndentSize { get; set; }
| Name | Description |
|---|---|
message |
The text to write. |
category |
Optional prefix; listeners usually print category: message. |
condition |
For the ...If variants: write only when true. |
Listeners |
Shared list of TraceListener objects (DefaultTraceListener, TextWriterTraceListener, ConsoleTraceListener, ...). |
AutoFlush |
Flush listeners after every write. Set it to true when debugging crashes. |
Returns: nothing. Errors: listeners can throw if their target is unavailable (for example a file that cannot be opened).
Usage notes
- Removed at compile time. A call to a method marked
[Conditional]is dropped by the compiler when the symbol is not defined, and its arguments are not evaluated. The first example showsevaluatedstaying0. - Defining symbols. Projects normally define
DEBUGandTRACEvia build configuration. Putting#define DEBUGat the very top of a single file enables it for that file only, which is how the second example works on the runner. - Listeners are shared.
DebugandTracewrite to the sameTrace.Listenerscollection, so adding a console listener makes both visible. - Default listener. It writes to an attached debugger or the platform debug stream. In a console app without a debugger you will see nothing until you add a listener.
- Not a logging framework. There are no levels, structured data or scopes. For production logging use
ILogger(see Logging).Tracestill exists for older libraries andTraceSourcebased tracing. - Do not put side effects in arguments. Because the call may disappear,
Debug.WriteLine(Next())runsNext()only in Debug builds. - Indent state is shared across threads that use the same listeners. Do not rely on it in multithreaded code.
- Performance. In builds where the symbol is defined, every call formats and writes text, so avoid tight loops. In builds where it is not, the cost is zero.
- Assertions.
Debug.AssertandTrace.Assertalso report through listeners; see Debug.Assert.