This documentation is archived and is not being maintained.

Adding Trace Statements to Application Code

Visual Studio .NET 2003

The methods used most often for tracing are the methods for writing output to listeners: Write, WriteIf, WriteLine, WriteLineIf, Assert, and Fail. These methods can be divided into two categories: Write, WriteLine, and Fail all emit output unconditionally, whereas WriteIf, WriteLineIf, and Assert test a Boolean condition, and write or do not write based on the value of the condition. WriteIf and WriteLineIf emit output of the condition is true, and Assert emits output if the condition is false.

When designing your tracing and debugging strategy, you should think about how you want the output to look. Multiple Write statements filled with unrelated information will create a log that is difficult to read. On the other hand, using WriteLine to put related statements on separate lines may make it difficult to distinguish what information belongs together. In general, use multiple Write statements when you want to combine information from multiple sources to create a single informative message, and the WriteLine statement when you want to create a single, complete message.

To write a complete line

  • Call the WriteLine or WriteLineIf method.

    A carriage return is appended to the end of the message this method returns, so that the next message returned by Write, WriteIf, WriteLine, or WriteLineIf will begin on the following line:

    ' Visual Basic
    Dim errorFlag As Boolean = False
    Trace.WriteLine("Error in AppendData procedure.")
    Trace.WriteLineIf(errorFlag, "Error in AppendData procedure.") 
    // C#
    bool errorFlag = false;
    System.Diagnostics.Trace.WriteLine ("Error in AppendData procedure.");
       "Error in AppendData procedure.");

To write a partial line

  • Call the Write or WriteIf method.

    The next message put out by a Write, WriteIf, WriteLine, or WriteLineIf will begin on the same line as the message put out by the Write or WriteIf statement:

    ' Visual Basic
    Dim errorFlag As Boolean = False
    Trace.WriteIf(errorFlag, "Error in AppendData procedure.")
    Debug.WriteIf(errorFlag, "Transaction abandoned.")
    Trace.Write("Invalid value for data request")
    // C#
    bool errorFlag = false;
       "Error in AppendData procedure.");
    System.Diagnostics.Debug.WriteIf(errorFlag, "Transaction abandoned.");
    Trace.Write("Invalid value for data request");

To verify that certain conditions exist either before or after you execute a method

  • Call the Assert method.
    ' Visual Basic
    Dim I As Integer = 4
    Trace.Assert(I = 5, "I is not equal to 5.")
    // C#
    int I = 4;
    System.Diagnostics.Trace.Assert(I == 5, "I is not equal to 5.");
    Note   You can use Assert with both tracing and debugging. This example outputs the call stack to any listener in the Listeners collection. For more information, see Assertions in Managed Code and Debug.Assert Method.

Controlling Conditional Writes with Switches

You might want to make a decision about writing trace output based on the status of switches. A BooleanSwitch is a simple on-off switch, and a TraceSwitch is a switch with multiple level settings. For more information, see Trace Switches.

You can use the WriteIf and WriteLineIf methods to test a particular switch and write a message if appropriate. To use BooleanSwitch to write tracing information, use its Enabled field in an If statement or a WriteIf statement. For some examples, see BooleanSwitch.Enabled Property in the .NET Framework reference. To use TraceSwitch to write tracing information, use TraceSwitch's Level property. For examples, see TraceSwitch.Level Property in the .NET Framework reference.

The following example uses the Enabled property of a BooleanSwitch called dataSwitch to determine whether or not to write a line.

' Visual Basic
Trace.WriteLineIf(dataSwitch.Enabled, "Starting connection procedure")

// C#
   "Starting connection procedure");

A TraceSwitch provides multiple setting levels, and exposes a set of properties that correspond to these levels. Thus, the Boolean properties TraceError, TraceWarning, TraceInfo, and TraceVerbose can be tested as part of a WriteIf or WriteLineIf statement. The code in this example writes the specified information only if your TraceSwitch is set to trace level Error or higher:

' Visual Basic
Trace.WriteLineIf(myTraceSwitch.TraceError, "Error 42 occurred")

// C#
   "Error 42 occurred");
Note   When you test a TraceSwitch, the level is considered to be true if it is equal to or higher than the level you test for.

The preceding example always calls the WriteLineIf method when tracing is enabled. Therefore, the example must always execute any code necessary to evaluate the second argument for WriteLineIf. However, you will usually get better performance by testing a BooleanSwitch first and then calling the general Trace.Write method only if the test succeeds, using this code:

' Visual Basic
If MyBooleanSwitch.Enabled Then
   Trace.WriteLine("Error 42 occured")
End If

// C#
if (MyBooleanSwitch.Enabled)
   System.Diagnostics.Trace.WriteLine("Error 42 occured");

If you test the Boolean value before calling the tracing method, you avoid executing unnecessary code, because tracing always evaluates all parameters of WriteLineIf. Note that this technique would improve performance only if TraceSwitch is off during the application's normal operating mode. If TraceSwitch is on, the application must evaluate all parameters of WriteLineIf, adding time to the overall execution of the application.

See Also

Introduction to Instrumentation and Tracing | Tracing and Instrumenting Applications in Visual Basic and Visual C# | Configuring Trace Switches | Trace Switches | Trace Listeners | Debug.WriteIf Method | Debug.WriteLineIf Method| Trace.WriteIf Method | Trace.WriteLineIf Method