System.Diagnostics.TraceSwitch Class

Summary

Provides a multilevel switch to control tracing and debug output without recompiling your code.

C# Syntax:

public class TraceSwitch : Switch

You can use the trace levels to filter out messages based on their importance.

To set the level of your TraceSwitch, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example:

          <configuration>
           <system.diagnostics>
           <switches>
           <add name="mySwitch" value="10" />
           <add name="myNewSwitch" value="20" />
           <remove name="mySwitch" />
           <clear/>
           </switches>
           </system.diagnostics>
           </configuration>
        

When the TraceSwitch.#ctor constructor cannot find initial switch settings in the configuration file, the TraceSwitch.Level of the new switch is set to TraceLevel.Off.

The TraceSwitch class provides the TraceSwitch.TraceError, TraceSwitch.TraceWarning, TraceSwitch.TraceInfo, and TraceSwitch.TraceVerbose properties test the TraceSwitch.Level of the switch. The TraceSwitch.Level property gets or sets the switch's TraceLevel.

You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler.

• 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 enable tracing using in C#, add the /d:TRACE flag to the compiler command line when you compile your code, or add #define TRACE to the top of your file. In Visual Basic, add the /d:TRACE=True flag to the compiler command line.

For more information on instrumenting your application, see Debug and Trace.

Note To improve performance, you can make TraceSwitch members static in your class.

The following example creates a new TraceSwitch and uses the switch to determine whether to print error messages. The switch is created at the class level. MyMethod will write the first error message if the TraceSwitch.Level is set to TraceSwitch.TraceError or higher. However, MyMethod will not write the second error message when the TraceSwitch.Level is less than TraceSwitch.TraceVerbose.

//Class-level declaration.
 /* Create a TraceSwitch to use in the entire application. This switch is set
  * by using values stored in the registry or in environmental variables. */
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Console.WriteLine("My error message.");
 
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Console.WriteLine("My second error message.");
 }
 
 public static void Main(string[] args) {
    // Run the method that prints error messages based on the switch level.
    MyMethod();
 }
 

    

System.Diagnostics Namespace | Switch | BooleanSwitch | TraceLevel | Debug | Trace

System.Diagnostics.TraceSwitch Member List:

Public Constructors

ctor #1

Initializes a new instance of the TraceSwitch class.

Public Properties

Description (inherited from System.Diagnostics.Switch)	Read-only See base class member description: System.Diagnostics.Switch.Description Gets a description of the switch.
DisplayName (inherited from System.Diagnostics.Switch)	Read-only See base class member description: System.Diagnostics.Switch.DisplayName Gets a name used to identify the switch.
Level	Read-write Gets or sets the trace level that specifies the messages to output for tracing and debugging.
TraceError	Read-only Gets a value indicating whether the TraceSwitch.Level is set to Error, Warning, Info, or Verbose.
TraceInfo	Read-only Gets a value indicating whether the TraceSwitch.Level is set to Info or Verbose.
TraceVerbose	Read-only Gets a value indicating whether the TraceSwitch.Level is set to Verbose.
TraceWarning	Read-only Gets a value indicating whether the TraceSwitch.Level is set to Warning, Info, or Verbose.

Public Methods

Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
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.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Properties

SwitchSetting (inherited from System.Diagnostics.Switch)

Read-write See base class member description: System.Diagnostics.Switch.SwitchSetting Gets or sets the current setting for this switch.

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.
OnSwitchSettingChanged	Overridden: Update the level for this switch.

Hierarchy:

• System.Object
• System.Diagnostics.Switch
• System.Diagnostics.TraceSwitch

System.Diagnostics.TraceSwitch Member Details

Summary

Initializes a new instance of the TraceSwitch class.

C# Syntax:

public TraceSwitch(    string displayName,    string description );

displayName

A name for the switch.

description

A description of the switch.

To set the level of your TraceSwitch, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example:

              <configuration>
                  <system.diagnostics>
                     <switches>
                        <add name="mySwitch" value="10" />
                        <add name="myNewSwitch" value="20" />
                        <remove name="mySwitch" />
                        <clear/>
                     </switches>
                  </system.diagnostics>
               </configuration>
            

When the TraceSwitch.#ctor constructor cannot find initial switch settings in the configuration file, the TraceSwitch.Level of the new switch is set to TraceLevel.Off.

