Tracing Your Web Application s Activity | C# Developer[ap]s Guide to ASP. NET, XML, and ADO. NET

for RuBoard

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

 <% @Page language="C#" debug="true" trace="true" %> <html> <head>   <title>ASP.NET DataList Control</title> </head> <script runat="server">   public void Page_Load(Object sender, EventArgs e)   {     Trace.Write("Page_Load starting.");     if (!IsPostBack)     {       Trace.Write("IsPostBack is false; creating data source.");       Hashtable h = new Hashtable();       h.Add ("SF", "San Francisco");       h.Add ("AZ", "Arizona");       h.Add ("CO", "Colorado");       h.Add ("SD", "San Diego");       h.Add ("LA", "Los Angeles");       Trace.Write("Data binding.");       DataList1.DataSource = h;       DataList1.DataBind();     }     Trace.Write("Page_Load ending.");   } </script> <body>   <form runat="server">     <asp:DataList id="DataList1" runat="server"       BorderColor="black" BorderWidth="1" CellPadding="3"       Font-Name="Verdana" Font-Size="8pt">       <HeaderStyle BackColor="#000000" ForeColor="#FFFF99"></HeaderStyle>       <AlternatingItemStyle BackColor="#FFFF99"></AlternatingItemStyle>       <HeaderTemplate>         National League West       </HeaderTemplate>       <ItemTemplate>         <%# DataBinder.Eval(Container.DataItem, "Value") %>         [<%# DataBinder.Eval(Container.DataItem, "Key") %>]       </ItemTemplate>     </asp:DataList>   </form> </body> </html>

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.

Listing 3.2 Creating Categorized Trace.Write Output

 public void Page_Load(Object sender, EventArgs e) {     Trace.Write("My Application", "Page_Load starting.");     if (!IsPostBack)     {       Trace.Write("My Application", "IsPostBack is false;" +             "creating data source.");       Hashtable h = new Hashtable();       h.Add ("SF", "San Francisco");       h.Add ("AZ", "Arizona");       h.Add ("CO", "Colorado");       h.Add ("SD", "San Diego");       h.Add ("LA", "Los Angeles");       Trace.Write("Data binding.");       DataList1.DataSource = h;       DataList1.DataBind();     }     Trace.Write("My Application", "Page_Load ending."); }

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 sortedby 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 detailsThis 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 informationThis 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 treeThis is a hierarchical display of all the controls on the page.
A list of cookies transferred by the requestUnless 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 headersThese are sent by the server to the browser.
Query string valuesValues requested by the browser.
HTTP server variablesThe 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 informationperhaps to determine how multiple users are accessing elements of an entire Web applicationyou 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

 <configuration>    <system.web>       <trace enabled="true"          requestLimit="15"          pageOutput="true"          localOnly="true" />    <system.web> </configuration>

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."

for RuBoard