Type: System.Diagnostics.Trace

System.Diagnostics.Trace Class

Assembly: System.dll
Namespace: System.Diagnostics

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

C# Syntax:


        public sealed class Trace

Thread Safety

This type is safe for multithreaded operations.

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.

Note To enable debugging in C#, add the /d:TRACE flag to the compiler command line when you compile your code, or you can add #define TRACE to the top of your file. In Visual Basic, add the /d:TRACE=True flag to the compiler command line. To provide equivalent funtionality in the Managed Extensions for C++, you must enclose calls to methods of this class in a #ifdef TRACE ... #endif block. This syntax is compiler-specific. If you are using a compiler other than the ones specified above, you must refer to the compiler's documentation to enable conditional compiling because of the conditional compilation attributes placed on the methods of the Trace class.

In Visual Studio .NET projects, Trace is enabled by default. Therefore, code is generated for all Trace methods in both release and debug builds. This allows an end user to turn on tracing to help identify the problem without the program having to be recompiled. By contrast, Debug is disabled in release builds by default, so no executable code is generated for Debug methods. To disable Trace, see the Visual Studio .NET documentation.

This class provides methods to display an Trace.Assert dialog box, and to emit an assertion that will always Trace.Fail. This class provides write methods in the following variations: Trace.Write, Trace.WriteLine, Trace.WriteIf, and Trace.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 TraceSwitch Configuration topic in the Visual Studio .NET documentation.

You can customize the tracing output's target by adding TraceListener instances to or removing instances from the Trace.Listeners collection. By default, trace output is emitted using the DefaultTraceListener class.

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

To set the Trace.AutoFlush and Trace.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>

Example

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

public int Main(string[] args)
{
   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();
   return 0;
}

System.Diagnostics.Trace Member List:

Public Properties

AutoFlush	Read-write Gets or sets whether Trace.Flush should be called on the Trace.Listeners after every write.
IndentLevel	Read-write Gets or sets the indent level.
IndentSize	Read-write Gets or sets the number of spaces in an indent.
Listeners	Read-only Gets the collection of listeners that is monitoring the trace output.

Public Methods

Assert	Overloaded: `Assert(bool condition)` Checks for a condition, and outputs the call stack if the condition is false.
Assert	Overloaded: `Assert(bool condition, string message)` Checks for a condition, and displays a message if the condition is false.
Assert	Overloaded: `Assert(bool condition, string message, string detailMessage)` Checks for a condition, and displays both messages if the condition is false.
Close	Flushes the output buffer, and then closes the Trace.Listeners.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
Fail	Overloaded: `Fail(string message)` Emits the specified error message.
Fail	Overloaded: `Fail(string message, string detailMessage)` Emits an error message, and a detailed error message.
Flush	Flushes the output buffer, and causes buffered data to be written to the Trace.Listeners.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Indent	Increases the current Trace.IndentLevel by one.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.
Unindent	Decreases the current Trace.IndentLevel by one.
Write	Overloaded: `Write(object value)` Writes the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection.
Write	Overloaded: `Write(string message)` Writes a message to the trace listeners in the Trace.Listeners collection.
Write	Overloaded: `Write(object value, string category)` Writes a category name and the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection.
Write	Overloaded: `Write(string message, string category)` Writes a category name and a message to the trace listeners in the Trace.Listeners collection.
WriteIf	Overloaded: `WriteIf(bool condition, object value)` Writes the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection if a condition is true.
WriteIf	Overloaded: `WriteIf(bool condition, string message)` Writes a message to the trace listeners in the Trace.Listeners collection if a condition is true.
WriteIf	Overloaded: `WriteIf(bool condition, object value, string category)` Writes a category name and the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection if a condition is true.
WriteIf	Overloaded: `WriteIf(bool condition, string message, string category)` Writes a category name and message to the trace listeners in the Trace.Listeners collection if a condition is true.
WriteLine	Overloaded: `WriteLine(object value)` Writes the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection.
WriteLine	Overloaded: `WriteLine(string message)` Writes a message to the trace listeners in the Trace.Listeners collection.
WriteLine	Overloaded: `WriteLine(object value, string category)` Writes a category name and the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection.
WriteLine	Overloaded: `WriteLine(string message, string category)` Writes a category name and message to the trace listeners in the Trace.Listeners collection.
WriteLineIf	Overloaded: `WriteLineIf(bool condition, object value)` Writes the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection if a condition is true.
WriteLineIf	Overloaded: `WriteLineIf(bool condition, string message)` Writes a message to the trace listeners in the Trace.Listeners collection if a condition is true.
WriteLineIf	Overloaded: `WriteLineIf(bool condition, object value, string category)` Writes a category name and the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection if a condition is true.
WriteLineIf	Overloaded: `WriteLineIf(bool condition, string message, string category)` Writes a category name and message to the trace listeners in the Trace.Listeners collection if a condition is true.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

