How to: Configure 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.

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 create and configure trace switches

1. Create your switches in code. For more information, see Creating and Initializing Trace Switches.

2. 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.

3. 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.

4. 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.

5. 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).

6. 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>
   

See Also

Tasks

How to: Add Trace Statements to Application Code

Concepts

Introduction to Instrumentation and Tracing

Trace Switches

Reference

Trace and Debug Settings Schema

Other Resources

Tracing and Instrumenting Applications