@ Page

  • 项目

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

定义 ASP.NET 页分析器和编译器使用的页特定（.aspx 文件）特性。

<%@ Page attribute="value" [attribute="value"...] %>

特性

  • Async
    使页成为异步处理程序（即，导致页使用 IHttpAsyncHandler 的实现来处理请求）。

    默认值为 false。

  • AsyncTimeOut
    定义在处理异步任务时使用的超时时间间隔（以秒为单位）。 默认值为 45 秒。

    该值必须是整数。

    有关更多信息，请参见 AsyncTimeout 属性。

  • AspCompat
    当设置为 true 时，允许在单线程单元 (STA) 线程上执行页。 这允许页调用 STA 组件，例如用 Microsoft Visual Basic 6.0 开发的组件。 将此特性设为 true 还允许页调用 COM+ 1.0 版组件，该组件要求可以访问非托管 Active Server Pages (ASP) 内置对象。 可以通过 ObjectContext 对象或 OnStartPage 方法访问它们。 默认值为 false。

    备注

    将此特性设置为 true 可能导致页的性能降低。有关更多信息，请参见“备注”一节。

  • AutoEventWireup
    指示页面的事件是否自动匹配。 如果启用事件自动匹配，则为 true；否则为 false。 默认值为 true。 有关更多信息，请参见 ASP.NET Web Server Control Event Model。

  • Buffer
    确定是否启用 HTTP 响应缓冲。 如果启用页缓冲，则为 true；否则为 false。

    默认值为 true。

  • ClassName
    一个字符串，指定在请求页时将进行动态编译的页类的名称。 此值可以是任何有效的类名，并且可以包括完全限定的类名。 如果未指定该特性的值，则已编译页的类名将基于页的文件名并使用默认命名空间 ASP。 如果指定的 ClassName 特性的值没有完整的命名空间，将结合使用命名空间 ASP 与指定的类名以创建完全限定的类名。

    其他页可以通过使用 @ Reference 指令来引用分配给第一页的类名。

    备注

    可以使用 .aspx 页的完全限定类名在代码隐藏页类中引用关联的 .aspx 页类的成员。但是，如果预编译启用了源代码保护的网站，则代码隐藏页类与 .aspx 页类不在同一程序集中。因此，代码隐藏文件中引用的类将不起作用。有关预编译的更多信息，请参见 ASP.NET Web Site Precompilation Overview。

  • ClientIDMode
    指定用于生成控件 ClientID 值的算法。 默认值为 Predictable。 控件的默认值为 Inherit。 因此，页面中控件的默认算法由页面的 ClientID 设置决定。 可以在 Web.config 文件的 pages 元素中设置不同的默认值。 有关该算法的详细信息，请参阅 ClientIDMode 类。

  • ClientTarget
    指示 ASP.NET 服务器控件应该为其呈现内容的目标用户代理（通常是 Web 浏览器，例如 Microsoft Internet Explorer）。 该值可以是应用程序配置文件的 <clientTarget> 节中定义的任何有效别名。 有关更多信息，请参见 ClientTarget 属性。

  • CodeBehind
    指定包含与页关联的类的已编译文件的名称。 该特性不能在运行时使用。

    此特性用于 Web 应用程序项目。 CodeFile 特性用于网站项目。 有关 Visual Studio 中 Web 项目类型的更多信息，请参见 Web 应用程序项目，而不是在 Visual Studio 中的网站项目。

  • CodeFile
    指定指向页引用的代码隐藏文件的路径。 此特性与 Inherits 特性一起使用，用于将代码隐藏源文件与网页相关联。 此特性仅对编译的页有效。

    此特性用于网站项目。 CodeBehind 特性用于 Web 应用程序项目。 有关 Visual Studio 中 Web 项目类型的更多信息，请参见 Web 应用程序项目，而不是在 Visual Studio 中的网站项目。

  • CodeFileBaseClass
    指定页的基类及其关联的代码隐藏类的类型名称。 此特性是可选的，但如果使用此特性，则必须同时使用 CodeFile 特性。 如果希望实现以下共享方案，可使用该特性：在该共享方案中，您在基类中定义通用字段（可以选择性地定义关联事件）以引用在网页中声明的控件。 出于 ASP.NET 代码生成模型的缘故，如果您在基类中定义字段时没有使用该特性，则编译时将为在网页中（在单独的分部类存根中）声明的控件生成新的成员定义，而您希望的方案将无法生效。 但是，如果您使用 CodeFileBaseClass 特性将基类与页相关联，并且您的分部类（其名称分配给 Inherits 特性，并且其源文件由 CodeFile 特性引用）是从该基类继承的，则该基类中的字段在代码生成之后将能够引用页上的控件。

  • CodePage
    指示用于响应的编码方案的值。 该值是一个用作编码方案 ID 的整数。 有关可能的 CodePage ID 的列表，请参见 Encoding 类。

  • CompilationMode
    设置是否应使用指定多个枚举选项之一的字符串来编译页。 默认值为 Always，因此，默认情况下编译 .aspx 页。 有关详细信息，请参见 CompilationMode 枚举。

  • CompilerOptions
    包含用于编译页的编译器选项的字符串。 在 C# 和 Visual Basic 中，这是编译器命令行开关的序列。 有关编译器选项的更多信息，请参见 C# 编译器选项 或 Visual Basic 命令行编译器。

  • ContentType
    将响应的 HTTP 内容类型定义为标准的 MIME 类型。 支持任何有效的 HTTP 内容类型字符串。 有关可能值的列表，请在 MSDN Library 中搜索 MIME。

  • Culture
    指示页的区域性设置。 此特性的值必须是有效的区域性 ID。 注意，LCID 和 Culture 特性是互相排斥的；如果使用了其中一个特性，就不能在同一页中使用另一个特性。 有关更多信息，请参见 Culture 属性和 CultureInfo 类。

  • Debug
    指示是否应使用调试符号来编译页面。 如果应使用调试符号编译该页，则为 true；否则为 false。 由于此设置影响性能，因此只应在开发期间将此特性设置为 true。

  • Description
    提供该页的文本说明。 ASP.NET 分析器忽略该值。

  • EnableEventValidation
    在回发和回调方案中启用事件验证。 如果验证事件，则为 true；否则为 false。 默认值为 true。

    页面事件验证机制可消除未经授权的回发请求和回调带来的风险。 如果 enableEventValidation 属性设置为 true，ASP.NET 只允许可在回发请求或回调过程中对控件引发的事件。 通过此模型，控件可在呈现期间注册其事件，然后在回发或回调期间验证这些事件。 默认情况下，ASP.NET 中的所有事件驱动控件均使用此功能。

    强烈建议不要禁用事件验证。 在禁用事件验证之前，应该确保不会构造任何可能对应用程序具有意外影响的回发。

  • EnableSessionState
    定义页的会话状态要求。 如果启用了会话状态，则为 true；如果可以读取会话状态但不能进行更改，则为 ReadOnly；否则为 false。 默认值为 true。 这些值是不区分大小写的。 有关更多信息，请参见 ASP.NET Session State Overview。

  • EnableTheming
    指示页面上是否使用了主题。 如果使用主题，则为 true；否则为 false。 默认值为 true。

  • EnableViewState
    指定是否在多个页请求之间保持视图状态。 如果保持视图状态，则此值为 true，或者如果不保持视图状态，则为 false。 默认值为 true。

    即使此属性设置为 true，如果以下任一条件适用，控件也不会维护视图状态：

    有关视图状态和控件状态的详细信息，请参阅 Control.EnableViewState 属性。

  • EnableViewStateMac
    指示页从客户端回发时，ASP.NET 应在页的视图状态中验证消息验证代码 (MAC)。 如果应该对视图状态运行 MAC 检查，则为 true；否则为 false。 默认值为 true。

    视图状态 MAC 是隐藏变量的加密版本，当某页被发送到浏览器时，该页的视图状态永久保持到该变量中。 用 MAC 来验证视图状态是否已在客户端被篡改。

    安全说明安全说明

    在生成网站中，此属性永远不得设置为 false。

  • ErrorPage
    定义在出现未处理页异常时用于重定向的目标 URL。 有关更多信息，请参见 ErrorPage 属性。

  • Explicit
    确定是否使用 Visual Basic Option Explicit 模式来编译页。 如果启用 Visual Basic 显式编译选项，且所有变量必须使用 Dim、Private、Public 或 ReDim 语句进行声明，则为 true；否则为 false。 默认值为 false。

    备注

    除了 Visual Basic，所有其他语言都忽略此特性。此外，该选项在 Machine.config 配置文件中被设置为 true。有关更多信息，请参见 ASP.NET Configuration Files。

  • Inherits
    定义供页继承的代码隐藏类。 它可以是从 Page 类派生的任何类。 此特性与 CodeFile 特性一起使用，后者包含指向代码隐藏类的源文件的路径。 Inherits 特性在使用 C# 作为页面语言时区分大小写，而在使用 Visual Basic 作为页面语言时不区分大小写。

    如果 Inherits 特性不包含命名空间，ASP.NET 将检查 ClassName 特性是否包含命名空间。 如果包含，ASP.NET 将尝试使用 ClassName 特性的命名空间加载 Inherits 特性中引用的类。 （这假定 Inherits 特性和 ClassName 特性使用同一命名空间。）

    有关代码隐藏类的更多信息，请参见 ASP.NET Web Page Code Model。

  • Language
    指定在对页中所有内联呈现（<% %> 和 <%= %>）和代码声明块进行编译时使用的语言。 值可以表示任何 .NET Framework 支持的语言，包括 Visual Basic、C# 或 JScript。 每页只能使用和指定一种语言。

  • LCID
    定义 Web 窗体页的区域设置标识符。

    备注

    区域设置标识符是一个 32 位值，该值唯一地定义某个区域设置。除非您使用该特性为 Web 窗体页指定不同的区域设置，否则 ASP.NET 使用 Web 服务器默认的区域设置。注意，LCID 和 Culture 特性是互相排斥的；如果使用了其中一个特性，就不能在同一页中使用另一个特性。有关区域设置的更多信息，请搜索 MSDN Library。

  • LinePragmas
    确定运行时是否应在源代码中生成行杂注。 这些是编译器选项，通常由调试工具用来在源文件中标记特定位置。 如果应生成行杂注，则为 true；否则为 false。

  • MaintainScrollPositionOnPostback
    指示回发后是否将用户返回到客户端浏览器中的同一位置。 如果应该将用户返回到同一位置，则为 true；否则为 false。 默认值为 false。

    备注

    开发人员可以通过设置 Web.config 文件的 <pages> 元素上的 maintainScrollPostitionOnPostback 特性（注意，此特性在配置文件中是区分大小写的），为所有页定义该特性。

  • MasterPageFile
    设置内容页的母版页或嵌套母版页的路径。 支持相对路径和绝对路径。 有关更多信息，请参见 MasterPageFile 属性。

  • MetaDescription
    设置 MetaDescription 属性。 如果页标记还包括“说明”meta 元素，则 @ Page 指令中的值将覆盖标记中的值。

  • MetaKeywords
    设置 MetaKeywords 属性。 如果页标记还包括“密码”meta 元素，则 @ Page 指令中的值将覆盖标记中的值。

  • ResponseEncoding
    指示用于包含页内容的 HTTP 响应的编码方案的名称。 分配给此特性的值是有效的编码名称。 有关可能的编码名称的列表，请参见 Encoding 类。 您也可以调用 GetEncodings 方法来获取可能的编码名称和 ID 的列表。

  • SmartNavigation
    指示页是否支持 Internet Explorer 5.5 或更高版本的智能导航功能。 如果启用智能导航，则为 true；否则为 false。 默认值为 false。

    在 ASP.NET 2.0 版和更高版本中，SmartNavigation 属性已过时。 请改用 SetFocus 方法和 MaintainScrollPositionOnPostback() 属性。

  • Src
    指定包含链接到页的代码的源文件的路径。 在链接的源文件中，可以选择将页的编程逻辑包含在类中或代码声明块中。

    可以使用 Src 特性将生成提供程序链接到页。 有关更多信息，请参见 BuildProvider 类。 另外，在低于 2.0 版的 ASP.NET 中，Src 特性是另一种将代码隐藏文件链接到页的方法。 在 ASP.NET 2.0 中，将代码隐藏源文件链接到页的首选方法是使用 Inherits 特性来指定类，并使用 CodeFile 特性来指定该类的源文件的路径。

  • Strict
    指示应使用 Visual Basic OptionStrict 模式来编译页面。 如果启用 Option Strict，则为 true；否则为 false。 默认值为 false。

    备注

    除了 Visual Basic，所有其他语言都忽略此特性。

  • StyleSheetTheme
    指定在页上使用的有效主题标识符。 如果设置了 StyleSheetTheme 特性，则单独的控件可以重写主题中包含的样式设置。 这样，主题可以提供站点的整体外观，同时，利用 StyleSheetTheme 特性中包含的设置可以自定义页及其各个控件的特定设置。

  • TargetSchema
    指定用于验证页内容的方案的名称。 此特性仅起描述性的作用，而不会真正执行验证；分析器将忽略此特性。

  • Theme
    指定在页上使用的有效主题标识符。 如果设置 Theme 特性时没有使用 StyleSheetTheme 特性，则将重写控件上的单独的样式设置，允许您创建统一而一致的页外观。 有关更多信息，请参见 Theme 属性。

  • Title
    指定在响应的 HTML <title> 标记中呈现的页的标题。 也可以通过编程方式将标题作为页的属性来访问。 有关详细信息，请参见 Title 属性。

  • Trace
    指示是否启用跟踪。 如果已启用跟踪，则为 true；否则，为 false。 默认值为 false。 有关更多信息，请参见 ASP.NET Tracing Overview和 Trace 属性。

  • TraceMode
    指示当启用跟踪时如何为页显示跟踪消息。 可能的值为 SortByTime 和 SortByCategory。 当启用跟踪时，默认值为 SortByTime。 有关跟踪的更多信息，请参见 ASP.NET Tracing Overview。

  • Transaction
    指示在页上是否支持 COM+ 事务。 可能的值有 Disabled、NotSupported、Supported、Required 和 RequiresNew。 默认值为 Disabled。

  • UICulture
    指定用于页的用户界面 (UI) 区域性设置。 支持任何有效的 UI 区域性值。 有关更多信息，请参见 UICulture 属性。

  • ValidateRequest
    指示是否应发生请求验证。 如果为 true，请求验证将根据具有潜在危险的值的硬编码列表检查所有输入数据。 如果出现匹配情况，将引发 HttpRequestValidationException 异常。 默认值为 true。

    该功能在计算机配置文件 (Machine.config) 中启用。 可以在应用程序配置文件 (Web.config) 中或在页上将该特性设置为 false 来禁用该功能。

    备注

    该功能有助于减少对简单页或 ASP.NET 应用程序进行跨站点脚本攻击的风险。如果应用程序不能正确验证用户输入，则可能会受到多种类型的格式错误的输入的攻击，包括跨站点脚本攻击和 Microsoft SQL Server 注入式攻击。应该仔细地评估应用程序中所有形式的输入，并确保对它们进行了正确地验证和编码，或者确保应用程序在处理数据或将信息发送回客户端之前已退出。除此之外，别无它法。

  • ViewStateEncryptionMode
    使用三个可能的枚举值来确定如何加密视图状态：Auto、Always 或 Never。 默认值为 Auto，表示如果单个控件请求进行加密，将加密视图状态。 有关更多信息，请参见 ViewStateEncryptionMode。

  • ViewStateMode
    指定 ViewStateMode 属性值，在控件的 ViewStateMode 属性为 Inherit 时，将对控件生效。 页的默认 ViewStateMode 值为 Enabled。

    ViewStateMode 和 EnableViewState 属性确定是否为页上的控件维持视图状态。 有关更多信息，请参见 EnableViewState 属性和 ViewStateMode 属性。

  • WarningLevel
    指示您希望编译器将警告视为错误（从而中止对页进行编译）的编译器警告等级。 可能的警告等级为 0 到 4。 有关更多信息，请参见 WarningLevel 属性。

