pages 元素（ASP.NET 设置架构）

  • 项目

[本文档仅供预览，在以后的发行版中可能会发生更改。包含的空白主题用作占位符。]

全局定义页特定配置设置，如配置文件范围内的页和控件的 ASP.NET 指令。

<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>

特性和元素

以下几节描述了特性、子元素和父元素。

特性

特性

说明

asyncTimeout

可选的 TimeSpan 特性。

指定在异步处理过程中等待异步处理程序完成的时间（以秒为单位）。

此特性是 .NET Framework 2.0 版中的新特性。

默认值为 "0:00:45"（45 秒）。

autoEventWireup

可选的 Boolean 特性。

指定是否自动启用页事件。 当出现自动事件连接时就是如此，这意味着系统将自动连接特定签名的方法（如 Page_Load）。 有关更多信息，请参见 ASP.NET Server Control Event Model。

默认值为 True。

buffer

可选的 Boolean 特性。

指定 URL 资源是否使用响应缓冲。

默认值为 True。

clientIDMode

指定用于生成控件 ClientID 值的算法。 默认值为 Predictable。 控件的默认值为 Inherit。 因此，页面中控件的默认算法由页面的 ClientIDMode 设置决定。 可以在页的 @ Page 指令或用户控件的 @ Control 指令中设置不同的默认值。 有关算法的更多信息，请参见 ClientIDMode 和 ASP.NET Control Identification。

compilationMode

可选的 CompilationMode 特性。

指定是否应当在运行时编译 ASP.NET 页或控件。

compilationMode 特性是 .NET Framework 2.0 中新引入的特性。 此特性可以为下列可能值之一。 默认值为 Always。

值说明
Always 应始终编译页面。
Auto 如果可能，ASP.NET 将不编译页面。
Never 在任何情况下都不应动态编译页面或控件。如果某页包含需要编译的脚本块或代码构造，ASP.NET 将因为出错而返回，并且该页将不会运行。

controlRenderingCompatibilityVersion

指定控件应以 ASP.NET 的早期版本中的呈现方式，还是以专用于当前版本中的呈现方式呈现 HTML。

NoteNote
controlRenderingCompatibilityVersion 是 ASP.NET 4 中新增的属性。将其设置为当前版本号与不对其进行设置的效果相同。在任意一种情况下，控件均呈现专为当前版本设计的 HTML。可以为此特性设置的最早版本是 3.5 版。

有关更多信息，请参见 PagesSection.ControlRenderingCompatibilityVersion 和 Control.RenderingCompatibility 属性。

enableEventValidation

指定页和控件是否验证回发和回调事件。 默认值为 True。

enableSessionState

可选的 String 特性。

为配置文件范围内的资源指定会话状态要求。

enableSessionState 特性可以为下列可能值之一。 默认值为 True。

值说明
False 指示会话状态已禁用。
ReadOnly 表明会话状态不可写。
True 指示会话状态已启用。

enableViewState

可选的 Boolean 特性。

指定视图状态是否启用并在多个页请求之间保持。

默认值为 True。

enableViewStateMac

可选的 Boolean 特性。

指定从客户端回发页时，ASP.NET 是否应该对页的视图状态运行消息身份验证代码 (MAC)。 如果为 True，将检查加密的视图状态，以验证视图状态是否已在客户端被篡改。

默认值为 True。

maintainScrollPositionOnPostBack

可选的 Boolean 特性。

指定在页回发到服务器上时，是否将用户返回到客户端浏览器中的同一位置。 如果为 False，则用户将在页回发时返回到页首。

此特性是 .NET Framework 2.0 中的新特性。

默认值为 False。

masterPageFile

可选的 String 特性。

指定母版页相对于本地配置文件的路径。 masterPageFile 特性设置为 True 的页必须包含一个 Content 控件作为顶级控件。

此特性是 .NET Framework 2.0 中的新特性。

默认值为空字符串 ("")。

maxPageStateFieldLength

可选的 Int32 特性。

指定页的状态字段的最大字符长度。 如果将它设置为正数，则发送到客户端浏览器的视图状态字段将分成几块，每块都小于 maxPageStateFieldLength 特性中指定的大小。 如果将它设置为负数，则视图状态字段不应分成几块。

此特性是 .NET Framework 2.0 中的新特性。

默认值为 "-1"。

pageBaseType

可选的 String 特性。

仅当页独立时指定要使用的基础。 它由独立文件中的 inherits 特性重写。

默认值是“System.Web.UI.Page”。

pageParserFilterType

可选的 String 特性。

指定筛选器的类型名称，ASP.NET 分析器使用该筛选器来确定分析时页中是否允许某项。 该筛选器必须从 PageParserFilter 类派生。

此特性是 .NET Framework 2.0 中的新特性。

默认值为空字符串 ("")。

renderAllHiddenFieldsAtTopOfForm

可选的 Boolean 特性。

指定所有系统生成的隐藏字段是否呈现在窗体的顶部。