System.Object

System.Diagnostics.Trace

System.Diagnostics.Trace Member Details

Property: AutoFlush (read-write)

Summary: Gets or sets whether Trace.Flush should be called on the Trace.Listeners after every write.

C# Syntax:


            public static bool AutoFlush {get; set;}

Remarks

The default is false.

Flushing the stream will not flush its underlying encoder unless you explicitly call Trace.Flush or Trace.Close. Setting Trace.AutoFlush to true means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters.

To set the Trace.AutoFlush and Trace.IndentSize for Trace, you can also 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>

Return to top

Property: IndentLevel (read-write)

Summary: Gets or sets the indent level.

C# Syntax:


            public static int IndentLevel {get; set;}

Remarks

This property is stored on per-thread/per-request basis.

Example

The following example increments and decrements the indent level and emits tracing messages.

Trace.WriteLine("List of errors:");
 Trace.Indent();
 Trace.WriteLine("Error 1: File not found");
 Trace.WriteLine("Error 2: Directory not found");
 Trace.Unindent();
 Trace.WriteLine("End of list of errors");

This example produces the following output:


List of errors:
     Error 1: File not found
     Error 2: Directory not found
End of list of errors

Return to top

Property: IndentSize (read-write)

Summary: Gets or sets the number of spaces in an indent.

C# Syntax:


            public static int IndentSize {get; set;}

Remarks

A TextWriterTraceListener interprets this number as spaces. An EventLogTraceListener ignores this value.

This property is stored on per-thread/per-request basis.

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

Return to top

Property: Listeners (read-only)

Summary: Gets the collection of listeners that is monitoring the trace output.

C# Syntax:


            public static TraceListenerCollection Listeners {get;}

Remarks

The listeners produce formatted output from the trace output. By default, the collection contains an instance of the DefaultTraceListener class. If you want to remove the default listener, call the TraceListenerCollection.Remove method, and pass it the instance of the DefaultTraceListener. To redirect output to the console window, add an instance of the TextWriterTraceListener that uses the Console.Out stream.

Example

The following example creates a TextWriterTraceListener that outputs to the console screen. The code then adds the new listener to the Trace.Listeners.

/* Create a listener, which outputs to the console screen, and 
  * add it to the trace listeners. */
 TextWriterTraceListener myWriter = new 
    TextWriterTraceListener(System.Console.Out);
 Trace.Listeners.Add(myWriter);

Return to top

Overloaded Method: Assert(
bool condition
)

Summary: Checks for a condition, and outputs the call stack if the condition is false.

C# Syntax:

[Conditional("")]
public static void Assert(
   bool condition
);

Parameters:

condition

true to prevent a message being displayed; otherwise, false.true to prevent a message being displayed; otherwise, false.

Remarks

Trace.Assert outputs the call stack with file and line number for each line in the call stack.

Typically, you use Trace.Assert to identify logic errors during program development. Trace.Assert will evaluate the condition. If the result is false, it sends diagnostic messages to the Trace.Listeners.

The default behavior displays a message box when the application runs in user-interface mode, and to output the message to the default trace output. You can customize this behavior by adding a TraceListener to, or removing one from, the Trace.Listeners collection.

