Type: System.Diagnostics.Debug

System.Diagnostics.Debug Class

Assembly: System.dll
Namespace: System.Diagnostics

Summary: Provides a set of methods and properties that help debug your code. This class cannot be inherited.

C# Syntax:


        public sealed class Debug

Thread Safety

This type is safe for multithreaded operations.

Remarks

If you use methods in the Debug class to print debugging information and check your logic with assertions, you can make your code more robust without impacting the performance and code size of your shipping product.

In Visual Studio .NET projects, creating a debug build enables Debug. To disable Debug see Visual Studio documentation.

In contrast, in Visual Studio .NET projects, Trace is enabled, so code is generated for these methods. Therefore, you can use Trace to instrument release builds.

This class provides methods to display an Debug.Assert dialog box, and to emit an assertion that will always Debug.Fail. This class provides write methods in the following variations: Debug.Write, Debug.WriteLine, Debug.WriteIf and Debug.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 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 Debug.Listeners collection. By default, the DefaultTraceListener class emits trace output.

You can modify the level of indentation using the Debug.Indent method or the Debug.IndentLevel property. To modify the indent spacing, use the Debug.IndentSize property. You can specify whether to automaticaly flush the output buffer after each write by setting the Debug.AutoFlush property to true.

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

          <configuration>
              <system.diagnostics>
                 <debug autoflush="true" indentsize="7" />
              </system.diagnostics>
           </configuration>

Note To enable debugging in C#, add the /d:DEBUG flag to the compiler command line when you compile your code, or you can add #define DEBUG to the top of your file. In Visual Basic, add the /d:DEBUG=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 DEBUG ... #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 Debug.

Example

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

public int Main(string[] args)
{
   Debug.Listeners.Add(new TextWriterTraceListener(Console.Out));
   Debug.AutoFlush = true;
   Debug.Indent();
   Debug.WriteLine("Entering Main");
   Console.WriteLine("Hello World.");
   Debug.WriteLine("Exiting Main"); 
   Debug.Unindent();
   return 0;
}

System.Diagnostics.Debug Member List:

Public Properties

AutoFlush	Read-write Gets or sets a value indicating whether Debug.Flush should be called on the Debug.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 debug 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 specified messages if the condition is false.
Close	Flushes the output buffer and then closes the Debug.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 write to the Debug.Listeners collection.
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 Debug.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 Debug.IndentLevel by one.
Write	Overloaded: `Write(object value)` Writes the value of the object's Object.ToString method to the trace listeners in the Debug.Listeners collection.
Write	Overloaded: `Write(string message)` Writes a message to the trace listeners in the Debug.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 Debug.Listeners collection.
Write	Overloaded: `Write(string message, string category)` Writes a category name and message to the trace listeners in the Debug.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 Debug.Listeners collection if a condition is true.
WriteIf	Overloaded: `WriteIf(bool condition, string message)` Writes a message to the trace listeners in the Debug.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 Debug.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 Debug.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 Debug.Listeners collection.
WriteLine	Overloaded: `WriteLine(string message)` Writes a message followed by a line terminator to the trace listeners in the Debug.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 Debug.Listeners collection.
WriteLine	Overloaded: `WriteLine(string message, string category)` Writes a category name and message to the trace listeners in the Debug.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 Debug.Listeners collection if a condition is true.
WriteLineIf	Overloaded: `WriteLineIf(bool condition, string message)` Writes a message to the trace listeners in the Debug.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 Debug.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 Debug.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.Debug

System.Diagnostics.Debug Member Details

Property: AutoFlush (read-write)

Summary: Gets or sets a value indicating whether Debug.Flush should be called on the Debug.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 Debug.Flush or Debug.Close. Setting Debug.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 Debug.AutoFlush and Debug.IndentSize for Debug, you can also edit the configuration file corresponding to the name of your application. The configuration file should be formatted like the following example:

              <configuration>
                  <system.diagnostics>
                     <debug autoflush="true" indentsize="7" />
                  </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

Debug stores this property on per-thread/per-request basis.

Example

The following example sets the indent level and emits debugging messages.

 Debug.WriteLine("List of errors:");
 Debug.Indent();
 Debug.WriteLine("Error 1: File not found");
 Debug.WriteLine("Error 2: Directory not found");
 Debug.Unindent();
 Debug.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.

Debug stores this property on per-thread/per-request basis.

              <configuration>
                  <system.diagnostics>
                     <debug autoflush="true" indentsize="7" />
                  </system.diagnostics>
               </configuration>

Return to top

Property: Listeners (read-only)

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

C# Syntax:


            public static TraceListenerCollection Listeners {get;}

