One of the most useful, and easiest-to-use, diagnostic features of ASP.NET is page tracing. Simply adding Trace=true to your @Page directive causes ASP.NET to generate diagnostic information at the end of your normal page rendering, containing everything you would ever want to know about the request and its response. Page-level tracing is extremely convenient because just by placing one additional attribute on your .aspx page, you can quickly collect information about the any request made to that page. Figure 5-1 shows an example of a page that has enabled tracing and the resulting output generated when that page is rendered.

Figure 5-1. Enabling Trace on a Page

Enabling page tracing displays six pieces of information for a page, as listed in Table 5-1. The request details section shows the session ID, the time of the request, the encoding types of the request and response, and the resulting status code. The trace information section contains the output of trace statements made either by system libraries or by the page. The control tree section displays all the controls that were created to render the page along with how many rendering bytes they occupied and how much information they stored in the view state cache. The cookies collection shows the names and values of all cookies sent by a client. The headers collection shows all the header information presented by the client at the time of the request. Finally, the server variables section shows all the intrinsic server variables available to page scripts, and their values.

The goal of enabling tracing on a page is to be able to see at a glance all the relevant data associated with a particular request, to easily diagnose any problems that might have occurred. Many of the methods in ASP.NET classes generate some output to the trace stream, as you will see if you enable tracing on a page. In addition to the ASP.NET-generated output, however, it is often even more useful to have custom output from your own classes and pages printed to the trace output stream. To do this, you can access the Trace property of your Page class that references an instance of the TraceContext class. You can use the Write method to send information to the trace information region of the trace output. If instead you use the Warn method, the trace statement is printed in red to indicate it is a warning. Finally, you can check to see whether tracing is enabled by querying the IsEnabled property of the TraceContext object if your trace operation involves any additional code that should be avoided when tracing is disabled, as shown in Figure 5-2.

Figure 5-2. Writing Custom Trace Messages

It is good practice to add trace output to most of your pages and classes, even if you see no immediate need for the information. When something goes wrong on a page, you are better off having more diagnostic information to help resolve the problem quickly. Tracing is appealing because it does not generate any output or occupy any additional computation time unless you explicitly enable it, so there is no cost in liberally adding trace messages to your pages.

It is often useful, when you are trying to track down a problem, to be able to save several page traces for later review and analysis. You can do this by enabling tracing at the application level instead of the page level. When you enable tracing in your application-wide configuration file, ASP.NET saves the trace output of every page visited until you disable it. Figure 5-3 shows an example of enabling trace at the application level and the corresponding output generated by navigating to the trace.axd URL at any location in your application.

Figure 5-3. Enabling Application-Level Tracing

The attributes for the trace element are shown in Table 5-2. In addition to simply enabling, trace accepts requestLimit as an attribute to control how many pages to trace (which defaults to 10), pageOutput to control whether page-level tracing is shown as well, traceMode to control the sorting of the trace output, and localOnly to control whether remote access to the site can see the trace output. Once tracing has been enabled for an application, all requests made for pages in that application are traced and stored in-memory in the worker process. To view the page traces, navigate to trace.axd at the root of the application, for which a special HttpHandler is defined, and ASP.NET displays a list of all the traces stored since application-level tracing was enabled.

In addition to the page-level diagnostic features, ASP.NET provides many counters for the performance monitoring utility to track the performance and behavior of your applications. More than 50 counters are available, ranging from how many times the worker process has restarted to how many requests are processed per second. A partial list of the available counters is shown in Table 5-3.

When you install ASP.NET, these counters should be installed on the same machine. To use any of the counters, bring up the Performance administrative tool (perfmon.exe), and choose to add a counter. You should see two categories of ASP.NET performance objects, one simply labeled ASP.NET and the other labeled ASP.NET Applications. Figure 5-4 shows a sample instance of the Performance tool with three of the ASP.NET performance counters activated.

Figure 5-4. Performance Monitor