To set an assert, you can also edit the configuration file that corresponds to the name of your application. Within this file, you can enable and disable the assert or set the name of its log file. The configuration file should be formatted like the following example:

              <configuration>
                 <system.diagnostics>
                    <switches>
                       <add name="mySwitch" value="4"/>
                    </switches>
                    <trace autoflush="false" indentsize="4"/>
                    <assert assertuienabled="true" logfilename=".\TraceLog.txt"/>
                 </system.diagnostics>
              </configuration>

Example

The following example creates an index for an array. Then some action is performed that sets the value of the index. Next the code calls Trace.Assert to verify the index value is valid. If it is not valid, the Trace.Assert outputs the call stack.

// Create an index for an array.
 protected int index;
 
 protected void Method()
 { 
 // Perform some action that sets the index.
 
 // Test that the index value is valid. 
 Trace.Assert(index > -1);
 }

Return to top

Overloaded Method: Assert(
bool condition,
string message
)

Summary: Checks for a condition, and displays a message if the condition is false.

C# Syntax:

[Conditional("")]
public static void Assert(
   bool condition,
   string message
);

Parameters:

condition

true to prevent a message being displayed; otherwise, false.true to prevent a message being displayed; otherwise, false.

message

A message to display. A message to display.

Remarks

Typically, you use Trace.Assert to identify logic errors during program development. Trace.Assert will evaluate the condition parameter. If the result is false, it sends diagnostic messages to the Trace.Listeners. The default behavior displays a message box when the application runs in user-interface mode, and to output the message to the default trace output. You can customize this behavior by adding a TraceListener to, or removing one from, the Trace.Listeners collection.

              <configuration>
                 <system.diagnostics>
                    <switches>
                       <add name="mySwitch" value="4"/>
                    </switches>
                    <trace autoflush="false" indentsize="4"/>
                    <assert assertuienabled="true" logfilename=".\TraceLog.txt"/>
                 </system.diagnostics>
              </configuration>

Example

The following example checks to see that the


                type

parameter is valid. If the


                type

passed in is null, the Trace.Assert outputs a message.

public static void MyMethod(Type type, Type baseType) {
    Trace.Assert(type != null, "Type parameter is null");
 
   // Perform some processing.
 }

Return to top

Overloaded Method: Assert(
   bool condition,
   string message,
   string detailMessage
)

Summary: Checks for a condition, and displays both messages if the condition is false.

C# Syntax:

[Conditional("")]
public static void Assert(
   bool condition,
   string message,
   string detailMessage
);

Parameters:

condition

true to prevent a message being displayed; otherwise, false.true to prevent a message being displayed; otherwise, false.

message

A message to display. A message to display.

detailMessage

A detailed message to display.

Remarks

Typically, you use Trace.Assert to identify logic errors during program development. Trace.Assert will evaluate the condition. If the result is false, it sends diagnostic messages to the Trace.Listeners.

The default behavior is to display a message box when the application runs in user-interface mode, and to output the message to the default trace output. You can customize this behavior by adding a TraceListener to, or removing one from, the Trace.Listeners collection.

              <configuration>
                 <system.diagnostics>
                    <switches>
                       <add name="mySwitch" value="4"/>
                    </switches>
                    <trace autoflush="false" indentsize="4"/>
                    <assert assertuienabled="true" logfilename=".\TraceLog.txt"/>
                 </system.diagnostics>
              </configuration>

Example

The following example checks to see that the


                type

parameter is valid. If the


                type

passed in is null, the Trace.Assert outputs a message.

public static void MyMethod(Type type, Type baseType) {
    Trace.Assert(type != null, "Type parameter is null", 
       "Can't get object for null type");
 
   // Perform some processing.
 }

Return to top

Method: Close()

Summary: Flushes the output buffer, and then closes the Trace.Listeners.

C# Syntax:

[Conditional("")]
public static void Close();

Remarks

Use this method when the output is going to a file, such as to the TextWriterTraceListener.

Example

The following example creates a TextWriterTraceListener named


                myTextListener


                myTextListener