Remarks

The listeners produce formatted output from the debug output. By default, the collection contains an instance of the DefaultTraceListener class. 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 Debug.Listeners.

/* Create a listener that outputs to the console screen, and 
  * add it to the debug listeners. */
 TextWriterTraceListener myWriter = new 
    TextWriterTraceListener(System.Console.Out);
 Debug.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

Debug.Assert outputs the call stack with file and line numbers for each line in the call stack.

Typically, Debug.Assert is used to identify logic errors during program development. Debug.Assert evaluates the condition. If the result is false, it sends diagnostic messages to the Debug.Listeners.

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

To set an assert, you can also edit the configuration file corresponding 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>
                        <assert assertuienabled="true" logfilename="c:\\myFile.log" />
                     </switches>
                  </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 Debug.Assert to confirm the index value is valid. If it is not valid, Debug.Assert outputs the call stack.

// Create an index for an array.
 int index;
 
 // Perform some action that sets the index.
 
 // Test that the index value is valid. 
 Debug.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

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

              <configuration>
                  <system.diagnostics>
                     <switches>
                        <assert assertuienabled="true" logfilename="c:\\myFile.log" />
                     </switches>
                  </system.diagnostics>
               </configuration>

Example

The following example checks whether the


                type

parameter is valid. If the


                type

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

public static void MyMethod(Type type, Type baseType) {
    Debug.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 specified 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.

detailMessage

A detailed message to display.

Remarks

              <configuration>
                  <system.diagnostics>
                     <switches>
                        <assert assertuienabled="true" logfilename="c:\\myFile.log" />
                     </switches>
                  </system.diagnostics>
               </configuration>

Example

The following example checks whether 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) {
    Debug.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 Debug.Listeners.

C# Syntax:

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

Remarks

Use this method when the output goes 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)) 
	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);
    Debug.Listeners.Add(myTextListener);
  
    // Write output to the file.
    Debug.WriteLine("Test output");
 
    // Flush and close the output stream.
    Debug.Flush();
    Debug.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 is the DefaultTraceListener outputs the message to a message box when the application is running in user-interface mode and to the TraceListener instances in the Debug.Listeners collection. You can customize this behavior by adding a TraceListener to, or removing one from, the Debug.Listeners collection.

Example

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

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

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

switch (option) {
    case Option.First:
       result = 1.0;
       break;
 
    // Insert additional cases.
 
    default:
       Debug.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

Example

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

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

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

    switch (option1) {
        case MyOption.First:
           result = 1.0;
           break;
     
        // Insert additional cases.
     
        default:
           Debug.Fail("Unknown Option " + option1, "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:


            ~Debug();

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 write to the Debug.Listeners collection.

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)) 
	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);
    Debug.Listeners.Add(myTextListener);
  
    // Write output to the file.
    Debug.WriteLine("Test output");
 
    // Flush and close the output stream.
    Debug.Flush();
    Debug.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 Debug.IndentLevel by one.

C# Syntax:

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

Example

The following example sets the indent level and emits debugging messages.

 Debug.WriteLine("List of errors:");
 Debug.Indent();
 Debug.WriteLine("Error 1: File not found");
 Debug.WriteLine("Error 2: Directory not found");
 Debug.Unindent();
 Debug.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:
Debug.Unindent | Debug.IndentLevel | Debug.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 Debug.IndentLevel by one.

C# Syntax:

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

Example

The following example sets the indent level and emits debugging messages.

 Debug.WriteLine("List of errors:");
 Debug.Indent();
 Debug.WriteLine("Error 1: File not found");
 Debug.WriteLine("Error 2: Directory not found");
 Debug.Unindent();
 Debug.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:
Debug.Indent | Debug.IndentLevel | Debug.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 Debug.Listeners collection.

C# Syntax:

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

Parameters:

value

An Object whose name is sent to the Debug.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 of the code sample.

If the switch is set to the TraceLevelError or higher, the example outputs the first error message to the Debug.Listeners. For information on adding a listener to the Debug.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(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Debug.Write(myObject, category);
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Debug.WriteLine(" Object is not valid for this category.");
 }

Return to top

Overloaded Method: Write(
string message
)

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

C# Syntax:

[Conditional("")]
public static void Write(
   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.Write method of the trace listener.

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of 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. 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(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Debug.Write(myObject, category);
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Debug.WriteLine(" Object is not valid for this category.");
 }

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 Debug.Listeners collection.

C# Syntax:

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

Parameters:

value

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

category

A category name used to organize the output.

Remarks

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

Use the category 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 of 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. 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(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Debug.Write(myObject, category);
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Debug.WriteLine(" Object is not valid for this category.");
 }

Return to top

Overloaded Method: Write(
string message,
string category
)

Summary: Writes a category name and message to the trace listeners in the Debug.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.

Use the category 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 of 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. 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(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Debug.Write(myObject, category);
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Debug.WriteLine(" Object is not valid for this 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 Debug.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.

value

An Object whose name is sent to the Debug.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 Debug.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 Debug.Write. The second example always calls Debug.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) 
                  Debug.Write("aNumber = " + aNumber + " out of range");

Second example.

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

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of 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 Debug.Listeners. For information on adding a listener to the Debug.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. 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(Object myObject) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Debug.WriteIf(generalSwitch.TraceError, myObject);
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Debug.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 Debug.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 Debug.Write. The second example always calls Debug.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) 
                  Debug.Write("aNumber = " + aNumber + " out of range");

Second example.

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

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of 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. 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.
    Debug.WriteIf(generalSwitch.TraceError, "My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Debug.WriteIf(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 Debug.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.

value

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

category

A category name used to organize the output.

Remarks

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

The category 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 Debug.Write. The second example always calls Debug.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) 
                  Debug.Write("aNumber = " + aNumber + " out of range");

Second example.

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

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of the code sample.

If the switch is set to the TraceLevelVerbose, the example outputs the name of the myObject and the category to the Debug.Listeners. For information on adding a listener to the Debug.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. 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(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Verbose.
    Debug.WriteIf(generalSwitch.TraceVerbose, myObject, category);
 
    // Write a second message if the TraceSwitch level is set to Error or higher.
    Debug.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 Debug.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.

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 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 Debug.Write. The second example always calls Debug.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) 
                  Debug.Write("aNumber = " + aNumber + " out of range");

Second example.

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

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of the code sample.

If the switch is set to the TraceLevelVerbose, the example outputs the first error message to the Debug.Listeners. For information on adding a listener to the Debug.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. 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(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Verbose.
    Debug.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.
    Debug.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 Debug.Listeners collection.

C# Syntax:

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

Parameters:

value

An Object whose name is sent to the Debug.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 of 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. 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(Object myObject) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Debug.Write("Invalid object. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Debug.WriteLine(myObject);
 }

Return to top

Overloaded Method: WriteLine(
string message
)

Summary: Writes a message followed by a line terminator to the trace listeners in the Debug.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 of 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. 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)
       Debug.Write("My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Debug.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 Debug.Listeners collection.

C# Syntax:

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

Parameters:

value

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

category

A category name used to organize the output.

Remarks

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

The category 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 of 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)
       Debug.Write("Invalid object for category. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Debug.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 Debug.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 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 of 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. 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(String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Debug.Write("My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Debug.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 Debug.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.

value

An Object whose name is sent to the Debug.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 Debug.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 Debug.WriteLine. The second example always calls Debug.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) 
                  Debug.WriteLine("aNumber = " + aNumber + " out of range");

Second example.

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

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of 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. 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(Object myObject) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Debug.WriteIf(generalSwitch.TraceError, "Invalid object. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Debug.WriteLineIf(generalSwitch.TraceVerbose, myObject);
 }

Return to top

Overloaded Method: WriteLineIf(
bool condition,
string message
)

Summary: Writes a message to the trace listeners in the Debug.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.

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.


                mySwitch.TraceError

evaluates to false, you do not call Debug.WriteLine. The second example always calls Debug.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) 
                  Debug.WriteLine("aNumber = " + aNumber + " out of range");

Second example.

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

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of 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. 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.
    Debug.WriteIf(generalSwitch.TraceError, "My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Debug.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 Debug.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 Debug.Listeners.

category

A category name used to organize the output.

Remarks

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

The category 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 Debug.WriteLine. The second example always calls Debug.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) 
                  Debug.WriteLine("aNumber = " + aNumber + " out of range");

Second example.

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

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of 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. 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(Object myObject, String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Debug.WriteIf(generalSwitch.TraceError, "Invalid object for category. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Debug.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 Debug.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.

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 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 Debug.WriteLine. The second example always calls Debug.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) 
                  Debug.WriteLine("aNumber = " + aNumber + " out of range");

Second example.

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

Example

The following example creates a TraceSwitch named


                generalSwitch

. This switch is set outside of 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. 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(String category) {
    // Write the message if the TraceSwitch level is set to Error or higher.
    Debug.WriteIf(generalSwitch.TraceError, "My error message. ");
 
    // Write a second message if the TraceSwitch level is set to Verbose.
    Debug.WriteLineIf(generalSwitch.TraceVerbose, "My second error message.", category);
 }