How to: Create, Initialize and Configure Trace Switches

Article
07/23/2022

Note

This article is specific to .NET Framework. It doesn't apply to newer implementations of .NET, including .NET 6 and later versions.

Trace switches enable you to enable, disable, and filter tracing output.

Creating and initializing a trace switch

In order to use trace switches, you must first create them and place them in your code. There are two predefined classes from which you can create switch objects: the System.Diagnostics.BooleanSwitch class and the System.Diagnostics.TraceSwitch class. You would use BooleanSwitch if you care only about whether or not a tracing message appears; you would use TraceSwitch if you want to discriminate between levels of tracing. If you use a TraceSwitch, you can define your own debugging messages and associate them with different trace levels. You can use both types of switches with either tracing or debugging. By default, a BooleanSwitch is disabled and a TraceSwitch is set to level TraceLevel.Off. Trace switches can be created and placed in any part of your code that might use them.

Although you can set trace levels and other configuration options in code, we recommend that you use the configuration file to manage the state of your switches. This is because managing the configuration of your switches in the configuration system gives you greater flexibility — you can turn on and off various switches and change levels without recompiling your application.

To create and initialize a trace switch

Define a switch as either type System.Diagnostics.BooleanSwitch or type System.Diagnostics.TraceSwitch and set the name and description of the switch.

Configure your trace switch. For more information, see Configuring trace switches.

The following code creates two switches, one of each type:

Dim dataSwitch As New BooleanSwitch("Data", "DataAccess module")
Dim generalSwitch As New TraceSwitch("General", "Entire application")

System.Diagnostics.BooleanSwitch dataSwitch =
   new System.Diagnostics.BooleanSwitch("Data", "DataAccess module");
System.Diagnostics.TraceSwitch generalSwitch =
   new System.Diagnostics.TraceSwitch("General",
   "Entire application");

Configuring trace switches

After your application has been distributed, you can still enable or disable trace output by configuring the trace switches in your application. Configuring a switch means changing its value from an external source after it has been initialized. You can change the values of the switch objects using the configuration file. You configure a trace switch to turn it on and off, or to set its level, determining the amount and type of messages it passes along to listeners.

Your switches are configured using the .config file. For a Web application, this is the Web.config file associated with the project. In a Windows application, this file is named (application name).exe.config. In a deployed application, this file must reside in the same folder as the executable.

When your application executes the code that creates an instance of a switch for the first time, it checks the configuration file for trace-level information about the named switch. The tracing system examines the configuration file only once for any particular switch — the first time your application creates the switch.

In a deployed application, you enable trace code by reconfiguring switch objects when your application is not running. Typically this involves turning the switch objects on and off or by changing the tracing levels, and then restarting your application.

When you create an instance of a switch, you also initialize it by specifying two arguments: a displayName argument and a description argument. The displayName argument of the constructor sets the Switch.DisplayName property of the Switch class instance. The displayName is the name that is used to configure the switch in the .config file, and the description argument should return a brief description of the switch and what messages it controls.

In addition to specifying the name of a switch to configure, you must also specify a value for the switch. This value is an Integer. For BooleanSwitch, a value of 0 corresponds to Off, and any nonzero value corresponds to On. For TraceSwitch, 0,1,2,3, and 4 correspond Off, Error, Warning, Info, and Verbose, respectively. Any number greater than 4 is treated as Verbose, and any number less than zero is treated as Off.

Note

In .NET Framework version 2.0, you can use text to specify the value for a switch. For example, true for a BooleanSwitch or the text representing an enumeration value such as Error for a TraceSwitch. The line <add name="myTraceSwitch" value="Error" /> is equivalent to <add name="myTraceSwitch" value="1" />.

In order for end users to be able to configure an application's trace switches, you must provide detailed documentation on the switches in your application. You should detail which switches control what and how to turn them on and off. You should also provide your end user with a .config file that has appropriate Help in the comments.

To configure trace switches

In order to use trace switches, you must first create them and place them in your code as described in the section Creating and initializing a trace switch.
If your project does not contain a configuration file (app.config or Web.config), then from the Project menu, select Add New Item.
- Visual Basic: In the Add New Item dialog box, choose Application Configuration File.
  
  The application configuration file is created and opened. This is an XML document whose root element is <configuration>.
- Visual C#: In the Add New Item dialog box, choose XML File. Name this file app.config. In the XML editor, after the XML declaration, add the following XML:
```
<configuration>
</configuration>
```
  When your project is compiled, the app.config file is copied to the project output folder and is renamed applicationname.exe.config.
After the <configuration> tag but before the </configuration> tag, add the appropriate XML to configure your switches. The following examples demonstrate a BooleanSwitch with a DisplayName property of DataMessageSwitch and a TraceSwitch with a DisplayName property of TraceLevelSwitch.
```
<system.diagnostics>
   <switches>
      <add name="DataMessagesSwitch" value="0" />
      <add name="TraceLevelSwitch" value="0" />
   </switches>
</system.diagnostics>
```
In this configuration, both switches are off.
If you need to turn on a BooleanSwitch, such as DataMessagesSwitch shown in the previous example, change the Value to any integer other than 0.
If you need to turn on a TraceSwitch, such as TraceLevelSwitch shown in the previous example, change the Value to the appropriate level setting (1 to 4).

Add comments to the .config file so the end user has a clear understanding of what values to change to configure the switches appropriately.

The following example shows how the final code, including comments, might look:

<system.diagnostics>
   <switches>
      <!-- This switch controls data messages. In order to receive data
         trace messages, change value="0" to value="1" -->
      <add name="DataMessagesSwitch" value="0" />
      <!-- This switch controls general messages. In order to
         receive general trace messages change the value to the
         appropriate level. "1" gives error messages, "2" gives errors
         and warnings, "3" gives more detailed error information, and
         "4" gives verbose trace information -->
      <add name="TraceLevelSwitch" value="0" />
   </switches>
</system.diagnostics>

Share via

How to: Create, Initialize and Configure Trace Switches

Creating and initializing a trace switch

To create and initialize a trace switch

Configuring trace switches

To configure trace switches

See also

Additional resources