Recipe 6.2 Providing Fine-Grained Control Over Debugging/Tracing Output

Problem

Your application consists of multiple components. You need, at specific times, to turn on debug/trace output for a select few components, while leaving all other debug/trace output turned off. In addition, you need control over the type and amount of information that is produced by the Trace/Debug statements.

Solution

Use the BooleanSwitch class with an application configuration file (*.config). The following method creates three switches for our application: one that controls tracing for database calls, one that controls tracing for UI components, and one that controls tracing for any exceptions that are thrown by the application:

public class Traceable
{
    BooleanSwitch DBSwitch = null;
    BooleanSwitch UISwitch = null;
    BooleanSwitch exceptionSwitch = null;

    public void EnableTracing( )
    {
        DBSwitch = new BooleanSwitch("DatabaseSwitch", 
                   "Switch for database tracing");
        Console.WriteLine("DBSwitch Enabled = " + DBSwitch.Enabled);

        UISwitch = new BooleanSwitch("UISwitch", 
                   "Switch for user interface tracing");
        Console.WriteLine("UISwitch Enabled = " + UISwitch.Enabled);

        exceptionSwitch = new BooleanSwitch("ExceptionSwitch", 
                          "Switch for tracing thrown exceptions");
        Console.WriteLine("ExceptionSwitch Enabled = " + exceptionSwitch.Enabled);
    }
}

After creating each switch, the Enabled property is displayed, indicating whether the switch is on or off.

Creating these switches without an application configuration file results in every switch getting set to false. To control what state each switch is set to, use an application configuration file, shown here:

<?xml version="1.0" encoding="utf-8" ?> 
<configuration>
    <system.diagnostics>
        <switches>
            <clear/>   
            <add name="DatabaseSwitch" value="1" />
            <add name="UISwitch" value="0" />
            <add name="ExceptionSwitch" value="0" />
        </switches>
    </system.diagnostics>
</configuration>

The TraceSwitch class can also be used with an application configuration file (AppName.exe.config). The following method creates a new TraceSwitch object with a level assigned by the application configuration file:

public class Traceable
{
    TraceSwitch DBFilterSwitch = null;
    TraceSwitch UIFilterSwitch = null;
    TraceSwitch exceptionFilterSwitch = null;

    public void SetTracingFilter( )
    {
        DBFilterSwitch = new TraceSwitch("DatabaseFilter", 
                         "Filter database output");
        Console.WriteLine("DBFilterSwitch Level = " + DBFilterSwitch.Level);

        UIFilterSwitch = new TraceSwitch("UIFilter", 
                         "Filter user interface output");
        Console.WriteLine("UIFilterSwitch Level = " + UIFilterSwitch.Level);

        exceptionFilterSwitch = new TraceSwitch("ExceptionFilter", 
                                "Filter exception output");
        Console.WriteLine("exceptionFilterSwitch Level = " 
                          + exceptionFilterSwitch.Level);
    }
}

After creating each filter switch, the Level property is displayed to indicate the switch's level.

Creating these switches at this point results in every switch's level being set to zero. To turn them on, use an application configuration file, shown here:

<?xml version="1.0" encoding="utf-8" ?> 

<configuration>
    <system.diagnostics>
        <switches>
            <clear/>   
            <add name="DatabaseFilter" value="4" />
            <add name="UIFilter" value="0" />
            <add name="ExceptionFilter" value="1" />
        </switches>
    </system.diagnostics>
</configuration>

This XML file contains a nested tag called switches. This tag defines switch names and sets a value indicating the level of the switch. The TraceSwitch class accepts five predefined trace levels shown in Table 6-1. The level of the TraceSwitch can be set through code, but that would defeat the flexibility of using a configuration file.

Table 6-1. The TraceSwitch class's tracing levels

Level name	Value	Default
Off	0	Yes
Error	1	No
Warning	2	No
Info	3	No
Verbose	4	No

For more information on the application configuration file, see Recipe 6.1.

Discussion

Turning tracing on or off involves the BooleanSwitch class. When the BooleanSwitch is created, it attempts to locate a switch with the same name as the displayName parameter in either the machine.config or application configuration files. If it cannot locate this name in either file, BooleanSwitch is set to false.

The application configuration file is an XML file named with the assembly's name followed by .exe.config. An application will automatically use a config file with the same name as the executable; however, the config file must be in the same directory as the application. Notice the switches tag nested inside the <system.diagnostics> element. This tag allows switches to be added and their values set. For Boolean switches, a zero turns the switch off, and any other positive or negative number turns it on. The Enabled property of the BooleanSwitch can be set through code, but that would defeat the flexibility of using a configuration file.

This XML file must have the same name as the executable using these switches, followed by .config. For example, if the executable name were Accounting.exe, the configuration file would be named Accounting.exe.config. This file should be placed in the same directory as the executable Accounting.exe. For more information on this file, see Recipe 6.1.

The application configuration file can also set trace and debug output levels in this same switches tag. These levels identify the scope of the output, for example, if the output will contain only warnings, only errors, only informational messages, or some combination thereof. Of course, this is only an example, you may define your own levels as well. For more information on controlling these output levels, see Recipe 6.3.

The TraceSwitch class operates similarly to the BooleanSwitch class, except that the TraceSwitch class encapsulates the available levels that control the type and amount of debug/trace output. The BooleanSwitch class is simply an on/off switch used to enable or disable debugging/tracing.

When the TraceSwitch is created, it attempts to locate a switch with the same name as the displayName parameter in either the machine.config or application configuration files. If it cannot locate this name in either file, the TraceSwitch.Level property is set to zero.

The application configuration file can also enable or disable trace and debug output in this same switches tag. For more information on this topic, see Recipe 6.1.

See Also

See Recipe 6.1 and Recipe 6.3; see the "BooleanSwitch Class" and "Trace and Debug Settings Schema" topics in the MSDN documentation.