trace Element (ASP.NET Settings Schema)

Article
04/30/2007

Configures the ASP.NET code tracing service that controls how trace results are gathered, stored, and displayed.

<trace 
   enabled="true|false"
   localOnly="true|false"
   pageOutput="true|false"
   requestLimit="integer" 
   mostRecent="true|false"
   writeToDiagnosticsTrace="true|false"
   traceMode="SortByTime|SortByCategory"
/>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

enabled

Optional Boolean attribute.

Specifies whether tracing is enabled for an application. Tracing must be enabled in order to use the Trace.axd viewer. By default, the Trace.axd viewer is added to the httpHandlers element.

The default is false.

localOnly

Optional Boolean attribute.

Specifies whether the trace viewer (Trace.axd) is available only on the host Web server. If false, the trace viewer is available from any computer. By default, the Trace.axd viewer is added to the httpHandlers element.

The default is true.

mostRecent

Optional Boolean attribute.

Specifies whether the most recent application-level tracing output is displayed and older trace data beyond the limits that are indicated by the requestLimit is discarded. If false, trace data is displayed for requests until the requestLimit attribute is reached.

This attribute is new in the .NET Framework version 2.0.

The default is false.

pageOutput

Optional Boolean attribute.

Specifies whether trace output is rendered at the end of each page. If false, trace output is accessible through the trace utility only.

The default is false.

requestLimit

Optional Int32 attribute.

Specifies the number of trace requests to store on the server. If the limit is reached and the mostRecent attribute is false, trace is automatically disabled.

The maximum request limit is 10,000. If a value that is greater than 10,000 is specified, it is silently rounded down to 10,000 by ASP.NET.

The default is 10.

traceMode

Optional TraceDisplayMode attribute.

Specifies the order in which to display trace information.

The traceMode attribute can be one of the following possible values.

Value	Description
SortByCategory	Specifies that trace information is displayed in the order that the trace information is processed.
SortByTime	Specifies that trace information is displayed alphabetically by user-defined category.

The default is SortByTime.

writeToDiagnosticsTrace

Optional Boolean attribute.

Specifies whether ASP.NET Trace messages are forwarded to the System.Diagnostics tracing infrastructure, for any listeners that are registered to display Trace messages. For more information, see the trace element of system.diagnostics.

This attribute is new in the .NET Framework version 2.0.

The default value is false.

Child Elements

None.

Parent Elements

Element	Description
configuration	The required root element in every configuration file that is used by the common language runtime and the .NET Framework applications.
system.web	Specifies the root element for the ASP.NET configuration settings in a configuration file and contains configuration elements that configure ASP.NET Web applications and control how the applications behave.

Remarks

The trace element configures the ASP.NET code tracing service that controls how trace results are gathered, stored, and displayed.

When tracing is enabled, each page request generates trace messages that can be appended to the page output or stored in an application trace log. You can use the ASP.NET trace viewer (Trace.axd) to view the contents of the trace log. By default, Trace.axd is added to the httpHandlers element.

Note

Generally, you should not enable tracing in an active Web site, because this can display sensitive configuration information to anyone who views pages in the Web site. Tracing is intended for debugging purposes only. If the localOnly attribute is true, trace information is displayed only for localhost requests. Additionally, if <deployment retail=true> is set in the Web.config file, tracing is disabled.

You can use the properties and methods in the Trace class to instrument release builds. Instrumentation allows you to monitor the health of your application by running the application in real-life settings. Tracing helps you isolate issues and fix the issues without disrupting a running system.

In order for the trace to take effect, you need to recompile your application with the trace flag set. You do that by setting the compilerOptions attribute to ="/d:TRACE" in the configuration line for the language compiler you want to support tracing. Refer to <compiler> Element

Default Configuration

The following default trace element is not explicitly configured in the Machine.config file or in the root Web.config file. However, it is the default configuration that is returned by application in the .NET Framework 2.0.

<trace 
   enabled="false" 
   localOnly="true" 
   mostRecent="false" 
   pageOutput="false" 
   requestLimit="10" 
   traceMode="SortByTime" 
   writeToDiagnosticsTrace="false" 
/>

The following default element element is configured in the Machine.config file in the .NET Framework versions 1.0 and 1.1.

<trace
   enabled="false"
   localOnly="true"
   pageOutput="false"
   requestLimit="10"
   traceMode="SortByTime"
/>

Example

The following code example demonstrates how to specify tracing configuration settings.

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

Element Information

Configuration section handler	TraceSection
Configuration member	TraceSection
Configurable locations	Machine.config Root-level Web.config Application-level Web.config Virtual or physical directory–level Web.config
Requirements	Microsoft Internet Information Services (IIS) 5.0, 5.1, or 6.0 The .NET Framework version 1.0, 1.1, or 2.0 Microsoft Visual Studio 2003 or Visual Studio 2005

Partager via

trace Element (ASP.NET Settings Schema)

Attributes and Elements

Attributes

Child Elements

Parent Elements

Remarks

Default Configuration

Example

Element Information

See Also

Tasks

Reference

Concepts

Other Resources

Ressources supplémentaires