Module 5: Using Trace in ASP.NET Pages

They will also add custom trace messages to an ASP.NET page and a middle-tier component.. Overview of Tracing Start the module with an overview of tracing and why do we need to enable tr

Contents

Overview 1

Lab 5: Adding Trace to an ASP.NET Page 14

Review 15

Module 5: Using Trace

in ASP.NET Pages

BETA MATERIALS FOR MICROSOFT CERTIFIED TRAINER PREPARATION PURPOSES ONLY

to represent any real individual, company, product, or event, unless otherwise noted Complying with all applicable copyright laws is the responsibility of the user No part of this document may

be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation If, however, your only means of access is electronic, permission to print one copy is hereby granted

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property

 2001 Microsoft Corporation All rights reserved

Microsoft, BackOffice, MS-DOS, Windows, Windows NT, <plus other appropriate product

names or titles The publications specialist replaces this example list with the list of trademarks provided by the copy editor Microsoft is listed first, followed by all other Microsoft trademarks

in alphabetical order > are either registered trademarks or trademarks of Microsoft Corporation

in the U.S.A and/or other countries

<The publications specialist inserts mention of specific, contractually obligated to, third-party trademarks, provided by the copy editor>

Other product and company names mentioned herein may be the trademarks of their respective owners

Instructor Notes

This module describes the trace feature of ASP.NET Students will learn about the two tracing techniques in ASP.NET, page-level tracing and application-level tracing

In the lab, students will enable and disable tracing for an ASP.NET page They will also add custom trace messages to an ASP.NET page and a middle-tier component

After completing this module, students will be able to:

Describe page-level and application-level tracing

Enable and disable tracing for an ASP.NET page

Add custom trace information

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach this module

Required Materials

To teach this module, you need the following materials:

! Microsoft® PowerPoint® file 2063A_05.ppt

! Module 5, “Using Trace in ASP.NET Pages” (2063A_05.doc)

! Lab, “Adding trace to an ASP.NET Page” (2063A_L05.doc)

Preparation Tasks

To prepare for this module, you should:

! Read all of the materials for this module

! Complete all the demonstrations

! Complete the lab

Presentation:

60 Minutes

Lab:

30 Minutes

BETA MATERIALS FOR MICROSOFT CERTIFIED TRAINER PREPARATION PURPOSES ONLY

Module Strategy

Use the following strategy to present this module:

! Overview of Tracing Start the module with an overview of tracing and why do we need to enable trace on an application page

! Trace Information This section described the type of information that can be retrieved by enabling trace on a page When teaching this, point to each category in the illustration and discuss it briefly

! Page-Level Trace Page-level Tracing provides the ability to write debugging statements directly to the output of a page, and conditionally execute debugging code when tracing is enabled This section describes how page-level tracing works This section ends with a topic on how to trace into a component When talking about tracing into a component, tell them about why it is useful to be able to trace into a component

! Application-Level Trace ASP.NET also provides a way to enable tracing for the entire application and not just a single page This section describes how application-level trace works

Overview

! Overview of Tracing

! Trace Information

! Page-Level Trace

! Application-Level Trace

In earlier versions of ASP, tracing of code was accomplished by inserting

Response.Write statements, wherever required One main drawback of this

technique was the removal of the excess code added when the application is

deployed, and thus the inability to use the output from the Response.Write

statements in a production environment ASP.NET overcomes such drawbacks

by introducing an automatic tracing mechanism This tracing mechanism can be enabled and disabled either on a page-by-page basis, or for an entire

application, and can be configured in the config.web file

After completing this module, you will be able to:

! Describe page-level and application-level tracing

! Enable and disable tracing for an ASP.NET page

! Add custom trace information

<<add something on Debug object and conditional compilation Trace is good because you can turn it on from config.web in a production environment to see what's going wrong It can also output to a log file in a production

environment>>

Topic Objective

To provide an overview of

the module topics and

objectives

Lead-in

In this module, you will learn

how to use the trace feature

of ASP.NET

BETA MATERIALS FOR MICROSOFT CERTIFIED TRAINER PREPARATION PURPOSES ONLY