uses a StreamWriter called


                myOutputWriter

to write to a file named


                TestFile.txt

. The example creates the file, stream and text writer, writes one line of text to the file, and then flushes and closes the output.

public static void Main(string[] args) {
    // Create a file for output named TestFile.txt.
    String myFileName = "TestFile.txt";
    if(!File.Exists(myFileName))
    {
       Stream myFile = File.Create(myFileName);
 
    // Assign output file to output stream.
    StreamWriter myOutputWriter;
    myOutputWriter = File.AppendText(myFileName);
 
    /* Create a new text writer using the output stream, and 
     * add it to the trace listeners. */
    TextWriterTraceListener myTextListener = new 
       TextWriterTraceListener(myOutputWriter);
    Trace.Listeners.Add(myTextListener);
 
    // Write output to the file.
    Trace.WriteLine("Test output");
 
    // Flush and close the output stream.
    Trace.Flush();
    Trace.Close();
   }
 }

Return to top

Method: Equals(
object obj
)

Inherited
See base class member description: System.Object.Equals

C# Syntax:


            public virtual bool Equals(
   object obj
);

For more information on members inherited from System.Object click on the link above.

Return to top

Overloaded Method: Fail(
string message
)

Summary: Emits the specified error message.

C# Syntax:

[Conditional("")]
public static void Fail(
   string message
);

Parameters:

message

A message to emit.

Remarks

The default behavior for the default trace listener is to output the message parameter to a message box when the application runs in user-interface mode, and to the TraceListener instances in the Trace.Listeners collection. You can customize this behavior by adding a TraceListener to, or by removing one from, the Trace.Listeners collection.

Example

The following example uses the Trace.Fail method to print a message during exception handling.

        catch (Exception) {
            Trace.Fail("Cannot find SpecialController, proceeding with StandardController");
        }

You can also use the Trace.Fail method in a switch statement.

        switch (option) {
            case Option.First:
               result = 1.0;
               break;
         
            // Insert additional cases.
            default:
               Trace.Fail("Unknown Option " + option);
               result = 1.0;
               break;
        }

Return to top

Overloaded Method: Fail(
string message,
string detailMessage
)

Summary: Emits an error message, and a detailed error message.

C# Syntax:

[Conditional("")]
public static void Fail(
   string message,
   string detailMessage
);

Parameters:

message

A message to emit.

detailMessage

A detailed message to emit.

Remarks

The default behavior is for the default trace listener to output the message parameter and the detailedMessage parameter to a message box when the application runs in user-interface mode, and to the TraceListener instances in the Trace.Listeners collection. You can customize this behavior by adding a TraceListener to, or by removing one from, the Trace.Listeners collection.

Example

The following example uses the Trace.Fail method to print a message during exception handling.

        catch (Exception) {
            Trace.Fail("Invalid value: " + value.ToString(), 
               "Resetting value to newValue.");
            value = newValue;
        }

You can also use the Trace.Fail method in a switch statement.

        switch (option) {
            case Option.First:
               result = 1.0;
               break;
         
            // Insert additional cases.
         
            default:
               Trace.Fail("Unknown Option " + option, "Result set to 1.0");
               result = 1.0;
               break;
        }

Return to top

Method: Finalize()

Inherited
See base class member description: System.Object.Finalize

C# Syntax:


            ~Trace();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: Flush()

Summary: Flushes the output buffer, and causes buffered data to be written to the Trace.Listeners.

C# Syntax:

[Conditional("")]
public static void Flush();

Remarks

Example

The following example creates a TextWriterTraceListener named


                myTextListener


                myTextListener

uses a StreamWriter called


                myOutputWriter

to write to a file named


                TestFile.txt

. The example creates the file, stream and text writer, writes one line of text to the file, and then flushes and closes the output.

