pages Element (ASP.NET Settings Schema)

  • Article

Globally defines page-specific configuration settings, such as ASP.NET directives for pages and controls that are within the scope of the configuration file.

configuration Element (General Settings Schema)
  system.web Element (ASP.NET Settings Schema)
    pages Element (ASP.NET Settings Schema)

<pages     
   asyncTimeout="number"
   autoEventWireup="[True|False]"
   buffer="[True|False]"
   clientIDMode="[AutoID|Predictable|Static]"
   compilationMode="[Always|Auto|Never]" 
   controlRenderingCompatibilityVersion="[3.5|4.0]"
   enableEventValidation="[True|False]"
   enableSessionState="[True|False|ReadOnly]"
   enableViewState="[True|False]"
   enableViewStateMac="[True|False]"
   maintainScrollPositionOnPostBack="[True|False]" 
   masterPageFile="file path" 
   maxPageStateFieldLength="number" 
   pageBaseType="typename, assembly"
   pageParserFilterType="string" 
   renderAllHiddenFieldsAtTopOfForm="[True|False]"
   smartNavigation="[True|False]"
   styleSheetTheme="string"
   theme="string"
   userControlBaseType="typename"
   validateRequest="[True|False]"
   viewStateEncryptionMode="[Always|Auto|Never]" 
>
   <controls>...</controls>
   <namespaces>...</namespaces>
   <tagMapping>...</tagMapping>
   <ignoreDeviceFilters>...</ignoreDeviceFilters>
</pages>

Attributes and Elements

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

Attributes

Attribute

Description

asyncTimeout

Optional TimeSpan attribute.

Specifies the number of seconds to wait for an asynchronous handler to complete during asynchronous processing.

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

The default is "0:00:45" (45 seconds).

autoEventWireup

Optional Boolean attribute.

Specifies whether page events are automatically enabled. This is if the auto-event wireup occurs, which means that the system will automatically attach the methods of a particular signature (Page_Load for example). For more information, see ASP.NET Web Server Control Event Model.

The default is True.

buffer

Optional Boolean attribute.

Specifies whether the URL resource uses response buffering.

The default is True.

clientIDMode

Specifies the algorithm to use to generate ClientID values for controls. The default value is Predictable. The default value for controls is Inherit. Therefore, the default algorithm for controls in a page is determined by the ClientIDMode setting of the page. A different default value can be set in the @ Page directive of the page or in the @ Control directive of a user control. For more information about the algorithms, see ClientIDMode and ASP.NET Web Server Control Identification.

compilationMode

Optional CompilationMode attribute.

Specifies whether an ASP.NET page or control should be compiled at run time.

The compilationMode attribute is new in the .NET Framework 2.0. This attribute can be one of the following possible values. The default is Always.

ValueDescription
Always The page should always be compiled.
Auto ASP.NET will not compile the page, if possible.
Never The page or control should never be dynamically compiled. If a page contains a script block or code construct that requires compilation, ASP.NET will return with an error and the page will not run.

controlRenderingCompatibilityVersion

Specifies whether controls should render HTML the way they do in an earlier version of ASP.NET or the way they are designed to do in the current version.

Note

The controlRenderingCompatibilityVersion is new in ASP.NET 4. Setting it to the current version number has the same effect as not setting it. In either case, controls render HTML as designed for the current version. The earliest version that this attribute can be set to is 3.5.

For more information, see the PagesSection.ControlRenderingCompatibilityVersion and Control.RenderingCompatibility properties.

enableEventValidation

Specifies whether pages and controls validate postback and callback events. The default is True.

enableSessionState

Optional String attribute.

Specifies session state requirements for the resources that are within the scope of the configuration file.

The enableSessionState attribute can be one of the following possible values. The default is True.

ValueDescription
False Indicates that session state is disabled.
ReadOnly Indicates that session state is not writable.
True Indicates that session state is enabled.

enableViewState

Optional Boolean attribute.

Specifies whether view state is enabled and maintained across page requests.

The default is True.

enableViewStateMac

Optional Boolean attribute.

Specifies whether ASP.NET should run a message authentication code (MAC) on the view state for the page when the page is posted back from the client. If True, the encrypted view state is checked to verify that it has not been tampered with on the client.

The default is True.

maintainScrollPositionOnPostBack

Optional Boolean attribute.

Specifies whether to return the user to the same position in the client browser when pages are posted back to the server. If False, the user is returned to the top of the page on a postback.

This attribute is new in the .NET Framework 2.0.

The default is False.

masterPageFile

Optional String attribute.

Specifies the master page path relative to the local configuration file. Pages that have the masterPageFile attribute set to True must contain a Content control as the top-level control

This attribute is new in the .NET Framework 2.0.

The default is an empty string ("").

maxPageStateFieldLength

Optional Int32 attribute.

Specifies the maximum length in characters for the state field for the page. If set to a positive number, the view-state field that is sent to the client browser is separated into chunks, and each chunk is less than the size that is specified in the maxPageStateFieldLength attribute. If set to a negative number, the view-state field should not be separated into chunks.

This attribute is new in the .NET Framework 2.0.

The default is "-1".

pageBaseType

Optional String attribute.

Specifies the base to use when the pages are stand-alone only. This is overridden by the inherits attribute in a stand-alone file.

The default is "System.Web.UI.Page".

pageParserFilterType

Optional String attribute.

Specifies the type name of a filter that is used by the ASP.NET parser to determine whether an item is allowed in the page at parse time. The filter must derive from the PageParserFilter class.

