@ Register

  • 發行項

建立標記前置詞與自訂控制項之間的關聯，以提供開發人員參考 ASP.NET 應用程式檔案 (包括 Web 網頁、使用者控制項和主版頁面 (Master Page)) 中自訂控制項的簡明方式。

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

屬性

  • assembly
    與 tagprefix 屬性產生關聯之命名空間 (Namespace) 所在的組件。

    注意

    組件名稱不能包含副檔名。同時請注意，如果遺失 assembly 屬性，則 ASP.NET 剖析器 (Parser) 會假設應用程式的 App_Code 資料夾中內含原始程式碼。如果您擁有要在頁面上註冊而不需編譯之控制項的原始程式碼，請將原始程式碼放置在 App_Code 資料夾中。ASP.NET 會在執行階段動態編譯 App_Code 資料夾內的原始程式碼。

  • namespace
    所註冊之自訂控制項的命名空間。

  • src
    要與 tagprefix:tagname 組產生關聯之宣告式 ASP.NET User Controls 檔案的位置 (相對或絕對)。

  • tagname
    要與類別產生關聯的任意別名。 這個屬性只能用於使用者控制項。

  • tagprefix
    任意的別名，提供在包含指示詞的檔案中使用之標記命名空間的簡略參考。

備註

將 @ Register 指示詞包含在網頁或使用者控制項中，可讓您使用宣告式 自訂伺服器控制項語法 配置自訂伺服器控制項或使用者控制項。

注意

您也可以使用 Web.config 檔中的 頁面的 controls 項目 (ASP.NET 設定結構描述) 註冊應用程式之所有頁面上的自訂控制項。

請在下列狀況中使用 @ Register 指示詞。

  • 若要以宣告方式將自訂控制項加入至 Web 網頁、使用者控制項、主版頁面或面板檔案 (請參閱 ASP.NET Themes Overview)。

  • 若要以宣告方式將使用者控制項加入至 Web 網頁、使用者控制項、主版頁面或面板檔案。

注意

tagprefix 值 "mobile" 是 ASP.NET 用於識別 System.Web.UI.MobileControls 命名空間內的 Mobile Web 控制項的值。您應該避免在控制項內使用這個前置詞。

當您使用 @ Register 指示詞來參考某個控制項時，可以將控制項的程式碼放置在下列位置：

  • 由於原始程式碼位於應用程式的 App_Code 資料夾中，這些原始程式碼將會在執行階段動態編譯。 這是開發期間可利用的一個方便的選項。 如果選擇這個選項，您就不能在 @ Register 指示詞內使用 assembly 屬性。

  • 如果將已編譯的組件存放在應用程式的 Bin 資料夾內， 則這是供已部署的 Web 應用程式使用的一般選項。

  • 如果將已編譯和已簽署的組件存放在全域組件快取 (Global Assembly Cache，GAC) 內， 則這是您想要在多個應用程式內共用已編譯的控制項時可以使用的一般選項。 您可以對 assembly 屬性指定識別字串，以便在 GAC 內參考某個控制項。 字串會指定與控制項有關的必要細節，包括其完整的型別名稱、版本、公開金鑰語彙基元和文化特性 (Culture)。 下列功能性字串說明在 GAC 內參考某個自訂控制項的方式：

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

    如需參考組件的詳細資訊，請參閱編譯組件的 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 Web 網頁中存取它。如需開發自訂 ASP.NET 伺服器控制項的詳細資訊，請參閱Developing Custom ASP.NET Server Controls。

範例

下列程式碼範例使用 @ Register 指示詞宣告 tagprefix 和 tagname 別名，以及指派 src 屬性，以參考至 Web 網頁內的使用者控制項。 程式碼的第一個部分是個簡單的使用者控制項，由 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