.NET Tracing Tutorial

Environment: .NET 1.1

Introduction

The Trace and Debug classes are included in the .NET framework for adding tracing support in an application. Proper tracing in the code helps in application debugging, bug fixing, and profiling. Three unique features of the .NET tracing support are: support of trace filtering using Trace Switches, Trace Listeners, and trace configuration using application configuration files without recompilation of the application.

As a convention, the Debug Class is used to instrument the code for pure debugging purposes; and this code instrumentation is not included in release builds. This is the default setting of the VS.NET. VS.NET removes the code instrumentation based on the Debug Class from release builds. Only code instrumentation based on the Trace Class is enabled in release builds. However, it is possible to change the default setting, if required.

Support of trace filtering is very important in any application. .NET supports two levels of filtering for tracing, based on the Debug and Trace Classes. The first level is to compile the application for Trace or Debug. Using this feature, it is possible to completely remove the code instrumentation based on Trace/Debug Classes from the application. The second level of filtering is supported using Trace Switches and application configuration files. It allows tracing of filtering criteria without application compilation.

Note that all members of the Trace and Debug classes are static. Thus, for its use, no member variables of these classes are required to be declared. Also, both classes have exactly the same members with similar signatures. For a complete members list of the classes, check the .NET SDK documentation.

Compiling to Include Debug/Trace Support

To enable tracing based on the Trace Class in an application, the compile time symbol, TRACE, must be defined. If this symbol is not defined, all tracing code based on the Trace Class is removed from the application during the compilation process. Similarly, tracing based on the Debug Class is controlled by the DEBUG symbol. This is the first level of filtering support as discussed above.

There are two methods to define the TRACE (or DEBUG) symbol to include the tracing support. The first one is to use the #define directive in the application code as given in the following snippet. The #define statement must be the first statement in the file.

#define DEBUG    // #define TRACE to enable Tracing based on
                 // the Trace Class
using System;
...

The second method is to define the flag while compiling the application, as shown in the following.

csc /define:DEBUG myfile.cs ...         // C# users
vbc /define:TRACE=True myfile.vb ...    // VB .NET users

Enabling or Disabling Tracing Using Trace Switches

It is possible to enable or disable Tracing based on the Trace/Debug classes using Trace Switches. By using trace switches, the level of tracing can be controlled by using the application configuration file. There are two types of tracing switches: BooleanSwitch and TraceSwitch. The BooleanSwitch is used as a flag to enable and disable the tracing. On the other hand, the TraceSwitch supports tracing levels so that trace messages at a particular level can be enabled or disabled. This is a very powerful filtering mechanism. It can be changed using configuration files without re-compilation of the application.

The following gives an example of the use of the trace switches.

BooleanSwitch boolSwitch = new BooleanSwitch("ABooleanSwitch",
                                             "Demo bool Switch");
TraceSwitch traceSwitch  = new TraceSwitch("ATraceSwitch",
                                           "Demo trace switch");

// Set the switch values programmatically
boolSwitch.Enabled = true;
traceSwitch.Level  = TraceLevel.Info;

Trace.WriteLineIf(boolSwitch.Enabled, "bool switch is enabled");
Trace.WriteLineIf(traceSwitch.TraceInfo,
                  "traceSwitch.TraceInfo is enabled");
Trace.WriteLineIf(traceSwitch.TraceError, 
                  "traceSwitch.TraceError is enabled");

When using TraceSwitch, the tracing occurs only if the current trace level is equal to or less than the specified level. For instance, in the above example, the message "traceSwitch.TraceError is enabled" will not be displayed, because the 'Trace Error' level is less than the current value of the tracing level (Trace Info). The following table shows the enumeration values of TraceLevel. To set the tracing level of a Trace Switch, these values should be used instead of using hard-coded numeric values.

Enumerated Value Integer Value Remarks
Off 0 None
Error 1 Only error messages
Warnings 2 Warning messages
Info 3 Informational messages
Verbose 4 Verbose messages

The above example explained the use of the WriteLineIf method of the Trace Class. A Trace Switch can also be used in a condition statement, as shown in the following code.

if(boolSwitch.Enabled)
  Trace.WriteLine("Boolean switch is enabled");

The above examples discussed the use of trace switches where the trace level is set programmatically. It is also possible, which is more common and effective, to set the trace level by using the application configuration files. In this method, there is no need to change and thus re-compile the application.

The following section explains the use of trace switches using application configuration files. The application configuration file for Windows as an application is named appplicationName.exe.config. For ASP.NET application files, it is named web.config.

  1. Add the following after the <configuration> but before the </configuration> tag. Note that the names here are the same as the name of trace switches (first parameter passed to the constructor) used in the application. Also note that we have used only two switches, so there are only two entries. However, there should be one entry for each trace switch used in the application.
      <system.diagnostics>
        <switches>
        <!--
            0 - Disabled
            1 - Enabled
            -->
                <add name="ABooleanSwitch" value="0" />
    
        <!--
            0 - Disabled
            1 - Gives error messages
            2 - Gives errors and warnings
            3 - Gives more detailed error information
            4 - Gives verbose trace information
            -->
                <add name="ATraceSwitch" value = "0" />
        </switches>
      </system.diagnostics>
    
    In this configuration, both switches are switched off.
  2. If a BooleanSwitch is required to be turned ON, change its value to something other than 0. For example, in the above, make the change to '<add name="ABooleanSwitch" value="1" />.
  3. If a TraceSwitch is needed to be switched ON, change the value to the appropriate level given in table above (1 to 4).

Trace Listeners

The tracing based on the Trace and Debug is sent to trace listeners registered for the application. By default, if no trace listeners are registered for the application, the tracing is sent to the DefaultTraceListener. The default listener sends the tracing message to the OutputDebugString, which can be captured using a debug monitor like DebugView from SysInternals.

