@ Register

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

创建标记前缀和自定义控件之间的关联,这为开发人员提供了一种在 ASP.NET 应用程序文件(包括网页、用户控件和母版页)中引用自定义控件的简明方法。

<%@ Register tagprefix="tagprefix"
   namespace="namespace"
   assembly="assembly" %>
<%@ Register tagprefix="tagprefix"
   namespace="namespace" %>
<%@ Register tagprefix="tagprefix"
   tagname="tagname"
   src="pathname" %>

特性

  • assembly
    与 tagprefix 特性关联的命名空间所驻留的程序集。

    备注

    程序集名称不能包括文件扩展名。另请注意,如果 assembly 特性缺失,ASP.NET 分析器会假定应用程序的 App_Code 文件夹中存在源代码。如果您希望在页面上注册控件的源代码而不对其进行编译,请将源代码放在 App_Code 文件夹中。ASP.NET 在运行时动态编译 App_Code 文件夹中的源文件。

  • namespace
    正在注册的自定义控件的命名空间。

  • src
    与 tagprefix:tagname 对关联的声明性 ASP.NET User Controls 文件的位置(相对的或绝对的)。

  • tagname
    与类关联的任意别名。 此特性只用于用户控件。

  • tagprefix
    一个任意别名,它提供对包含指令的文件中所使用的标记的命名空间的短引用。

备注

如果在页或用户控件中包含 @ Register 指令,则可以使用声明性 自定义服务器控件语法 为自定义服务器控件或用户控件进行布局。

备注

还可以通过使用 Web.config 文件中的 pages 的 controls 元素(ASP.NET 设置架构) 在应用程序的所有页上注册自定义控件。

在以下情况中,使用 @ Register 指令:

  • 以声明方式将自定义服务器控件添加到网页、用户控件、母版页或外观文件(请参见 ASP.NET Themes Overview)。

  • 以声明方式将用户控件添加到网页、用户控件、母版页或外观文件。

备注

tagprefix 值“mobile”由 ASP.NET 用于标识 System.Web.UI.MobileControls 命名空间中的移动 Web 控件。应避免对控件使用此前缀。

使用 @ Register 指令引用控件时,可以将控件的代码放在以下位置:

  • 作为应用程序的 App_Code 文件夹的源代码,将在运行时在该文件夹中动态编译代码。 在开发过程中可以使用这一便捷选项。 如果您选择此选项,则不必在 @ Register 指令中使用 assembly 特性。

  • 作为应用程序的 Bin 文件夹中的编译的程序集。 这是一个针对部署的 Web 应用程序的通用选项。

  • 作为全局程序集缓存 (GAC) 中编译和签署的程序集。 这是一个针对希望在多个应用程序之间共享编译的控件的通用选项。 通过向 assembly 特性分配正在识别的字符串,可以引用 GAC 中的控件。 此字符串指定有关控件的所需详细信息,包括控件的完全限定类型名、版本、公钥标记和区域性。 下面的虚拟字符串阐明了对 GAC 中的自定义控件的引用:

    <%@ Register  tagprefix="custom"
         namespace="Mycompany.namespace"
         assembly="Mycompany.namespace.control, Version=1.2.3.4, 
            PublicKeyToken=12345678abcdefgh, Culture=neutral"  %>
    

    有关引用程序集的更多信息,请参见compilation 的 assemblies 的 add 元素(ASP.NET 设置架构)

对于声明性用户控件,请使用 tagname、tagprefix 和 src 特性。 在页中声明控件时,前两个属性总是以冒号分隔对 (tagprefix:tagname) 的形式一起使用。 可以将多个命名空间映射到同一 tagname,如以下示例所示:

<% @Register tagprefix="tag1" namespace="MyNamespace1"/>
<% @Register tagprefix="tag1" namespace="MyNamespace2"/> 

src 特性值既可以是相对路径,也可以是从应用程序的根目录到用户控件源文件的绝对路径。 为方便使用,建议使用相对路径。 例如,假设将应用程序的所有用户控件文件存储在应用程序根目录的子目录 \Usercontrol 中。 若要包括 Usercontrol1.ascx 文件中的用户控件,请在 @ Register 指令中包含以下内容:

Src="~\usercontrol\usercontrol1.ascx" 

代字号 (~) 字符表示应用程序的根目录。

备注

如果用户控件和包含该控件的页位于同一目录中,则 src 特性值应当为 .ascx 文件的文件名和扩展名。

当包含已经编译为 .dll 文件供应用程序使用的自定义服务器控件时,请将 tagprefix 特性与 assembly 和 namespace 特性一起使用。 如果没有包含 namespace 特性,或者为其分配了一个空字符串 (""),则会出现分析器错误。

警告

在开发自定义服务器控件时,必须将其包含在命名空间中。如果没有包含在命名空间中,则将无法从 ASP.NET 页中访问该控件。有关开发自定义 ASP.NET 服务器控件的更多信息,请参见Developing Custom ASP.NET Server Controls

示例

下面的代码示例使用 @ Register 指令声明 tagprefix 和 tagname 别名,同时分配 src 特性以在网页内引用用户控件。 代码的第一部分是由一个 ASP.NET Calendar 控件组成的简单用户控件。 代码的第二部分是承载该控件的页。 请注意,tagprefix 特性分配一个用于标记的任意前缀值。 tagname 特性使用分配给用户控件的类名称的值(尽管此特性可以取任意值,且可使用任何字符串值,但不必使用所引用控件的类名称)。 src 特性指向用户控件的源文件(相对于应用程序根文件夹)。 按照如下形式,使用前缀、冒号以及标记名称在页面主体内引用用户控件:<uc1:CalendarUserControl runat="server" />。

<%@ Control ClassName="CalendarUserControl" %>
<asp:calendar id="Calendar1" runat="server" />


<%@ Page %>
<%@ register tagprefix="uc1" 
    tagname="CalendarUserControl" 
    src="~/CalendarUserControl.ascx" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Calendar Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <uc1:calendarusercontrol runat="server" />
  </form>
</body>
</html>

请参见

参考

文本模板指令语法

概念

ASP.NET Web Page Syntax Overview

其他资源

ASP.NET User Controls