The TraceSwitch class provides the TraceSwitch.TraceError, TraceSwitch.TraceWarning, TraceSwitch.TraceInfo, and TraceSwitch.TraceVerbose properties test the TraceSwitch.Level of the switch. The TraceSwitch.Level property gets or sets the switch's TraceLevel.

Note To improve performance, you can make TraceSwitch members static in your class.

The following example creates a new TraceSwitch and uses the switch to determine whether to print error messages. This example creates the switch at the class level. MyMethod will write the first error message if the TraceSwitch.Level is set to TraceSwitch.TraceError or higher. However, MyMethod will not write the second error message when the TraceSwitch.Level is less than TraceSwitch.TraceVerbose.

//Class-level declaration.
 /* Create a TraceSwitch to use in the entire application. This switch is set
  * by using values stored in the registry or in environmental variables. */
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Console.WriteLine("My error message.");
 
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Console.WriteLine("My second error message.");
 }
 
 public static void Main(string[] args) {
    // Run the method that prints error messages based on the switch level.
    MyMethod();
 }
 

    

Return to top

Inherited
See base class member description: System.Diagnostics.Switch.Description

Summary

Gets a description of the switch.

C# Syntax:

public string Description {get;}

This property should indicate the function of the switch. For example, "Enables tracing for a directory watcher component."

Return to top

Inherited
See base class member description: System.Diagnostics.Switch.DisplayName

Summary

Gets a name used to identify the switch.

C# Syntax:

public string DisplayName {get;}

When you create a new Switch object, the Switch.DisplayName finds initial switch settings. For more information, see the Switch.#ctor constructor and the TraceSwitch Configuration topic in the Visual Studio documentation.

Return to top

Summary

Gets or sets the trace level that specifies the messages to output for tracing and debugging.

C# Syntax:

public TraceLevel Level {get; set;}

Exceptions

Exception Type	Condition
ArgumentException	Setting the level to a value not in the TraceLevel enumeration.

To set the level of your TraceSwitch, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example:

              <configuration>
                  <system.diagnostics>
                     <switches>
                        <add name="mySwitch" value="10" />
                        <add name="myNewSwitch" value="20" />
                        <remove name="mySwitch" />
                        <clear/>
                     </switches>
                  </system.diagnostics>
               </configuration>
            

When the TraceSwitch.#ctor constructor cannot find initial switch settings in the configuration file, the TraceSwitch.Level of the new switch is set to TraceLevel.Off.

Setting this property will update the TraceSwitch.TraceError, TraceSwitch.TraceWarning, TraceSwitch.TraceInfo, and TraceSwitch.TraceVerbose properties in this class to the new value.

The following example creates a new TraceSwitch and uses the switch to determine whether to print error messages. The switch is created at the class level. MyMethod will write the first error message if the TraceSwitch.Level is set to TraceSwitch.TraceError or higher. However, MyMethod will not write the second error message when the TraceSwitch.Level is less than TraceSwitch.TraceVerbose.

//Class-level declaration.
 /* Create a TraceSwitch to use in the entire application. This switch is set
  * by using values stored in the registry or in environmental variables. */
 
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Console.WriteLine("My error message.");
 
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Console.WriteLine("My second error message.");
 }
 
 public static void Main(string[] args) {
    // Run the method that prints error messages based on the switch level.
    MyMethod();
 }


    

Return to top

Inherited
See base class member description: System.Diagnostics.Switch.SwitchSetting

Summary

Gets or sets the current setting for this switch.

C# Syntax:

protected int SwitchSetting {get; set;}

Return to top

Summary

Gets a value indicating whether the TraceSwitch.Level is set to Error, Warning, Info, or Verbose.

C# Syntax:

public bool TraceError {get;}

When the TraceSwitch.Level is set to Error, only error-handling messages are output. When the TraceSwitch.Level is set to Warning, Info, or Verbose, additional tracing or debugging messages are output.

The following example creates a new TraceSwitch and uses the switch to determine whether to print error messages. The switch is created at the class level. MyMethod will write the first error message if the TraceSwitch.Level is set to TraceSwitch.TraceError or higher. However, MyMethod will not write the second error message when the TraceSwitch.Level is less than TraceSwitch.TraceVerbose.

