This chapter is from the book

This chapter is from the book

Debugging ASP.old applications was generally only slightly less painful than
a trip to the dentist. There was a way to debug ASP.old applications, but it was
poorly documented and essentially required Visual InterDev and a team of crack
technicians, as well as favorable weather conditions and a whole lot of luck to
work correctly.

Many ASP.old developers got into the habit of using code like the following
as a way of creating breakpoints in their code:

Response.Write "DEBUG: Maybe this will work now."
Response.End

This is about the least-efficient kind of debugging code you can possibly
write. It's the coding equivalent of driving a car off a cliff just to lift
up the hood. At the very least, you should have a way of figuring out
what's going on in your application without having to stop its
execution.

It should come as no surprise, then, that ASP.NET recognized the severe
shortcomings in debugging Web applications and came up with a number of
compelling solutions. In ASP.NET, you can perform various useful and detailed
inspections into the inner workings of your running applications.

We'll begin our exploration of debugging ASP.NET applications with a
discussion of tracing and then move on to debugging and other diagnostic
services provided by ASP.NET and the .NET framework.

Tracing Your Web Application's Activity

Tracing is a new feature of ASP.NET that enables you to monitor the activity
of your application as it runs. Tracing requires three steps:

Equipping a page for tracing

Turning tracing on

Executing your Web application in Trace mode

When you have gone through these three steps, you'll be able to see the
results of the execution of each line of code on each page of your ASP.NET
application.

Equipping a Page for Tracing

Any ASP.NET pagecan can run in Trace mode. In fact, you technically
don't have to explicitly equip a page for tracing to derive benefit from
Trace mode. But equipping a page for tracing enables you to insert custom
markers in the trace output, so it's common to include them in all but the
most trivial ASP.NET pages. Even better, Trace mode can be turned on and off on
at the page level or the application level, so you never need to remove the code
that equips a page for tracing. Trace code won't affect performance of your
application when tracing is turned off, and you'll never have to worry
about your embarrassing ad hoc test output making its way to users because you
forgot to comment something out.

Note

The Trace object used in ASP.NET is an instance of the TraceContext class,
found in the System.Web namespace. (This class is different from the Trace class
found in the System.Diagnostics namespace; TraceContext is specific to
ASP.NET.)

The properties, methods, and events of the TraceContext class are summarized
in the reference section at the end of this chapter.

To equip a page for Trace mode, you make calls to the Write method of the
Trace object anyplace in your code you want to receive trace notification. For
example, you may be debugging a function that does not appear to be called
during the lifetime of the page. By placing a call to Trace.Write somewhere in
the body of the function, you can easily determine whether the function is being
called.

Note

Because the Trace object is created implicitly by the ASP.NET Page object,
you don't need to instantiate it yourself.

Listing 3.1 shows an example of a simple page that is equipped for
tracing.

Listing 3.1 A Simple Page Equipped for Tracing with Calls to
Trace.Write

You may recognize this page as the DataList example from Chapter 2,
"Page Framework." (Book authors enjoy recycling their own code as much
as any programmers do.) This version of the code includes calls to Trace.Write
to indicate the status of the Page_Load event procedure.

You can see the output of this trace simply by navigating to this page in a
browser. The normal page code executes and a voluminous amount of trace
information is disgorged to the bottom of the page. Under the heading Trace
Information, you should be able to see a number of page-generated trace items
(such as Begin Init and End Init) as well as the page's own custom trace
custom trace messages (such as Page_Load starting).

Categorizing Trace Output

You can assign a category to the trace output generated by your code.
Categorizing trace output can make it easier to sort out trace messages;
it's particularly useful when you view output in SortByCategory mode
(described in the next section).

You assign a category to a trace message by using an overloaded version of
the Trace.Write method. Listing 3.2 shows an example of this.

This is a slightly altered version of the Page_Load event procedure from the
previous code example. The only difference is in the pair of strings passed to
Trace.Write. When using this form of the method, the first string becomes the
category and the second string is the trace message. You can view the trace
category alongside the other trace information by viewing the page in Trace
mode, as described in the next section.

Enabling Tracing for a Page

You can turn tracing on for a particular page by using an @Page directive. To
do this, set the Trace attribute in the @Page directive to true.

<@ Page language='C#' trace="true" %>

Two Trace modes specify how trace output is sortedby time or by
category.

You control the Trace mode by using the TraceMode attribute in the @Page
directive. To sort Trace mode information by category, set the TraceMode
attribute to SortByCategory. The default setting, SortByTime, sorts the trace
output by time, oldest to newest.

When tracing is activated at the page level, a wealth of information is
displayed at the bottom of the normal page output. (Depending on what's
normally supposed to be displayed on the page, you may have to scroll down to
see the trace information.)

Trace information is divided into the following categories:

Request detailsThis includes the session ID assigned to the
user's session by ASP.NET, the time the request was made, the encoding used
in the request and response, the HTTP type, and the HTTP status code.

Trace informationThis includes trace information automatically
generated by ASP.NET, as well as custom trace items generated by calls to
Trace.Write from your code. Included in this information is a measurement of how
long each operation took to complete. You can use this information to determine
where performance bottlenecks exist in the execution of your page.

A control treeThis is a hierarchical display of all the controls on
the page.

A list of cookies transferred by the requestUnless you have
cookie-based sessions turned off in your application, typically at least one
cookie will be transferred per request (the cookie used to identify the
user's session).

HTTP headersThese are sent by the server to the browser.

Query string valuesValues requested by the browser.

HTTP server variablesThe list of all HTTP server variables sent by
the server to the browser.

Page-based tracing is useful for performance and debugging purposes. But if
you're interested in seeing aggregated tracing informationperhaps to
determine how multiple users are accessing elements of an entire Web
applicationyou must use application-level tracing, as described in the
next section.

Enabling Tracing in an Application

You can turn tracing on for all the pages in a Web application. To do this,
you must make a change in Web.config. Listing 3.3 shows an example of a
Web.config settings file that activates tracing.

Listing 3.3 Using the Web.config File to Activate Tracing for an Entire Web
Directory

In addition to the enabled and pageOutput settings, you can see that the
trace configuration settings in Web.config contain a few options that
aren't available in the debug settings found in the @Page directive.
Specifically, the requestLimit attribute enables you to limit the number of
trace requests stored on the server. This option is meaningful when you view
aggregate trace information from a remote browser window, as described in the
next section.

The localOnly attribute ensures that trace information can be viewed only by
users logged on to the Web server machine directly. This prevents remote users
from seeing trace output.

For more information on how Web.config works, see Chapter 5,
"Configuration and Deployment."

Using Application Tracing from a Remote Browser Window

When application-level tracing is activated, you can view aggregate trace
data from a separate browser window. This gives you an aggregate view of all
trace information generated by your Web application.

To do this, first equip the application for tracing by adjusting the
appropriate settings in Web.config (as described in the previous section).

Next, open two browser windows: one to view a page equipped for tracing in
the application; the second to display trace output. (We'll call this
second window the trace window.)

In the trace window, navigate to the HTTP handler trace.axd located in the
application directory. For example, if your application is located at
http://localhost/myapp/, the
Trace mode URL would be
http://localhost/myapp/trace.axd.
You should be able to see a list of application requests. The list may or may
not have any data in it, depending on whether you've refreshed the browser
that displays the application page since you started the trace.

After refreshing the application browser a few times, refresh the trace
window. You should be able to see a list of trace information. If you navigate
to another page in the application and then refresh the trace window,
you'll be able to see trace information for that page, too.

You can see that the trace window displays only aggregate information.
Further, the number of requests displayed in the window is limited to the number
you specified in the Web.config trace setting for the application. You can drill
down on each row of information by clicking the View Details link; this displays
the same detailed information you see when viewing a single page in Trace
mode.

Note

Trace.axd isn't a file; instead, it's a link to an ASP.NET feature
known as an HTTP handler. You can use the .NET framework to create your own HTTP
handlers; this is discussed in Chapter 8, "HttpHandlers and
HttpModules."