This attribute is new in the .NET Framework 2.0.

The default is an empty string ("").

renderAllHiddenFieldsAtTopOfForm

Optional Boolean attribute.

Specifies whether all system-generated hidden fields are rendered at the top of the form.

This attribute is new in the .NET Framework 3.5.

The default is True.

smartNavigation

Optional Boolean attribute.

Specifies whether smart navigation is enabled. Smart navigation requires Microsoft Internet Explorer version 5.5 or later. When smart navigation is enabled, the user experiences the following benefits:

  • Navigational flashing is eliminated.

  • Scroll position is persisted between pages.

  • Element focus is persisted between pages.

  • The last state for the page is the only state retained by the history on the browser.

This attribute is new in the .NET Framework 2.0, but has been deprecated in favor of the maintainScrollPositionOnPostBack attribute.

The default is False.

styleSheetTheme

Optional String attribute.

Specifies the name of the "named theme" folder to be used to apply the theme before control declarations, in contrast with the theme attribute that defines the theme to apply after the control declaration.

This attribute is new in the .NET Framework 2.0.

The default is an empty string ("").

theme

Optional String attribute.

Specifies the name of the theme that is used for the pages that are within the scope of the configuration file. The specified theme must exist as either an application or a global theme. If the theme does not exist, an HttpException exception is thrown.

This attribute is new in the .NET Framework 2.0.

The default is an empty string ("").

userControlBaseType

Optional String attribute.

Specifies the base to use when the pages are stand-alone only.

The default is "System.Web.UI.UserControl".

validateRequest

Optional Boolean attribute.

Indicates that ASP.NET examines all input from the browser for potentially dangerous data. If True, request validation is performed by comparing all input data to a list of potentially dangerous values. If a match occurs, ASP.NET raises an HttpRequestValidationException exception.

The default is True.

viewStateEncryptionMode

Optional ViewStateEncryptionMode attribute.

Specifies the encryption mode of the view state. The ViewStateEncryptionMode property overrides this attribute, which is set in the configuration file.

This attribute can be one of the following possible values.

ValueDescription
Always View state is always encrypted.
Auto View state is encrypted, if a control requests it.
Never View state is never encrypted, even if a control requests it.

This attribute is new in the .NET Framework 2.0.

The default is Auto.

Child Elements

Element

Description

controls

Defines a collection of register directives and the namespaces where the tag prefixes reside.

namespaces

Defines a collection of import directives to use during assembly precompilation.

tagMapping

Defines a collection of tag types that are remapped to other tag types at compile time.

ignoreDeviceFilters

Defines a collection of device elements that the browser must ignore the page is rendered. For more information, see IgnoreDeviceFilters.

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–based 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 pages element defines page-specific configuration settings. This configuration section supports setting certain ASP.NET page and control directives globally for all pages and controls in the scope of the configuration file. This includes the following page-level directives, which specify settings that are used by the page and user-control compilers when the compilers process ASP.NET Web Forms page (.aspx) and user control (.ascx) files:

The pages element also provides support for mapping tag types to other tag types at run time through the tagMapping element.

Note

Adding an @ Page directive to a master page does not allow you use the same directive declaration in pages that depend on the master. Instead, use the pages configuration element to globally define page directives.

Default Configuration

The following default pages 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 an application. Namespaces and controls are added in the root Web.config file.

<pages 
   buffer="true" 
   clientIDMode="AutoID" 
   enableSessionState="true" 
   enableViewState="true" 
   enableViewStateMac="true" 
   smartNavigation="false" 
   autoEventWireup="true" 
   pageBaseType="System.Web.UI.Page" 
   userControlBaseType="System.Web.UI.UserControl" 
   validateRequest="true" 
   masterPageFile="" 
   theme="" 
   styleSheetTheme="" 
   maxPageStateFieldLength="-1" 
   compilationMode="Always" 
   pageParserFilterType="" 
   viewStateEncryptionMode="Auto" 
   maintainScrollPositionOnPostBack="false" 
   asyncTimeout="45"
>
   <namespaces>
      <clear />
   </namespaces>
   <tagMapping>
      <clear />
   </tagMapping>
</pages>

Example

The following code example demonstrates how to specify several page configuration settings.

<configuration>
   <system.web>
      <pages buffer="true"
         enableSessionState="true"
         autoEventWireup="true"
         maintainScrollPositionOnPostBack="true"
         masterPageFile = "~/Masters/Page1.master" />
  </system.web>
</configuration>

Element Information

Configuration section handler

PagesSection

Configuration member

Pages

Page

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) versions 5.0 or later

The .NET Framework versions 1.0 or later

Microsoft Visual Studio 2003 or later

See Also

Tasks

How to: Configure Specific Directories Using Location Settings

How to: Lock ASP.NET Configuration Settings

Reference

configuration Element (General Settings Schema)

controls Element for pages (ASP.NET Settings Schema)

namespaces Element for pages (ASP.NET Settings Schema)

tagMapping Element for pages (ASP.NET Settings Schema)

system.web Element (ASP.NET Settings Schema)

@ Page

System.Configuration

System.Web.Configuration

Page

PagesSection

Concepts

ASP.NET Configuration File Hierarchy and Inheritance

Securing ASP.NET Configuration

Other Resources

General Configuration Settings (ASP.NET)

ASP.NET Configuration Settings

ASP.NET Web Site Administration

ASP.NET Configuration API