备注

该指令只能在 Web 窗体页中使用。 每个 .aspx 文件只能包含一条 @ Page 指令。 此外，每条 @ Page 指令只能定义一个 Language 特性，因为每页只能使用一种语言。 由于在源代码或配置文件中，大多数特性都提供了最常用的默认值，因此通常不需要向指令添加大量特性。 通常，应该添加指定希望页具有的功能所需的最小特性集。 如果有一个想应用于所有页的公共特性（例如，希望在所有页上启用跟踪），请考虑在 Web.config 文件中启用相应的功能，而不是向每个单独的页添加 Trace 特性。

备注

@ Page 指令具有大量与应用于整个源文件的其他指令（例如，在 Web 用户控件的 .ascx 文件中使用的 @ Control 指令和在母版页的 .master 文件中使用的 @ Master 指令）共用的特性。

若要定义 @ Page 指令的多个特性，请用一个空格分隔每个特性/值对。 对于特定特性，不要在将该特性与其值相连的等号 (=) 两侧加空格。 有关示例，请参见本主题的“示例”部分。

智能导航是 ASP.NET 的一个功能，Internet Explorer 5.5 和更高版本的浏览器都支持该功能。 它使得在对页进行刷新时，仍可保持导航之间的滚动位置和元素焦点。这样就只有一页存储在浏览器历史记录中，也就不再有因刷新网页引起的常见的闪烁问题。 智能导航在 ASP.NET 页中的使用效果最好，因为 ASP.NET 页要求频繁地回发，但可视化内容在返回时并不显著改变。 在决定是否将该特性设置为 true 时，请认真考虑这一点。