The following example shows how to add a console, file, and event log as debug listeners.

Debug.Listeners.Add(new TextWriterTraceListener(Console.Out));
Debug.Listeners.Add(new TextWriterTraceListener(File.Create(
                                                "Output.txt")));
Debug.Listeners.Add(new EventLogTraceListener("SwitchesDemo"));

The download includes a MyTrace.cs and MyTrace.exe.config file to experiment the Trace and Debug classes. Use the command-line C# compiler (csc) to compile the application with and without various combinations of /define:TRACE and /define:DEBUG switches.

Downloads

Download source - 1 Kb


Comments

  • wheloltabotly PumeSonee Phobereurce 4693389

    Posted by TizefaTaNaday on 06/14/2013 09:39am

    MycleGypetete officialwholesalejordanshoes.holidaygiving.org Weedenfogue jordan11redandwhiteforsale.holidaygiving.org Boareehauri

    Reply
  • hvad vi fÃ¥r fra beats hovedtelefoner

    Posted by wanzixiao on 06/04/2013 09:51pm

    [url=http://www.beatsbydrdredanmark.webstarts.com/]Køb høretelefoner billig[/url] Et emne BIII booo kunne udrette ved hjælp af din adeptness sammen med aktivitet indenfor en ny og mere omfattende midler sammen med komplet inkluderet tilsætning i fald rigdom elektrisk strøm. Dit hygge del i de sande hovedtelefoner er dybest set vidunderligt. Du vil se disse slags Nederlag ved blot Dre nederlag opnå Nederlag ved blot at Dre Dojo hele headsets ved blot Dre krydret øretelefoner kompetente via flere superstjerner. Din BIII inkluderer en oprydning håndklæde til at foretage visse de er på jagt meget god. For nylig observerede jeg en gennemsnitlig nær ven går hele motorvejen sætte på BIII Boooplainly ved blot Doctor. Dre dojo headset af denne grund Min ægtefælle og jeg trang vil blive spurgte din ex den måde, de gjorde en udseende. [url=http://www.beatsbydrdredanmark.moonfruit.com/]beats by dre tilbud[/url] Based hovedtelefoner tilbyde lydkvalitet, der er lige så forbløffende. Ideel til nutidens digitale musik, disse hovedtelefoner giver dyb bas, en fed mellemtone, og klar, uforvrænget diskant, så du kan høre hver detail.The on-ear, lukket-back design giver langvarig komfort og en høj grad af naturlig støj isolation . Den enkeltsidede kabel er designet til at give dig masser af slæk mens modstå tangles. Integreret i kablet er Monsters ControlTalk modul, som giver dig en kontrolknap og high-grade mikrofon, ideel til styring musikafspilning, telefonopkald og tage stemmenotater på kompatible iPods, iPhones, og Blackberrys. Den guldbelagt 3,5 mm stik giver bred kompatibilitet med MP3-afspillere, cd-afspillere, computere og meget mere. [url=http://www.beatsbydrdredanmark.350.com/]beats by dre danmark[/url] Beats hovedtelefoner tilbyder en stilfuld og komfortabel design samt usædvanligt sprød lyd respons. Lydkvaliteten er for det meste afbalanceret, med varme mids og dundrende bas. Inkluderet er en nice bæretaske og en musik-telefon-kompatibelt kabel.han Monster Beats by Dr. Dre hovedtelefoner tilbyde et stilfuldt og komfortabelt design samt usædvanligt sprød lyd respons. Lydkvaliteten er for det meste afbalanceret, med varme mids og dundrende bas. Inkluderet er en nice bæretaske og en musik-telefon-kompatibelt kabel.

    Reply
  • Error in Example

    Posted by Legacy on 07/15/2003 12:00am

    Originally posted by: Andy B.

    The example contains an error:

    "...

    // Set the switch values programmatically
    boolSwitch.Enabled = true;
    traceSwitch.Level = TraceLevel.Info;

    Trace.WriteLineIf(boolSwitch.Enabled, "bool switch is enabled");
    Trace.WriteLineIf(traceSwitch.TraceInfo,
    "traceSwitch.TraceInfo is enabled");
    Trace.WriteLineIf(traceSwitch.TraceError,
    "traceSwitch.TraceError is enabled");

    When using TraceSwitch, the tracing occurs only if the current trace level is equal to or less than the specified level. For instance, in the above example, the message "traceSwitch.TraceError is enabled" will not be displayed, because the 'Trace Error' level is less than the current value of the tracing level (Trace Info)..."

    The tracing occurs only if the current trace level is equal to or greater than the specified level. Thus the message "traceSwitch.TraceError is enabled will indeed be displayed but a message that depends on a value of traceSwitch.TraceVerbose (has a value greater than the current level of Info) will not be displayed.

    Reply
  • Helpful article for .NET beginer.

    Posted by Legacy on 05/31/2003 12:00am

    Originally posted by: Justin Oh

    Nice explanations. Well done!

    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • You may already know about some of the benefits of Bluemix, IBM's open platform for developing and deploying mobile and web applications. Check out this webcast that focuses on building an Android application using the MobileData service, with a walk-through of the real process and workflow used to build and link the MobileData service within your application. Join IBM's subject matter experts as they show you the way to build a base application that will jumpstart you into building your own more complex app …

  • Protecting business operations means shifting the priorities around availability from disaster recovery to business continuity. Enterprises are shifting their focus from recovery from a disaster to preventing the disaster in the first place. With this change in mindset, disaster recovery is no longer the first line of defense; the organizations with a smarter business continuity practice are less impacted when disasters strike. This SmartSelect will provide insight to help guide your enterprise toward better …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds