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.
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.
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 Recipe 6.1 and Recipe 6.3; see the “BooleanSwitch Class” and “Trace and Debug Settings Schema” topics in the MSDN documentation.