当页的 AspCompat 特性设置为 true 时，如果计划请求之前使用构造函数创建了 COM 组件，该请求将在多线程单元 (MTA) 线程上运行。 这样会导致 Web 服务器性能明显下降。 若要避免此问题，请只在一个 Page 事件（例如 Page_Load、Page_Init 等）或一个 Page 方法中创建 COM 组件。 还应确保不要在构造页时创建对象。

下面的代码示例演示一个在启用 AspCompat 的情况下在页中创建 COM 对象实例的建议方法。

<%@ Page AspCompat="true" language="C#" %>
<script runat="server" >

MyComObject comObj;

public void Page_Load(){
   // Use comObj here when the code is running on the STA thread pool.
   comObj = New MyComObject();
   // Do something with the combObj object.
}

<%@ Page AspCompat="true" language="VB" %>
<script runat="server" >

    Dim comObj As MyComObject 

    Public Sub Page_Load()
     'Use comObj here when the code is running on the STA thread pool.
     comObj = New MyComObject()
     ' Do something with the combObj object.
    End Sub
</script>

备注

向母版页添加 @ Master 指令并不能使您可以在依赖该母版页的页中使用相同的指令声明。应改用 pages 元素在全局范围内定义页指令。

示例

下面的代码示例指示 ASP.NET 页编译器使用 Visual Basic 作为页的服务器端代码语言，并将传输到客户端的默认 HTTP MIME ContentType 特性设置为 "text/xml"。

<%@ Page Language="VB" ContentType="text/xml" %>

请参见

参考

文本模板指令语法

@ Control

@ Master

其他资源

ASP.NET 页语法