public static void Main(string[] args) {
    // Create a file for output named TestFile.txt.
    String myFileName = "TestFile.txt";
    if(!File.Exists(myFileName))
    {
       Stream myFile = File.Create(myFileName);
 
    // Assign output file to output stream.
    StreamWriter myOutputWriter;
    myOutputWriter = File.AppendText(myFileName);
 
    /* Create a new text writer using the output stream, and 
     * add it to the trace listeners. */
    TextWriterTraceListener myTextListener = new 
       TextWriterTraceListener(myOutputWriter);
    Trace.Listeners.Add(myTextListener);
 
    // Write output to the file.
    Trace.WriteLine("Test output");
 
    // Flush and close the output stream.
    Trace.Flush();
    Trace.Close();
   }
 }

Return to top

Method: GetHashCode()

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:


            public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: GetType()

Inherited
See base class member description: System.Object.GetType

C# Syntax:


            public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: Indent()

Summary: Increases the current Trace.IndentLevel by one.

C# Syntax:

[Conditional("")]
public static void Indent();

Example

The following example increments and decrements the indent level and emits tracing messages.

Trace.WriteLine("List of errors:");
 Trace.Indent();
 Trace.WriteLine("Error 1: File not found");
 Trace.WriteLine("Error 2: Directory not found");
 Trace.Unindent();
 Trace.WriteLine("End of list of errors");

This example produces the following output:


List of errors:
     Error 1: File not found
     Error 2: Directory not found
End of list of errors

See also:
Trace.Unindent | Trace.IndentLevel | Trace.IndentSize

Return to top

Method: MemberwiseClone()

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:


            protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: ToString()

Inherited
See base class member description: System.Object.ToString

C# Syntax:


            public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: Unindent()

Summary: Decreases the current Trace.IndentLevel by one.

C# Syntax:

[Conditional("")]
public static void Unindent();

Example

The following example increments and decrements the indent level and emits tracing messages.

Trace.WriteLine("List of errors:");
 Trace.Indent();
 Trace.WriteLine("Error 1: File not found");
 Trace.WriteLine("Error 2: Directory not found");
 Trace.Unindent();
 Trace.WriteLine("End of list of errors");

This example produces the following output:


List of errors:
     Error 1: File not found
     Error 2: Directory not found
End of list of errors

See also:
Trace.Indent | Trace.IndentLevel | Trace.IndentSize

Return to top

Overloaded Method: Write(
object value
)

Summary: Writes the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection.

C# Syntax:

[Conditional("")]
public static void Write(
   object value
);

Parameters:

value

An Object whose name is sent to the Trace.Listeners.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

This method calls the TraceListener.Write method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

If the switch is set to the TraceLevelError or higher, the example outputs the first name of the value parameter to the Trace.Listeners. For information on adding a listener to the Trace.Listeners collection, see the TraceListenerCollection class.

Then, if the TraceLevel is set to Verbose, the example outputs a message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Trace.Write(myObject);
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Trace.WriteLine(" is not a valid value for this method.");
 }

Return to top

Overloaded Method: Write(
string message
)

Summary: Writes a message to the trace listeners in the Trace.Listeners collection.

C# Syntax:

[Conditional("")]
public static void Write(
   string message
);

Parameters:

message

A message to write. A message to write.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

This method calls the TraceListener.Write method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

If the switch is set to the TraceLevelError or higher, the example outputs the first error message to the Trace.Listeners. For information on adding a listener to the Trace.Listeners collection, see the TraceListenerCollection class.

Then, if the TraceLevel is set to Verbose, the example outputs the second error message on the same line as the first message. A line terminator follows the second message.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Trace.Write("My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Trace.WriteLine("My second error message.");
 }

Return to top

Overloaded Method: Write(
object value,
string category
)

Summary: Writes a category name and the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection.

C# Syntax:

[Conditional("")]
public static void Write(
   object value,
   string category
);

Parameters:

value

An Object name is sent to the Trace.Listeners. An Object name is sent to the Trace.Listeners.

category

A category name used to organize the output.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

The category parameter can be used to group output messages.

This method calls the TraceListener.Write method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

If the switch is set to the TraceLevelVerbose, the example outputs the name of the myObject and the category to the Trace.Listeners. For information on adding a listener to the Trace.Listeners collection, see the TraceListenerCollection class.