Overview of Tracing

! With Tracing You Can:

# Output Variables or Structures

# Assert Whether a Condition is Met

# Trace through the Execution Path of the Application

! Can Be Enabled and Disabled, Either on a Page-By-Page Basis, or for an Entire Application

The tracing feature enables you to insert debugging print statements into your code to output variables or structures, assert whether a condition is met, or just generally trace through the execution path of the application

All this information is outputted with a page or saved to a log

Topic Objective

To describe tracing

Lead-in

Tracing enables you to see

the execution path and

output variable values from

your application

Trace Information

Tracing provides a lot of information to the developer of an ASP.NET application The trace output screen contains the following categories of information

Category Description

of request, and the status

Topic Objective

To list the information

provided in a trace output

Lead-in

The trace output page

provides lots of information

BETA MATERIALS FOR MICROSOFT CERTIFIED TRAINER PREPARATION PURPOSES ONLY

$ Page-Level Trace

! How Does Page-Level Trace Work?

! Demonstration: Adding Page-Level Trace Statements

! Tracing into a Component

Page-level tracing provides the ability to write debugging statements directly to the output of a page, and conditionally execute debugging code when tracing is enabled The performance data and the developer-specified messages (if any) are injected into the HTML output stream to the client to help clarify precisely what occurs when the framework processes a page request

In this section, you will learn how page-level tracing works

Topic Objective

To describe how page-level

tracing works

Lead-in

ASP.NET aids the

debugging and testing

process by providing two

types of trace capabilities,

page-level and

application-level

How Does Page-Level Trace Work?

! Enabling Tracing for a Page

! Inserting Trace Messages

! Sort Output by Category

<%@ Page Language="VB" Trace="true"%>

Trace.Write("category", "message")

<%@ Page Language="VB" Trace="true"

TraceMode="SortByCategory"%>

<%@ Page Language="VB" Trace="true"

TraceMode="SortByCategory"%>

The page-level trace mechanism performs two functions when it is enabled:

! It automatically appends a table of performance data to the end of the page

! It allows developers to insert custom diagnostic messages throughout their code

Let’s look at how a page-level trace works

Enabling Tracing for a Page

The trace capability must be enabled prior to use To enable tracing for a page, include the following directive at the top of the page code

<%@ Page Language="VB" Trace="true" %>

The page exposes the Trace property of the type TraceContext, which can be

used to output debugging statements to the page output The default value of the

Trace attribute is set to false

Inserting and Organizing Trace Messages

You can use the Trace object to write debugging statements There are two methods you can use to insert custom messages: Trace.Write and

Trace.Warn Trace.Write is used to display messages, and Trace.Warn is used to display warnings Trace.Write and Trace.Warn are easy to distinguish because Trace.Warn uses a red font color in its output

In their simplest forms, each method takes two string arguments:

public void Write( string category, string message ) public void Warn( string category, string message )

Topic Objective

To explain how page-level

tracing works

Lead-in

Let’s look at how page-level

trace works

BETA MATERIALS FOR MICROSOFT CERTIFIED TRAINER PREPARATION PURPOSES ONLY

The category argument is used to organize messages For example:

Trace.Write("Custom Trace","Beginning User Code ") Trace.Warn("Custom Trace","Array count is null!") Often you will need to execute additional code to construct the statements to

pass to the Trace.Write or Trace.Warn methods, where the code should only

execute if tracing is enabled for the page To support this, the page exposes a

boolean property, Trace.IsEnabled, that returns TRUE only if tracing is enabled for the page You should check Trace.IsEnabled first to guarantee

your debugging code will only execute when tracing is enabled

If Trace.IsEnabled strTrace = "create a trace string here"

End If Trace.Write(strTrace)

Sorting Trace Messages

The TraceContext class contains the TraceMode property that defines how

trace messages are sorted in the page output

<%@ Page Trace="true" TraceMode="SortByCategory" %>

TraceMode is of the type TraceModeEnum, and has two possible values:

! SortByTime Trace messages are outputted in order of chronological occurrence This is the default setting

! SortByCategory Trace messages are sorted alphabetically by the category argument to the