//Class-level declaration.
 /* Create a TraceSwitch to use in the entire application. This switch is set
  * by using values stored in the registry or in environmental variables. */
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Console.WriteLine("My error message.");
 
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Console.WriteLine("My second error message.");
 }
 
 public static void Main(string[] args) {
    // Run the method that prints error messages based on the switch level.
    MyMethod();
 }
 

    

Return to top

Summary

Gets a value indicating whether the TraceSwitch.Level is set to Info or Verbose.

C# Syntax:

public bool TraceInfo {get;}

When the TraceSwitch.Level is set to Warning, informational messages, warnings and error-handling messages are output. When the TraceSwitch.Level is set to Verbose, additional tracing or debugging messages are output.

The following example creates a new TraceSwitch and uses the switch to determine whether to print error messages. The switch is created at the class level. MyMethod will write the first error message if the TraceSwitch.Level is set to TraceSwitch.TraceInfo or higher. However, MyMethod will not write the second error message when the TraceSwitch.Level is less than TraceSwitch.TraceVerbose.

//Class-level declaration.
 /* Create a TraceSwitch to use in the entire application. This switch is set
  * by using values stored in the registry or in environmental variables. */
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyMethod() {
    // Write the message if the TraceSwitch level is set to Info or higher.
    if(generalSwitch.TraceInfo)
       Console.WriteLine("My error message.");
 
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Console.WriteLine("My second error message.");
 }
 
 public static void Main(string[] args) {
    // Run the method that prints error messages based on the switch level.
    MyMethod();
 }
 

    

Return to top

Summary

Gets a value indicating whether the TraceSwitch.Level is set to Verbose.

C# Syntax:

public bool TraceVerbose {get;}

When the TraceSwitch.Level is set to Verbose, all debugging and tracing messages are output.

The following example creates a new TraceSwitch and uses the switch to determine whether to print error messages. The switch is created at the class level. MyMethod will write both error messages when the TraceSwitch.Level is set to TraceSwitch.TraceVerbose.

//Class-level declaration.
 /* Create a TraceSwitch to use in the entire application. This switch is set
  * by using values stored in the registry or in environmental variables. */
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyMethod() {
    // Write the message if the TraceSwitch level is set to Error or higher.
    if(generalSwitch.TraceError)
       Console.WriteLine("My error message.");
 
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Console.WriteLine("My second error message.");
 }
 
 public static void Main(string[] args) {
    // Run the method that prints error messages based on the switch level.
    MyMethod();
 }
 

    

Return to top

Summary

Gets a value indicating whether the TraceSwitch.Level is set to Warning, Info, or Verbose.

C# Syntax:

public bool TraceWarning {get;}

When the TraceSwitch.Level is set to Warning, warnings and error-handling messages are output. When the TraceSwitch.Level is set to Info or Verbose, additional tracing or debugging messages are output.

The following example creates a new TraceSwitch and uses the switch to determine whether to print error messages. The switch is created at the class level. MyMethod will write the first error message if the TraceSwitch.Level is set to TraceSwitch.TraceWarning or higher. However, MyMethod will not write the second error message when the TraceSwitch.Level is less than TraceSwitch.TraceVerbose.

//Class-level declaration.
 /* Create a TraceSwitch to use in the entire application. This switch is set
  * by using values stored in the registry or in environmental variables. */
 static TraceSwitch generalSwitch = new TraceSwitch("General", "Entire Application");
 
 static public void MyMethod() {
    // Write the message if the TraceSwitch level is set to Warning or higher.
    if(generalSwitch.TraceWarning)
       Console.WriteLine("My error message.");
 
    // Write the message if the TraceSwitch level is set to Verbose.
    if(generalSwitch.TraceVerbose)
       Console.WriteLine("My second error message.");
 }
 
 public static void Main(string[] args) {
    // Run the method that prints error messages based on the switch level.
    MyMethod();
 }
 

    

Return to top

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

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

C# Syntax:

~TraceSwitch();

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

Return to top

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

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

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

Summary

Update the level for this switch.

This type supports the Shared Source CLI infrastructure and is not intended to be used directly from your code.

C# Syntax:

protected override void OnSwitchSettingChanged();

Return to top

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

Top of page