One of the most compelling aspects of working with the CLR is that even poorly written code is unlikely to cause your program to crash. Because all memory is accessed through references, array boundaries are maintained and checked on access, and direct pointers into memory are a thing of the past,^[12] it is almost impossible to cause a program error by writing to the wrong block of memory. This is not to say, however, that programs are now guaranteed error-free, but that errors are recognized by the runtime and can be dealt with programmatically.

Whenever errors are detected by the runtime, such as a divide by zero or a failure to connect to a database, an exception is thrown. Ideally, your ASP.NET pages and components should trap any potential exceptions and decide what to do for recovery where the exception occurred. Often, however, programs do not check for all potential exceptions, so any unhandled exceptions propagate up the call stack to a top-level exception handler provided by ASP.NET. If you receive an unhandled exception when you are running on the server machine, ASP.NET will print a useful diagnostic message containing a stack trace and source code showing the location the error was generated. If your application is accessed remotely when an unhandled exception occurs, however, your clients will see an error page that looks like the one shown in Figure 5-7.

Figure 5-7. Default ASP.NET Display for Unhandled Exceptions

As a developer, you should be embarrassed if your clients ever see this page. Not only does it state that an unhandled error occurred on the server, but it gives advice on how to configure the application to avoid showing this page again. The second piece of advice given by this page is one you should always follow: Include a customErrors element in your configuration file that provides a redirection to your own internal error handling page so that clients never see this page. The only disadvantage to this solution is that you lose the exception information when ASP.NET redirects clients to the default error page you specify, so there is no way to log information about the error or to give clients information to pass along to you so that you can analyze what went wrong.

To deal with this lack of error information in your default redirection page, you can provide a handler for the Error event of the HttpApplication class. This event is issued whenever there is an unhandled exception, and it is called before the internal ASP.NET unhandled event code executes, giving you the chance to deal with the error yourself and perhaps not display an error page at all. To add a handler to this even, create a global.asax file, and define a function named Application_Error, as shown in Listing 5-5. By calling the ClearError() method of the HttpContext class, you can prevent ASP.NET's unhandled exception code from ever being executed. Be warned, however, that calling ClearError() also prevents any redirection to other error pages you may have defined for specific HTTP error codes.

<!— global.asax —>
<%@ Application Language='C#' %>
<script runat=server>
protected void Application_Error(object src, EventArgs e)
{
  Exception ex = Server.GetLastError();
  // do something with the error here, such as
  // writing to the event log
  // The following line writes the error message
  // to the event log with a source of "MyApp"
  // Note that the "MyApp" source must be preregistered
  EventLog.WriteEntry("MyApp", ex.Message,
                      EventLogEntryType.Error);

  // At this point you could call:
  // Context.ClearError();
  // to clear the error and continue execution.
  // In general, you don't want to do this, because it will
  // prevent ASP.NET from redirecting to your error pages
}
</script>

The one other possible approach, which gives you the best of both worlds, is to look at the error in your Error handler, and if it is an unhandled exception, perform a Server.Transfer() to a custom error page you have built that displays information to users about the unhandled exception, which they could then relay to you. If it is any other type of error, just let it pass through, and ASP.NET will take care of redirecting users to the appropriate error page. It is important to perform the Server.Transfer() to the error page to retain the exception information, because performing a Server.Redirect() cause a round-trip back to the client, and the error information will be lost. Listing 5-6 shows the technique for performing the test on the exception and executing a transfer to the error page, and Listing 5-7 shows the sample error page that then has access to the exception information. Note that the exception typically is passed through the InnerException field of the Exception class.

// in global.asax
protected void Application_Error(Object sender, EventArgs e) {
  if (Server.GetLastError() is HttpUnhandledException)
      Server.Transfer("MyErrorPage.aspx");

  // Otherwise, we fall through, and the normal ASP.NET
  // error handling takes over
}

<!— MyErrorPage.aspx —>
<%@ Page Language='C#' %>
<html>
<h1>My error page</h1>
<%
Exception ex = Server.GetLastError();
     if (ex != null)
     {
          string err="";
          if (ex.InnerException != null)
          Response.Output.Write("The error was: {0}",
                        ex.InnerException.Message);
}
%> </html>