Trace.Write and Trace.Warn methods

Demonstration: Adding Page-Level Trace Statements

In this demonstration, you will see how to use trace at the page level

Topic Objective

To demonstrate page-level

and application-level tracing

Lead-in

In this demonstration, you

will see how to use tracing

at the page level

Delivery Tip

1 Open the file

storedprocedure.aspx in

2063\DemoCode\Mod05

2 Enable tracing by adding

"Trace=True" to the page

directive

3 View in Microsoft Internet

Explorer

4 Add a custom trace

message to the Page_Load

event

5 View again

6 Open the page add.aspx

and enable tracing This

page uses a user control

named numberbox.aspx

7 Add some trace

messages to both add.aspx

and numberbox.aspx

8 View add.aspx in Internet

Explorer

BETA MATERIALS FOR MICROSOFT CERTIFIED TRAINER PREPARATION PURPOSES ONLY

Tracing into a Component

! Import the System.Web Library

! Enable Tracing in Class Constructor

! Add Trace Statements to Method

Imports System.Web

HttpContext.Current.Trace.IsEnabled = True

HttpContext.Current.Trace.Write _ ("component", "this is my trace statement")

HttpContext.Current.Trace.Write _ ("component", "this is my trace statement")

If you have a component that is called from an ASP.NET page, you can also add trace statements to the component

! To add trace to a component

1 At the top of the component, import the System.Web library

Imports System.Web

2 In the constructor of the class where you want to add trace statements, enable tracing with the following statement:

HttpContext.Current.Trace.IsEnabled = True

3 Then, in the method, use the following:

HttpContext.Current.Trace.Write _ ("component", "this is my trace statement")

Topic Objective

To show how to trace into a

component

Lead-in

If you have a component

that is called from an

ASP.NET page, you can

add trace statements to the

methods of the component

too

$ Application-Level Trace

! How Does Application-Level Trace Work?

! Demonstration: Adding Application-Level Trace Statements

ASP.NET also provides a way to enable tracing for the entire application and not just a single page An ASP.NET application is the collection of files and folders in a virtual root of IIS

In this section, you will learn how an application-level trace works

Topic Objective

To introduce the topics in

this section

Lead-in

In this section, you will learn

about application-level

trace

BETA MATERIALS FOR MICROSOFT CERTIFIED TRAINER PREPARATION PURPOSES ONLY

How Does Application-Level Trace Work?

! Application-Level Trace Collects Additional Statistics from a Request in the trace.axd File

! Enabling Application-Level Trace in config.web

<configuration>

<trace enabled="true"

tracemode="SortByCategory"

requestlimit="40"

pageoutput="true"/>

</configuration>

<configuration>

<trace enabled="true"

tracemode="SortByCategory"

requestlimit="40"

pageoutput="true"/>

</configuration>

In addition to the page-level trace functionality, ASP.NET provides a way to enable trace output for an entire application Enabling trace at the application level has the effect of enabling page-level trace for every page within that application, provided there is no page-level directive to explicitly disable trace When application-level tracing is enabled, the ASP.NET runtime also collects several additional statistics, such as the state of the control hierarchy, the contents of session and application state, the form and query string input values, and so on These statistics are collected for a specified number of requests as determined by the application's configuration file

Enabling Tracing

With ASP.NET there is a configuration file that you can use to configure certain application attributes This file is named config.web and is located in the root folder of the application You will learn more about the config.web file in Module 7: Creating an ASP.NET Web Application

To enable tracing for an application, place the following code in the config.web file in the application's root folder:

<configuration>

<trace enabled="true"/>

</configuration>

Using the above configuration, each page in the application will output page-level trace statements to the client browser To access the additional page

statistics, view the page trace.axd in the application's root folder For example,

if the URL to your application were http://localhost/myapplication, you would view the file http://localhost/myapplication/trace.axd to access the trace statistics for that application

Topic Objective

To explain how

application-level trace works

Lead-in

In addition to exposing a

generalized trace facility to

developers, the ASP.NET

runtime can also collect

helpful request information

globally for an application

Collecting this additional

data must be explicitly

enabled for the application

through the configuration

system