此特性是 .NET Framework 3.5 中的新特性。

默认值为 True。

smartNavigation

可选的 Boolean 特性。

指定是否启用智能导航。 智能导航需要 Microsoft Internet Explorer 5.5 版或更高版本。 启用智能导航时，用户会体验到下列好处：

  • 消除了导航时出现的闪烁现象。

  • 滚动位置在不同页之间保持。

  • 元素焦点在不同页之间保持。

  • 浏览器的历史记录中只保留页的最近一次状态。

此特性是 .NET Framework 2.0 中新引入的特性，但现已弃用，改用 maintainScrollPositionOnPostBack 特性。

默认值为 False。

styleSheetTheme

可选的 String 特性。

指定在控件声明之前用于应用主题的“已命名主题”文件夹的名称，这与控件声明之后定义要应用主题的主题特性形成对比。

此特性是 .NET Framework 2.0 中的新特性。

默认值为空字符串 ("")。

theme

可选的 String 特性。

指定用于配置文件范围内的页的主题名称。 所指定的主题必须作为应用程序或全局主题存在。 如果该主题不存在，将会引发 HttpException 异常。

此特性是 .NET Framework 2.0 中的新特性。

默认值为空字符串 ("")。

userControlBaseType

可选的 String 特性。

仅当页独立时指定要使用的基础。

默认值为“System.Web.UI.UserControl”。

validateRequest

可选的 Boolean 特性。

指示 ASP.NET 在从浏览器输入的所有内容中检查是否存在潜在的危险数据。 如果是 True，则通过将所有输入数据与一个潜在危险值列表进行比较来执行请求验证。 如果发生匹配，ASP.NET 将引发 HttpRequestValidationException 异常。

默认值为 True。

viewStateEncryptionMode

可选的 ViewStateEncryptionMode 特性。

指定视图状态的加密模式。 ViewStateEncryptionMode 属性重写配置文件中设置的此特性。

此特性可以为下列可能值之一。

值说明
Always 视图状态始终加密。
Auto 视图状态根据控件的请求而加密。
Never 视图状态从不加密，即使控件请求加密时也是如此。

此特性是 .NET Framework 2.0 中的新特性。

默认值为 Auto。

子元素

元素

说明

controls

定义标记前缀所在的 register 指令和命名空间的集合。

namespaces

定义一个将在程序集预编译期间使用的导入指令的集合。

tagMapping

定义一个标记类型的集合，这些标记类型在编译时重新映射为其他标记类型。

ignoreDeviceFilters

定义浏览器必须忽略页面呈现的设备元素的集合。 有关更多信息，请参见 IgnoreDeviceFilters。

父元素

元素

说明

configuration

公共语言运行时和基于 .NET Framework 的应用程序所使用的每个配置文件中均需要的根元素。

system.web

指定配置文件中 ASP.NET 配置设置的根元素，并包含用于配置 ASP.NET Web 应用程序和控制应用程序行为方式的配置元素。

备注

pages 元素定义页特定的配置设置。 此配置节支持如下操作：在全局范围内为配置文件范围内的所有页和控件设置某些 ASP.NET 页和控件指令。 这包括以下页级别的指令，这些指令所指定的设置由页和用户控件编译器在处理 ASP.NET Web 窗体页 (.aspx) 和用户控件 (.ascx) 文件时使用：

pages 元素还为以下操作提供支持：在运行时通过 tagMapping 元素将标记类型映射到其他标记类型。

备注

将 @ Page 指令添加到母版页时不能在依赖于母版页的页中使用相同的指令声明。而应该使用 pages 配置元素来全局定义页指令。

默认配置

下面的默认 pages 元素不是在 Machine.config 文件或根 Web.config 文件中显式配置的。 但是，它是由应用程序返回的默认配置。 命名空间和控件是在根 Web.config 文件中添加的。

<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>

示例

下面的代码示例演示如何指定多个页配置设置。

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

元素信息

配置节处理程序

PagesSection

配置成员

Pages

Page

可配置的位置

Machine.config

根级别的 Web.config

应用程序级别的 Web.config

虚拟或物理目录级别的 Web.config

要求

Microsoft Internet 信息服务 (IIS) 版本 5.0 或更高版本

.NET Framework 版本 1.0 或 更高版本

Microsoft Visual Studio 2003 或更高版本

请参见

任务

How to: Configure Specific Folders Using Location Settings

How to: Lock ASP.NET Configuration Settings

参考

configuration 元素（常规设置架构）

pages 的 controls 元素（ASP.NET 设置架构）

pages 的 namespaces 元素（ASP.NET 设置架构）

pages 的 tagMapping 元素（ASP.NET 设置架构）

system.web 元素（ASP.NET 设置架构）

@ Page

System.Configuration

System.Web.Configuration

Page

PagesSection

概念

ASP.NET Configuration File Hierarchy

Securing Configuration

其他资源

常规配置设置 (ASP.NET)

ASP.NET 配置设置

Configuring ASP.NET Applications

ASP.NET Configuration API