Then, if the TraceLevel is set to Error or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Trace.Write(myObject, category);
 
    // Write a second message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Trace.WriteLine(" Object is not valid for this category.");
 }

Return to top

Overloaded Method: Write(
string message,
string category
)

Summary: Writes a category name and a message to the trace listeners in the Trace.Listeners collection.

C# Syntax:

[Conditional("")]
public static void Write(
   string message,
   string category
);

Parameters:

message

A message to write.

category

A category name used to organize the output.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

The category parameter can be used to group output messages.

This method calls the TraceListener.Write method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

If the switch is set to the TraceLevelVerbose, the example outputs the first error message to the Trace.Listeners. For information on adding a listener to the Trace.Listeners collection, see the TraceListenerCollection class.

Then, if the TraceLevel is set to Error or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Trace.Write(myObject.ToString() + " is not a valid object for category: ", 
          category);
 
    // Write a second message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Trace.WriteLine(" Please use a different category.");
 }

Return to top

Overloaded Method: WriteIf(
bool condition,
object value
)

Summary: Writes the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection if a condition is true.

C# Syntax:

[Conditional("")]
public static void WriteIf(
   bool condition,
   object value
);

Parameters:

condition

true to cause a message to be written; otherwise, false.true to cause a message to be written; otherwise, false.

value

An Object whose name is sent to the Trace.Listeners.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

This method calls the TraceListener.Write method of the trace listener.

Notes to implementors: You can minimize the performance penalty of instrumenting your application by using If...Then statements instead of using Trace.WriteIf statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if


                mySwitch.TraceError

evaluates to false you do not call Trace.Write. The second example always calls Trace.WriteIf, even when


                mySwitch.TraceError

is false and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code.

First example.

              if(mySwitch.TraceError) 
                  Trace.Write("aNumber = " + aNumber + " out of range");

Second example.

              Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range");

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

If the switch is set to the TraceLevelError or higher, the example outputs the first name of the value parameter to the Trace.Listeners. For information on adding a listener to the Trace.Listeners collection, see the TraceListenerCollection class.

Then, if the TraceLevel is set to Verbose, the example outputs a message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Trace.WriteIf(generalSwitch.TraceError, myObject);
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Trace.WriteLineIf(generalSwitch.TraceVerbose, " is not a valid value for this method.");
 }

Return to top

Overloaded Method: WriteIf(
bool condition,
string message
)

Summary: Writes a message to the trace listeners in the Trace.Listeners collection if a condition is true.

C# Syntax:

[Conditional("")]
public static void WriteIf(
   bool condition,
   string message
);

Parameters:

condition

true to cause a message to be written; otherwise, false.true to cause a message to be written; otherwise, false.

message

A message to write. A message to write.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

This method calls the TraceListener.Write method of the trace listener.


                mySwitch.TraceError

evaluates to false you do not call Trace.Write. The second example always calls Trace.WriteIf, even when


                mySwitch.TraceError

is false and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code.

First example.

              if(mySwitch.TraceError) 
                  Trace.Write("aNumber = " + aNumber + " out of range");

Second example.

              Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range");

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Verbose, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Trace.WriteIf(generalSwitch.TraceError, "My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Trace.WriteLineIf(generalSwitch.TraceVerbose, "My second error message.");
 }

Return to top

Overloaded Method: WriteIf(
   bool condition,
   object value,
   string category
)

Summary: Writes a category name and the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection if a condition is true.

C# Syntax:

[Conditional("")]
public static void WriteIf(
   bool condition,
   object value,
   string category
);

Parameters:

condition

true to cause a message to be written; otherwise, false.true to cause a message to be written; otherwise, false.

value

An Object whose name is sent to the Trace.Listeners.

category

A category name used to organize the output.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

The category parameter can be used to group output messages.

This method calls the TraceListener.Write method of the trace listener.


                mySwitch.TraceError

evaluates to false you do not call Trace.Write. The second example always calls Trace.WriteIf, even when


                mySwitch.TraceError

is false and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code.

First example.

              if(mySwitch.TraceError) 
                  Trace.Write("aNumber = " + aNumber + " out of range");

