To turn on tracing, you need to enable tracing in Web.Config like so:

<configuration>
   <system.web>
         <trace enabled='true'/>
   </system.web>
</configuration>

This simply turns tracing on. You can actually control several aspects of page tracing. For example, you could have tracing available on the host machine (in case you don't want clients getting to your trace information). You might also want to control the number of responses that are held in memory.

Table 16-1 shows the possible values that may go in the configuration file to support tracing.

Table 16-1 Web.Config settings supporting tracing.

Key	Possible Values	Meaning
enabled	true false	Enable or disable application-level tracing
localOnly	true false	Specify whether to show trace output only on local host or everywhere
pageOutput	true false	Specify whether to display trace output on individual pages in addition to caching application-level traces
mostRecent	true false	Specify whether to recycle traces once requestLimit is met or to keep the first N (up to the requestLimit threshold)
writeToDiagnosticsTrace	true false	Specify whether the trace data is also piped to System.Diagnostics.Trace
requestLimit	Decimal number	Specify how many traces to store in memory before removing earlier traces (default is 10)

The following exercise demonstrates how application-level tracing works and how to navigate around the results.

Application-level Tracing

1. Open the DebugORama project. Open the TraceMe.aspx page. Turn tracing off in the page by ensuring the Page class's Trace property is false.

2. Ensure that tracing is turned on in Web.Config. That is, open Web.Config and add a trace element, as shown above. If the application doesn't yet have a configuration file, you may add one by selecting Add New Item from the local project menu.

3. Surf to the page a few times.

4. In the URL appearing in the navigation bar, make the endpoint Trace.axd. Using this name in the URL redirects request processing through a special handler that will render the tracing results being kept in memory.

   

5. You should be able to see a list of requests. To see individual requests, get the request details by clicking on the link.

   

   Notice how the output is exactly the same as the output on the earlier page tracing example. However, now the tracing information stands alone without cluttering up the Web page.

Enabling Tracing Programmatically

While much of the time you'll find yourself enabling tracing via the designer, there are times when it's useful to manage tracing during runtime (programmatically). For example, you might have regular clients receive normal content; however, when someone with specific credentials appears, you might want to enable tracing for that individual. You might also decide to modify tracing when a certain parameter comes through the request.

The DebugORama site includes a page named EnableTracing.aspx that illustrates how to control the tracing programmatically. If the user types the correct password, the tracing is turned on. The page also shows how to enable and disable tracing programmatically.

public partial class EnableTracing : System.Web.UI.Page
{
   protected void Page_Load(object sender, EventArgs e)
   {
   }
   protected void Button1_Click(object sender, EventArgs e)
   {
      if (this.TextBoxPassword.Text == "password")
      {
         this.Trace.IsEnabled = true;
      }
   }
   protected void Button2_Click(object sender, EventArgs e)
   {
      this.Trace.IsEnabled = false;
   }
}

The TraceFinished Event

The tracing context includes an interesting event named TraceFinished that gives you a last chance opportunity to log the tracing information or deal with it in some other way. The TraceFinished event is raised by the Trace object after all request information is gathered.

To subscribe to the event, simply set up the handler during the Page_Load event. The DebugORama example includes a page named TraceFinished.aspx that shows gathering the trace information and writing it to the debug console using System.Diagnostics.Debug.

public partial class TraceFinished : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
      Trace.TraceFinished +=
         new TraceContextEventHandler(TracingFinished);
    }
   void TracingFinished(object sender, TraceContextEventArgs e)
   {
      foreach (TraceContextRecord traceContextRecord in e.TraceRecords)
      {
         System.Diagnostics.Debug.WriteLine(
   traceContextRecord.Message);
      }
   }
}

Piping Other Trace Messages

In the last example, tracing messages were logged manually to the debug console by setting up the TraceFinished event handler in the Trace context. System.Diagnostics.Debug is a standard .NET type that's helpful for managing tracing and debugging information. ASP.NET 2.0 now has the ability to plug the WebPageTraceListener type so that calls to System.Diagnostics.Trace are also inserted into the ASP.NET trace. Setting it up is simply a matter of inserting a line into Web.Config. Notice this lies outside the normal System.web section of Web.Config.

<system.codedom>
    <compilers>
        <compiler compilerOptions="/d:TRACE" />
    </compilers>
</system.codedom>