Writing Trace Messages

Article
10/17/2014

ASP.NET includes a Trace object (similar to the Response, Request, and Context objects) that allows you to write debug statements that appear when you enable tracing for a page or for the entire application.

ASP.NET uses the TraceContext class to store information about a request, its control hierarchy, and trace information. Trace information includes some of the life-cycle stages of a page request and any custom statements you choose to include. The TraceContext class is available to Web Forms pages through the Page.Trace property. When you create custom ASP.NET server controls by extending the Control class, you can access the TraceContext class through the Control.Context property using Control.Context.Trace syntax. However, if you want to include trace statements from files other than a page or control, such as your application's Global.asax file or a class that extends the IHttpHandler interface, you must use the HttpContext.Current property to access the TraceContext class. In this case, use HttpContext.Current.Trace syntax.

The TraceContext class provides two methods, Write and Warn, which allow you to write statements to the trace log. Each method is overloaded and allows you to specify a tracing category, a text message, and optional error information. The only difference between these methods is that the Warn method displays its text in red.

Note When you specify a category in a call to the Write or Warn method, you can use this category to sort trace statements. For more information, see Enabling Tracing for a Page and Enabling Application-Level Tracing.

Each of these methods is overloaded and has three versions. If you include only one string argument when you call Warn or Write, ASP.NET treats this as a message. If you include two arguments, the first is treated as a category, which you can use to sort where your messages appear in the Trace Information table that is displayed when tracing is enabled. The third argument is of type Exception and contains error information for the request, if there is any.

These trace statements and the rest of the tracing information are displayed in a requesting browser when you enable tracing for the page or entire application.

Security Note When tracing is enabled for a page, trace information is displayed on any browser that makes a request for the page from the server. Tracing displays sensitive information, such as the values of server variables, and can therefore represent a security threat. Be sure to disable page tracing for the page before porting your application to a production server. You can do this by setting the Trace attribute to false, or by removing it.

The following screen shot illustrates custom trace statements, rendered to the Trace Information table, when tracing is enabled for a page. The Warn method is used to generate the first message in red text, with a category of Render and a message of Text is about to render!. The Write method is used to generate the second custom message with the same category, but with a message of Text finished rendering!.

Trace statements in a page

z48bew18.writetotrace(en-us,VS.71).gif

To write custom trace messages to the trace log from a page

In your page's code-declaration block or code-behind class, call one of the TraceContext methods, using the Trace property.
Specify the optional category parameter for your trace statement. You can use this category to sort trace statements when they are displayed.
Specify the message parameter for your trace statement. This can be a string or a method.
Specify the optional errorInfo parameter that contains information about any errors in the page.

The following example of the TraceContext.Warn method defines a category of Render and a trace message of Text is about to render.
```
Trace.Warn("Render", "Text is about to render.");
[Visual Basic]
Trace.Warn("Render", "Text is about to render.")
```

To write custom trace message to the trace log from a custom server control

In your server control's code, call one of the TraceContext methods using the Context property.
Specify the optional category parameter for your trace statement. You can use this category to sort trace statements when they are displayed.
Specify the message parameter for your trace statement.
Specify the optional errorInfo parameter that contains information about any errors in the page.

The following example uses the TraceContext.Write method to write custom statements to a server control's trace log. The category is My Class, and the message is This is a simple trace statement.
```
Context.Trace.Write("My Class","This is a sample trace statement.");
[Visual Basic]
Context.Trace.Write("My Class","This is a sample trace statement.")
```

There are occasions when you want to pass statements to the Write or Warn methods only when tracing is enabled. The TraceContext object has a Boolean property, IsEnabled, that allows you to conditionally call these methods.

To write trace messages to the log only when tracing is enabled

Create an If statement that checks whether tracing is enabled for the page or application to which your code belongs, then a conditional statement to be executed when the Trace.IsEnabled property returns true.

The following example confirms that tracing is enabled for a page, then uses the Write method to write a selected number of books from a database to the Trace Information table.
```
If (Trace.IsEnabled) {
    For (int i=0; i<ds.Tables["Books"].Rows.Count; i++) {
         Trace.Write("Prod",ds.Tables["Books"].Rows[i][0].ToString());
    }
}
[Visual Basic]
If Trace.IsEnabled Then
    For i=0 To ds.Tables("Books").Rows.Count-1
        Trace.Write("Prod",ds.Tables("Books").Rows(i)(0).ToString())
    Next
End If
```

Writing Trace Messages

See Also

Additional resources