Second example.

              Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range");

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Error or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Verbose.
    Trace.WriteIf(generalSwitch.TraceVerbose, myObject, category);
 
    // Write a second message if the TraceSwitch level is set to Error or higher.
    Trace.WriteLineIf(generalSwitch.TraceError, " Object is not valid for this category.");
 }

Return to top

Overloaded Method: WriteIf(
   bool condition,
   string message,
   string category
)

Summary: Writes a category name and message to the trace listeners in the Trace.Listeners collection if a condition is true.

C# Syntax:

[Conditional("")]
public static void WriteIf(
   bool condition,
   string message,
   string category
);

Parameters:

condition

true to cause a message to be written; otherwise, false.true to cause a message to be written; otherwise, false.

message

A message to write. A message to write.

category

A category name used to organize the output.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

The category parameter can be used to group output messages.

This method calls the TraceListener.Write method of the trace listener.


                mySwitch.TraceError

evaluates to false you do not call Trace.Write. The second example always calls Trace.WriteIf, even when


                mySwitch.TraceError

is false and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code.

First example.

              if(mySwitch.TraceError) 
                  Trace.Write("aNumber = " + aNumber + " out of range");

Second example.

              Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range");

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Error or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Verbose.
    Trace.WriteIf(generalSwitch.TraceVerbose, myObject.ToString() + 
       " is not a valid object for category: ", category);
 
    // Write a second message if the TraceSwitch level is set to Error or higher.
    Trace.WriteLineIf(generalSwitch.TraceError, " Please use a different category.");
 }

Return to top

Overloaded Method: WriteLine(
object value
)

Summary: Writes the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection.

C# Syntax:

[Conditional("")]
public static void WriteLine(
   object value
);

Parameters:

value

An Object whose name is sent to the Trace.Listeners.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

This method calls the TraceListener.WriteLine method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Verbose, the example outputs the name of the object on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Trace.Write("Invalid object. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Trace.WriteLine(myObject);
 }

Return to top

Overloaded Method: WriteLine(
string message
)

Summary: Writes a message to the trace listeners in the Trace.Listeners collection.

C# Syntax:

[Conditional("")]
public static void WriteLine(
   string message
);

Parameters:

message

A message to write.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

This method calls the TraceListener.WriteLine method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Verbose, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Trace.Write("My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Trace.WriteLine("My second error message.");
 }

Return to top

Overloaded Method: WriteLine(
object value,
string category
)

Summary: Writes a category name and the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection.

C# Syntax:

[Conditional("")]
public static void WriteLine(
   object value,
   string category
);

Parameters:

value

An Object whose name is sent to the Trace.Listeners.

category

A category name used to organize the output.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

The category parameter can be used to group output messages.

This method calls the TraceListener.WriteLine method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Verbose, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Trace.Write("Invalid object for category. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Trace.WriteLine(myObject, category);
 }

Return to top

Overloaded Method: WriteLine(
string message,
string category
)

Summary: Writes a category name and message to the trace listeners in the Trace.Listeners collection.

C# Syntax:

[Conditional("")]
public static void WriteLine(
   string message,
   string category
);

Parameters:

message

A message to write.

category

A category name used to organize the output.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

The category parameter can be used to group output messages.

This method calls the TraceListener.WriteLine method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Verbose, the example outputs the second error message and the category on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Trace.Write("My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Trace.WriteLine("My second error message.", category);
 }

Return to top

Overloaded Method: WriteLineIf(
bool condition,
object value
)

Summary: Writes the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection if a condition is true.

C# Syntax:

[Conditional("")]
public static void WriteLineIf(
   bool condition,
   object value
);

Parameters:

condition

true to cause a message to be written; otherwise, false.true to cause a message to be written; otherwise, false.

value

An Object whose name is sent to the Trace.Listeners.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

This method calls the TraceListener.WriteLine method of the trace listener.

Notes to implementors: You can minimize the performance penalty of instrumenting your application by using If...Then statements instead of using Trace.WriteLineIf statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if


                mySwitch.TraceError

