Setting Trace Messages

The TraceContext class has a fairly simple interface, with only one constructor, two properties, and two methods. Of course, these are in addition to the standard properties and methods inherited from the Object class. An instance of the TraceContext class is available to your ASP.NET pages through the Trace property of the Page object, so you will need the constructor only if you want to enable tracing in your .NET components (discussed later in this chapter).

TraceContext Properties

The IsEnabled property works the same way as the Trace attribute of the @Page directive. The nice part about having this property available to you is that, unlike the @Page directive, it can be dynamically assigned. For instance, you can specify tracing through a Querystring parameter, as shown in Listings 6.2 and 6.3.

Listing 6.2. Setting the IsEnabled Property Dynamically (C#)

<%@ Page Language="C#" %> 

<script language="C#" runat="server"> 
      protected void Page_Load(object Sender, EventArgs e) 
      {
            bool traceFlag = Request.QueryString["trace"] != null 
                  ? true : false; 
            Trace.IsEnabled = traceFlag; 
     } 
</script> 

Listing 6.3. Setting the IsEnabled Property Dynamically (Visual Basic .NET)

<%@ Page Language="Visual Basic" %> 

<script language="Visual Basic" runat="server"> 
      Protected Sub Page_Load(Sender As Object, e As EventArgs) 
            Dim traceFlag As Boolean = IIF(Request.QueryString("trace") _ 
                  <> Nothing, True, False) 
            Trace.IsEnabled = traceFlag 
      End Sub 
</script> 

These listings set the IsEnabled property of the Trace object dynamically, based on the presence of the trace Querystring variable. Notice that no Trace attribute is assigned to the @Page directive. It is interesting to note that even if you specify a Trace attribute and set it to false, the IsEnabled property value still dictates whether trace information was displayed to the page.

The real power of using the IsEnabled property is that when you set it to false, the trace information not only isn’t displayed, but it also isn’t even compiled. This means that you can leave your tracing code in your ASP.NET application when you move it to production. As long as the IsEnabled property is set to false, you will not suffer any performance penalty.

The TraceMode property works exactly like the TraceMode attribute of the @Page directive. The same behaviors and advantages that apply to the IsEnabled property also exist for the TraceMode property.

TraceContext Methods

Only one thing (besides their names) differentiates the two methods of the TraceContext class, Write and Warn: The output generated by the Write method is black, while the output generated by the Warn method is red. For this reason, we will be discussing only the Write method. Just realize that everything said about the Write method can also be applied to the Warn method. There are three overloaded versions of the Write and Warn methods. The first version accepts a trace message. The second version accepts a trace message and a category. The third version accepts a trace message, a category, and an instance of an Exception class. Each of these is covered in more detail next.

TraceContext.Write (string)

The first of the overloaded Write methods of the TraceContext class accepts a single-string parameter. This string contains the message that is displayed in the Message field of the Trace Information section of the trace output (as seen in Figure 6.2). Listings 6.4 and 6.5 demonstrate its use.

Listing 6.4. Implementing TraceContext.Write (string) (C#)

<%@ Page Language="C#" Trace="true" %> 

<script language="C#" runat="server"> 
      protected void Page_Load(object Sender, EventArgs e) 
      {
            Trace.Write("I'm tracing now"); 
      } 
</script> 

Listing 6.5. Implementing TraceContext.Write (string) (Visual Basic .NET)

<%@ Page Language="Visual Basic" Trace="true" %> 

<script language="Visual Basic" runat="server"> 
      Protected Sub Page_Load(Sender As Object, e As EventArgs) 
            Trace.Write("I'm tracing now") 
      End Sub 
</script> 

Figure 6.9 shows what the trace output for the previous code looks like.

Notice the message “I’m tracing now” that appears as the third line item in the Trace Information section. No category was specified, so it is blank. The next overloaded version of the Write/Warn method includes the category parameter.

TraceContext.Write (string, string)

The second overloaded Write method of the TraceContext class takes two string parameters. The first parameter is the category of the trace item. It appears in the Category field of the Trace Information section of the trace output. The second parameter is the message that will be displayed in the Message field, and it is the same as the single-string parameter in the first overloaded Write method.

This is probably the most likely version of the Write method that you will use when debugging your ASP.NET pages.You can assign categories to your trace items, leveraging the TraceMode attribute of the @Page directive or the TraceMode property of the TraceContext class to sort the Trace Information section results. As previously described, this is done using the SortByCategory member of the TraceMode enumeration.

Listings 6.6 and 6.7 demonstrate the use of this version of the Write method.

Listing 6.6. Implementing TraceContext.Write (string, string) (C#)

<%@ Page Language="C#" Trace="true" %> 

<script language="C#" runat="server"> 
      protected void Page_Load(object Sender, EventArgs e) 
      {
            Trace. TraceMode = TraceMode.SortByCategory; 
            Trace.Write("Category 1", "Category 1 data"); 
            Trace.Write("Category 2", "Category 2 data"); 
            Trace.Write("Category 1", "More Category 1 data"); 
      } 
</script> 

Listing 6.7. Implementing TraceContext.Write (string, string) (Visual Basic .NET)

<%@ Page Language="Visual Basic" Trace="true" %> 

<script language="Visual Basic" runat="server"> 
      Protected Sub Page_Load(Sender As Object, e As EventArgs) 
            Trace. TraceMode = TraceMode.SortByCategory 
            Trace.Write("Category 1", "Category 1 data") 
            Trace.Write("Category 2", "Category 2 data") 
            Trace.Write("Category 1", "More Category 1 data") 
      End Sub 
</script> 

Figure 6.10 shows the trace output for the previous code.

Notice that the trace items are sorted by category so that both of the category 1 items appear together, instead of being separated by the category 2 item (which was the order in which the code made the calls to the Write method). Also, the previous code uses the TraceMode property of the Trace object to set the sort order.You could alternatively have used the TraceMode attribute of the @Page directive.

TraceContext.Write (string, string, Exception)

The third overloaded version of the Write method takes three parameters. The first two parameters match up with the two parameters of the previous overloaded method call. For the third parameter, you should pass in an object instance of the Exception class or an object instance of a class that inherits from the Exception class.You would most likely use this method call when writing trace output in conjunction with structured exception handling. Listings 6.8 and 6.9 demonstrate this concept by intentionally causing an exception in a Try block that adds to the trace information in the Catch block.

Listing 6.8. Implementing TraceContext.Write (string, string, Exception) (C#)

<%@ Page Language="C#" Trace="true" %> 

<script language="C#" runat="server"> 
      protected void Page_Load(object Sender, EventArgs e) 
      {
            int x = 1; 
            int y = 0; 

            try 
            {
                  int z = x / y; 
            } 
            catch(DivideByZeroException ex) 
	    {
                 Trace.Write("Errors", "Testing the limits of infinity?",ex); 
            } 
      } 
</script> 

Listing 6.9. Implementing TraceContext.Write (string, string, Exception) (Visual Basic .NET)

<%@ Page Language="Visual Basic" Trace="true" %> 

<script language="Visual Basic" runat="server"> 
      Protected Sub Page_Load(Sender As Object, e As EventArgs) 
            Dim x As Integer = 1 
            Dim y As Integer = 0 

            Try 
                  Dim z As Integer = x / y 
            Catch ex As OverflowException 
                  Trace.Write("Errors", "Testing the limits of infinity?",ex) 
            End Try 
      End Sub 
</script> 

Figure 6.11 shows the trace output for the C# version of this code.

In addition to the message that you specify in the call to the Write method, you get the message from the exception that was thrown, as well as the name of the procedure where the exception occurred.You can see valuable debugging information associated with the error that was thrown alongside your own custom comments, making it easier to combine the two into a solution to the bug.