evaluates to false you do not call Trace.WriteLine. The second example always calls Trace.WriteLineIf, even when


                mySwitch.TraceError

is false and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code.

First example.

              if(mySwitch.TraceError) 
                  Trace.WriteLine("aNumber = " + aNumber + " out of range");

Second example.

              Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range");

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Verbose, the example outputs the name of the object on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Trace.WriteIf(generalSwitch.TraceError, "Invalid object. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Trace.WriteLineIf(generalSwitch.TraceVerbose, myObject);
 }

Return to top

Overloaded Method: WriteLineIf(
bool condition,
string message
)

Summary: Writes a message to the trace listeners in the Trace.Listeners collection if a condition is true.

C# Syntax:

[Conditional("")]
public static void WriteLineIf(
   bool condition,
   string message
);

Parameters:

condition

true to cause a message to be written; otherwise, false.true to cause a message to be written; otherwise, false.

message

A message to write. A message to write.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

This method calls the TraceListener.WriteLine method of the trace listener.


                mySwitch.TraceError

evaluates to false you do not call Trace.WriteLine. The second example always calls Trace.WriteLineIf, even when


                mySwitch.TraceError

is false and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code.

First example.

              if(mySwitch.TraceError) 
                  Trace.WriteLine("aNumber = " + aNumber + " out of range");

Second example.

              Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range");

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Verbose, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Trace.WriteIf(generalSwitch.TraceError, "My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Trace.WriteLineIf(generalSwitch.TraceVerbose, "My second error message.");
 }

Return to top

Overloaded Method: WriteLineIf(
   bool condition,
   object value,
   string category
)

Summary: Writes a category name and the value of the object's Object.ToString method to the trace listeners in the Trace.Listeners collection if a condition is true.

C# Syntax:

[Conditional("")]
public static void WriteLineIf(
   bool condition,
   object value,
   string category
);

Parameters:

condition

true to cause a message to be written; otherwise, false.true to cause a message to be written; otherwise, false.

value

An Object whose name is sent to the Trace.Listeners.

category

A category name used to organize the output. A category name used to organize the output.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

The category parameter can be used to group output messages.

This method calls the TraceListener.WriteLine method of the trace listener.


                mySwitch.TraceError

evaluates to false you do not call Trace.WriteLine. The second example always calls Trace.WriteLineIf, even when


                mySwitch.TraceError

is false and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code.

First example.

              if(mySwitch.TraceError) 
                  Trace.WriteLine("aNumber = " + aNumber + " out of range");

Second example.

              Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range");

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

Then, if the TraceLevel is set to Verbose, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Trace.WriteIf(generalSwitch.TraceError, "Invalid object for category. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Trace.WriteLineIf(generalSwitch.TraceVerbose, myObject, category);
 }

Return to top

Overloaded Method: WriteLineIf(
   bool condition,
   string message,
   string category
)

Summary: Writes a category name and message to the trace listeners in the Trace.Listeners collection if a condition is true.

C# Syntax:

[Conditional("")]
public static void WriteLineIf(
   bool condition,
   string message,
   string category
);

Parameters:

condition

true to cause a message to be written; otherwise, false.true to cause a message to be written; otherwise, false.

message

A message to write. A message to write.

category

A category name used to organize the output.

Remarks

By default, the output is written to an instance of DefaultTraceListener.

The category parameter can be used to group output messages.

This method calls the TraceListener.WriteLine method of the trace listener.


                mySwitch.TraceError

evaluates to false you do not call Trace.WriteLine. The second example always calls Trace.WriteLineIf, even when


                mySwitch.TraceError

is false and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code.

First example.

              if(mySwitch.TraceError) 
                  Trace.WriteLine("aNumber = " + aNumber + " out of range");

Second example.

              Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range");

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside the code sample.

// Class-level declaration.
 // Create a TraceSwitch.
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyErrorMethod(String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Trace.WriteIf(generalSwitch.TraceError, "My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Trace.WriteLineIf(generalSwitch.TraceVerbose, "My second error message.", category);
 }