共用方式為

逐步解說：開發和使用自訂的伺服器控制項

  • 發行項

更新：2007 年 11 月

本逐步解說會示範如何建立和編譯自訂 ASP.NET 伺服器控制項，以及在網頁中使用此控制項的方法。

您可以透過這份逐步解說瞭解如何：

  • 建立 ASP.NET 伺服器控制項

  • 將中繼資料 (Metadata) 加入至控制項與控制項的成員，以控制安全性和設計階段行為

  • 在 ASP.NET Web 網頁中使用 App_Code 目錄，在不使用手動編譯步驟的情況下測試控制項

  • 在組態檔和控制項的組件中指定標記前置詞

  • 將控制項編譯至組件，並加入至 Bin 目錄

  • 將點陣圖內嵌至控制項的組件，做為視覺化設計工具 (Visual Designer) 的工具箱圖示

  • 在網頁中使用編譯的控制項

Microsoft Visual Studio 2005 這類視覺化設計工具會簡化控制項的開發，但基本上不是用於建立或建置自訂控制項。您可以使用任何文字編輯器建立控制項，並使用屬於 Windows Software Development Kit (SDK) 的編譯器 (Compiler)，從命令列建置這些控制項。無論使用什麼方法建立控制項，控制項的設計階段外觀和行為，在視覺化設計工具中都會一樣。網頁開發人員可以將控制項加入至視覺化設計工具的工具箱、拖曳至設計介面，然後在屬性瀏覽器 (在 [屬性] 視窗中) 中存取屬性和事件。在一些視覺化設計工具 (如 Visual Studio 2005) 中，自訂控制項不需要您親自操作，也可以具有 IntelliSense 支援。

建立伺服器控制項

您將建立的控制項 WelcomeLabel，是類似於標準 Label 控制項的簡易控制項。WelcomeLabel 類別衍生自 WebControl 並且定義 Text 屬性，可讓網頁開發人員提供歡迎使用者造訪網站的文字字串。如果使用者名稱出現在使用者瀏覽器傳送的頁首中，WelcomeLabel 會將使用者名稱附加至文字字串。如需擷取使用者名稱的詳細資訊，請參閱 User。例如，假設網頁開發人員設定 "Hello" 做為 Text 屬性的值，WelcomeLabel 會根據使用者名稱是否出現在頁首中，進而呈現 "Hello, userName!" 或 "Hello!"。

建立自訂伺服器控制項的程式碼

  1. 建立名為 WelcomeLabel.cs 或 WelcomeLabel.vb 的檔案。

  2. 將下列程式碼加入至控制項的原始程式檔 (Source File)：

    ' WelcomeLabel.vb
Option Strict On
Imports System
Imports System.ComponentModel
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

Namespace Samples.AspNet.VB.Controls
    < _
    AspNetHostingPermission(SecurityAction.Demand, _
        Level:=AspNetHostingPermissionLevel.Minimal), _
    AspNetHostingPermission(SecurityAction.InheritanceDemand, _
        Level:=AspNetHostingPermissionLevel.Minimal), _
    DefaultProperty("Text"), _
    ToolboxData( _
        "<{0}:WelcomeLabel runat=""server""> </{0}:WelcomeLabel>") _
    > _
    Public Class WelcomeLabel
        Inherits WebControl
        < _
        Bindable(True), _
        Category("Appearance"), _
        DefaultValue(""), _
        Description("The welcome message text."), _
        Localizable(True) _
        > _
        Public Overridable Property Text() As String
            Get
                Dim s As String = CStr(ViewState("Text"))
                If s Is Nothing Then s = String.Empty
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Text") = value
            End Set
        End Property

        Protected Overrides Sub RenderContents( _
            ByVal writer As HtmlTextWriter)
            writer.WriteEncodedText(Text)
            If Context IsNot Nothing Then
                Dim s As String = Context.User.Identity.Name
                If (s IsNot Nothing) AndAlso (s <> String.Empty) Then
                    Dim split() As String = s.Split("\".ToCharArray)
                    Dim n As Integer = split.Length - 1
                    If (split(n) <> String.Empty) Then
                        writer.Write(", ")
                        writer.Write(split(n))
                    End If
                End If
            End If
            writer.Write("!")
        End Sub
    End Class
End Namespace

    // WelcomeLabel.cs
using System;
using System.ComponentModel;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace Samples.AspNet.CS.Controls
{
    [
    AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal),
    AspNetHostingPermission(SecurityAction.InheritanceDemand, 
        Level=AspNetHostingPermissionLevel.Minimal),
    DefaultProperty("Text"),
    ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>")
    ]
    public class WelcomeLabel : WebControl
    {
        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The welcome message text."),
        Localizable(true)
        ]
        public virtual string Text
        {
            get
            {
                string s = (string)ViewState["Text"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Text"] = value;
            }
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            writer.WriteEncodedText(Text);
            if (Context != null)
            {
                string s = Context.User.Identity.Name;
                if (s != null && s != String.Empty)
                {
                    string[] split = s.Split('\\');
                    int n = split.Length - 1;
                    if (split[n] != String.Empty)
                    {
                        writer.Write(", ");
                        writer.Write(split[n]);
                    }
                }
            }
            writer.Write("!");
        }
    }
}

程式碼討論

隨後的程式碼討論基本上不適用於執行本逐步解說中的步驟，您一開始就可以略過這段。但是，如果您對控制項撰寫方法不熟悉，建議在完成逐步解說之後至少閱讀一次程式碼討論。

如果控制項在用戶端上呈現使用者介面 (UI) 項目或其他可見的項目，您就應該從 System.Web.UI.WebControls.WebControl (或衍生的類別) 衍生控制項。如果在用戶端瀏覽器上看不見控制項呈現的項目 (例如隱藏項目或 meta 項目)，請從 System.Web.UI.Control 衍生控制項。WebControl 類別衍生自 Control 並會加入與樣式相關的屬性，例如 Font、ForeColor 和 BackColor。此外，衍生自 WebControl 的控制項會參與 ASP.NET 的主題功能，您不需要額外執行其他作業。

如果控制項會擴充現有控制項的功能 (例如 Button、Label 或 Image 控制項)，則可以從該控制項衍生。因為 WelcomeLabel 會擴充 Label 控制項的功能，因此可以從 Label 衍生。但是，本逐步解說會從 WebControl 衍生 WelcomeLabel，以顯示如何定義屬性和定義屬性中繼資料。

WelcomeLabel 會定義一個 Text 屬性，並使用檢視狀態儲存屬性值。使用檢視狀態能保存多個回傳中 (Postback) 的 Text 值。在每個回傳 (Postback) 上，網頁會重新建立，值也會從檢視狀態中還原。如果 Text 值並未儲存在檢視狀態中，則會在每個回傳 (Postback) 上將值設為預設值 Empty。繼承自 WebControl 的 ViewState 屬性是儲存資料值的字典。要輸入及擷取值都會使用 String 索引鍵。在上述情形中，"Text" 會當做索引鍵使用。字典中的項目型別為 Object，您接著必須將它轉換為屬性型別 (Property Type)。如需詳細資訊，請參閱 ASP.NET 狀態管理概觀。

WelcomeLabel 控制項透過覆寫繼承的 RenderContents 方法，呈現其 Text 屬性。傳遞至 RenderContents 方法的參數是型別 HtmlTextWriter 的物件，這是具有可呈現標記 (Tag) 和其他 HTML (和 HTML 變異) 標記 (Markup) 的公用程式類別。

請注意，WelcomeLabel 會對 HtmlTextWriter 物件的 Write 方法產生連續呼叫，而非執行字串串連後再叫用 Write 方法。因為 HtmlTextWriter 物件會直接寫入輸出資料流，效能就因此獲得提升。字串串連需要時間和記憶體先建立字串，然後再寫入資料流。當您在控制項中實作呈現時，應該遵循本逐步解說中提供的模式。

注意事項：

一般來說，當您的控制項是衍生自 WebControl 並呈現單一項目時，應該覆寫 RenderContents 方法 (而不是 Render 方法)，以呈現控制項標記中的內容。WebControl 的 Render 方法會在呈現控制項的開頭標記及其樣式屬性 (Attribute) 之後叫用 RenderContents。如果覆寫 Render 方法以寫入內容，您的控制項將遺失 WebControl 的 Render 方法建置的樣式呈現邏輯。如需呈現衍生自 WebControl 的控制項詳細資訊，請參閱 Web 控制項呈現範例。

套用至 WelcomeLabel 的屬性 (Attribute) 包含 Common Language Runtime 和設計階段工具所使用的中繼資料。

在類別層級中，WelcomeLabel 將以下列屬性 (Attribute) 標記：

  • AspNetHostingPermissionAttribute 是程式碼存取的安全性屬性。會使 JIT 編譯器檢查連結至 WelcomeLabel 的程式碼是否授與 AspNetHostingPermission 使用權限。所有公用 ASP.NET 類別都會以這個屬性 (Attribute) 標記。您應該將 AspNetHostingPermissionAttribute 套用至控制項，以對部分信任的呼叫端進行安全性檢查。

  • DefaultPropertyAttribute 是設計階段屬性 (Attribute)，會指定控制項的預設屬性 (Property)。在視覺化設計工具中，當網頁開發人員按一下設計介面上的控制項時，屬性瀏覽器通常會反白顯示預設屬性。

  • ToolboxDataAttribute 會指定項目的格式字串。在工具箱中按兩下控制項或從工具箱拖曳至設計介面時，字串會變成控制項的標記。針對 WelcomeLabel，字串會建立此項目：

    <aspSample:WelcomeLabel > </aspSample:WelcomeLabel>

WelcomeLabel 控制項也會從 WebControl 基底類別 (Base Class) 繼承以下兩個屬性 (Attribute)：ParseChildrenAttribute 和 PersistChildrenAttribute。這兩個屬性會套用為 ParseChildren(true) 和 PersistChildren(false)。這兩個屬性 (Attribute) 會一起運作並且搭配 ToolboxDataAttribute 屬性 (Attribute)，如此子項目會解譯為屬性 (Property)，而屬性 (Property) 會當做屬性 (Attribute) 保存。

套用至 WelcomeLabel 的 Text 屬性 (Property) 之下列屬性 (Attribute) 是標準設計階段屬性 (Attribute)，您通常會將這些屬性 (Attribute) 套用至控制項的所有公用屬性 (Property)：

  • BindableAttribute (指定為 true 或 false) 會指定視覺化設計工具是否對繫結屬性至資料來說是有意義的。例如，在 Visual Studio 2005 中，如果將屬性標記為 Bindable(true)，屬性便會顯示在 [資料繫結] 對話方塊中。如果屬性 (Property) 未標記為 Bindable 屬性 (Attribute)，屬性瀏覽器會將值推斷 Bindable(false)。

  • CategoryAttribute 會指定如何在視覺化設計工具的屬性瀏覽器中對屬性進行分類。例如，當網頁開發人員使用屬性瀏覽器的分類檢視時，標示為 Category("Appearance") 的屬性，會通知屬性瀏覽器在 [外觀] 分類中顯示該屬性。您可以指定與屬性瀏覽器的現有分類相對應的字串引數，或建立自己的分類。

  • DescriptionAttribute 會指定屬性的概要說明。在 Visual Studio 2005 中，屬性瀏覽器會在 [屬性] 視窗的底部，顯示所選取屬性的說明。

  • DefaultValueAttribute 會指定屬性的預設值。這個值應該與您從屬性存取子 (getter) 傳回的預設值相同。在 Visual Studio 2005 中，DefaultValueAttribute 透過顯示 [屬性] 視窗中的快速鍵功能表並按一下 [重設] 按鈕，可讓網頁開發人員將屬性值重設為預設值。

  • LocalizableAttribute (指定為 true 或 false) 會指定視覺化設計工具是否對當地語系化屬性來說是有意義的。當屬性被標記為 Localizable(true) 時，視覺化設計工具會在序列化當地語系化資源時併入該屬性。對可當地語系化的屬性輪詢控制項時，設計工具將保存屬性值至中性文化特性 (Culture) 的資源檔或其他當地語系化來源。

    注意事項：

    您不能將 LocalizableAttribute 套用至 ASP.NET 1.0 版和 1.1 版中的自訂伺服器控制項，因為這些版本中的 ASP.NET 當地語系化模型不相同。

套用至控制項與其成員的設計階段屬性，在執行階段不會影響控制項的功能，而在視覺化設計工具中使用控制項時，會增加開發人員的經驗。您可以在自訂伺服器控制項的中繼資料屬性中查看伺服器控制項之設計階段、剖析階段和執行階段屬性的完整清單。

使用 App_Code 目錄測試控制項，不需要編譯

您可以使用 ASP.NET 的動態編譯功能測試網頁中的控制項，而不需要事先將控制項編譯為組件。ASP.NET 會動態編譯位於 ASP.NET 網站根目錄下 \App_Code 目錄中的程式碼。如此，就可以從網頁存取 \App_Code 原始程式檔中的類別，不需先行以手動方式編譯成組件。如果將控制項的原始程式檔放置在 App_Code 目錄中，您對控制項程式碼所做的變更會立即在使用控制項的網頁中反映出來。

注意事項：

ASP.NET 1.0 和 1.1 中沒有 \App_Code 目錄這個新功能。使用 App_Code 目錄進行初始控制項測試是選擇性功能。建置伺服器控制項的主要步驟與早期版本中相同，如下一個章節＜將控制項編譯為組件＞中所示：

若要建立 ASP.NET 網站和 App_Code 目錄

  1. 建立名為 ServerControlsTest 的網站。您可以建立名為 ServerControlsTest 的虛擬目錄，在 IIS 中建立此網站。如需建立及設定 IIS 虛擬目錄的詳細資訊，請參閱 HOW TO：在 IIS 5.0 和 6.0 中建立和設定虛擬目錄。

  2. 直接在網站根目錄 (又稱 Web 應用程式根目錄) 下建立 \App_Code 目錄。

  3. 將控制項的原始程式檔 (WelcomeLabel.cs 或 WelcomeLabel.vb) 複製至 App_Code 目錄。

建立標記前置詞

標記前置詞是一種如 <asp:Table /> 中的前置詞 "asp"，在網頁中以宣告方式建立控制項時，會在控制項的型別名稱之前出現。若要讓控制項在網頁中以宣告方式使用，ASP.NET 需要對應至控制項命名空間的標記前置詞。網頁開發人員在使用自訂控制項的每個網頁上加入 @ Register 指示詞，即可提供標記前置詞/命名空間對應，如下列範例所示：

<%@ Register TagPrefix="aspSample" 
        Namespace="Samples.AspNet.CS.Controls"%>

[Visual Basic]

<%@ Register TagPrefix="aspSample" 
        Namespace="Samples.AspNet.VB.Controls"%>
注意事項：

ASP.NET 2.0 中的 @ Register 指示詞，和 ASP.NET 1.0 與 ASP.NET 1.1 中的指示詞相同。如果您熟悉 ASP.NET 較早版本的 Register 指示詞，可能會注意到指定控制項組件名稱的 assembly 屬性已不在先前的 Register 指示詞中。遺漏 assembly 屬性時，ASP.NET 推斷組件是從 App_Code 目錄的原始程式檔動態進行編譯。

做為在每個 .aspx 網頁中使用 @ Register 指示詞的替代用法，網頁開發人員可以在 Web.config 檔案中指定標記前置詞/命名空間對應。如果要在 Web 應用程式中的多個網頁上使用自訂控制項，這個用法將會很有幫助。下列程序描述如何在 Web.config 檔案中指定標記前置詞對應。

若要將標記前置詞對應加入 Web.config 檔案

  1. 在網站的根目錄下建立名為 Web.config 的文字檔 (如果這個檔案不存在)。

  2. 如果已建立新 (空的) Web.config 檔，請將下列程式碼複製到檔案，並儲存檔案。

    <?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample"            namespace="Samples.AspNet.CS.Controls">       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

    <?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample"            namespace="Samples.AspNet.VB.Controls">       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

    反白顯示的區段會顯示標記前置詞項目，這個項目會將標記前置詞 "aspSample" 對應至命名空間 Samples.AspNet.CS.Controls 或 Samples.AspNet.VB.Controls。

  3. 如果 Web.config 檔案已存在，會加入先前步驟中的反白顯示文字，做為組態檔 controls 項目的子系。如果 controls 和 pages 項目不在 Web.config 檔案中，如先前步驟之說明建立這些項目。

    注意事項：

    標記前置詞項目必須是 controls 區段的子系，這個區段必須是在 system.web 子系的 pages 區段之下。

在組態檔中指定標記前置詞對應之後，您可以在網站的任何網頁中以宣告方式使用 WelcomeLabel 控制項 (做為 <aspSample:WelcomeLabel />)。

注意事項：

標記前置詞的設定項目是 ASP.NET 2.0 的新功能。在 ASP.NET 1.0 和 1.1 中，標記前置詞對應是在使用自訂控制項的每個網頁 @ Register 指示詞中指定。

建立使用控制項的網頁

若要建立使用自訂控制項的網頁

  1. 在網站中建立名稱為 WelcomeLabelTest.aspx 的文字檔。

  2. 將下列標記複製至 WelcomeLabelTest.aspx 檔案並儲存檔案。

    <%@ Page Language="VB"%>
<!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 id="Head1" >
    <title>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" >
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
           BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </form>
  </body>
</html>

    <%@ Page Language="C#"%>
<!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 id="Head1" >
    <title>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" >
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
           BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </form>
  </body>
</html>

  3. 在位址列中輸入下列 URL，即可在瀏覽器中顯示 WelcomeLabelTest.aspx：

    https://localhost/ServerControlsTest/WelcomeLabelTest.aspx

  4. 對控制項的原始程式碼進行一些變更。例如，在 RenderContents 方法結尾處加入這行程式碼，即可寫入額外的字串：

    writer.Write("Testing how the App_Code directory works.");

    writer.Write("Testing how the App_Code directory works.")

  5. 在瀏覽器中重新整理 WelcomeLabelTest.aspx 網頁。

    您將看到即使沒有編譯控制項，控制項中的變更仍會反映在網頁中。

除了您明確定義的 WelcomeLabel 控制項 Text 屬性之外，可以從網頁的控制項執行個體中看到，控制項具有沒有定義的 BackColor 和 ForeColor 屬性。WelcomeLabel 控制項會從 WebControl 基底類別繼承而取得這些屬性以及樣式相關屬性。此外，可以將面板指定給 WelcomeLabel 並做為主題的一部分，不需要您採取任何動作。

將控制項編譯為組件

雖然 App_Code 目錄可讓您在沒有編譯的情況下測試控制項，如果您將控制項當做物件程式碼傳送給其他開發人員，則必須編譯此控制項。此外，將控制項編譯為組件之前，無法將控制項加入至視覺化設計工具的工具箱中。

若要將控制項編譯為組件

  1. 依照下列步驟，設定電腦的 Windows 環境 PATH 變數，加入 .NET Framework 的安裝路徑：

    1. 在 Windows 中，以滑鼠右鍵按一下 [我的電腦]、選取 [內容]、依序按一下 [進階] 索引標籤和 [環境變數] 按鈕。

    2. 在 [系統變數] 清單中，按兩下 Path 變數。

    3. 在 [變數值] 文字方塊中，將分號 (;) 加在文字方塊中現有值的結尾，然後輸入 .NET Framework 安裝的路徑。.NET Framework 通常是安裝在 \Microsoft.NET\Framework\versionNumber 的 Windows 安裝目錄中。

    4. 按一下 [確定] 關閉每個對話方塊。

  2. 從您在本逐步解說的第一個程序中對原始程式檔所建立的目錄，執行下列命令。

    注意事項：

    這個目錄與您複製控制項原始程式檔以進行測試的 App_Code 目錄不同。

    		 
    csc /t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll /r:System.Web.dll *.cs

    vbc /t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll /r:System.Web.dll *.vb

    /t:library 編譯器選項會通知編譯器建立程式庫，而非可執行的組件。/out 選項提供組件的名稱，而 /r 選項會列出連結至您組件的各組件。

若要讓範例保持為獨立的 (Self-Contained)，本逐步解說會要求您使用單一控制項建立組件。一般來說，.NET Framework 設計方針會建議您不要建立只包含幾個類別的組件。為了簡化部署，您應該盡可能建立較少的組件。

將圖示內嵌在控制項組件中

視覺化設計工具 (例如 Visual Studio 2005) 通常會使用預設圖示 (例如齒輪影像) 在工具箱中顯示控制項。做為控制項的選項，將 16 X 16 像素的點陣圖內嵌至控制項的組件，即可在工具箱中自訂控制項的外觀。根據慣例，視覺化設計工具使用點陣圖最少的像素做為透明色彩。

若要將圖示內嵌至控制項組件中

  1. 建立或取得 16 X 16 像素的點陣圖，做為控制項的工具箱圖示。

  2. 將點陣圖命名為 WelcomeLabel.bmp。

  3. 將點陣圖檔加入至具有 WelcomeLabel 控制項原始程式檔的目錄 (CustomControlsCS 或 CustomControlsVB)。

  4. 從包含原始程式檔的目錄執行下列命令：

    csc /res:WelcomeLabel.bmp,Samples.AspNet.CS.Controls.WelcomeLabel.bmp 
/t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll 
/r:System.Web.dll *.cs

    vbc /res:WelcomeLabel.bmp,Samples.AspNet.VB.Controls.WelcomeLabel.bmp 
/t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll 
/r:System.Web.dll *.vb

    這個命令會編譯控制項，並將點陣圖內嵌至組件當做資源。您必須將內嵌點陣圖資源的名稱，命名為與關聯之控制項命名空間完整名稱完全相同。例如，如果控制項的名稱是 Samples.AspNet.CS.Controls.WelcomeLabel，內嵌點陣圖的名稱必須是 Samples.AspNet.CS.Controls.WelcomeLabel.bmp。此命名慣例會使視覺化設計工具，自動使用點陣圖做為控制項的工具箱圖示。如果不使用命名慣例，您必須將 ToolboxBitmapAttribute 套用至控制項，以指定內嵌點陣圖資源的名稱。

使用 TagPrefixAttribute 提供標記前置詞/命名空間對應

在本逐步解說稍早提及，使用 App_Code 目錄時，您會看到網頁開發人員如何在網頁或 Web.config 檔案中指定標記前置詞。您可以藉由將組件層級 (Assembly-level) 的 System.Web.UI.TagPrefixAttribute 屬性納入，選擇性地建議視覺化設計工具應該在控制項中使用的預設標記前置詞。TagPrefixAttribute 屬性十分有用，因為當設計工具在 Web.config 檔案或網頁的 Register 指示詞中找不到標記前置詞對應時，這個屬性會提供標記前置詞供視覺化設計工具使用。第一次在工具箱中按兩下控制項，或從工具項將控制項拖曳至網頁時，會使用網頁註冊標記前置詞。

如果決定使用 TagPrefixAttribute 屬性，可以在使用控制項編譯的個別檔案中指定這個屬性。根據慣例，檔案會命名為 AssemblyInfo.languageExtension，例如 AssemblyInfo.cs 或 AssembyInfo.vb。下列程序將說明如何指定 TagPrefixAttribute 中繼資料。

注意事項：

如果在控制項組件中沒有指定 TagPrefixAttribute，且網頁開發人員在網頁或 Web.config 檔案中沒有指定標記前置詞/命名空間對應，視覺化設計工具可能會建立預設的標記前置詞。例如，從工具箱拖曳控制項時，Visual Studio 2005 將建立自己的標記 (例如 cc1)。

若要使用 TagPrefixAttribute 加入命名空間/標記前置詞對應

  1. 在原始程式碼目錄中建立名為 AssemblyInfo.cs 或 AssemblyInfo.vb 的檔案，並將下列程式碼加入至檔案。

    using System;
using System.Web.UI;
[assembly: TagPrefix("Samples.AspNet.CS.Controls", "aspSample")]

    Imports System
Imports System.Web.UI
<Assembly: TagPrefix("Samples.AspNet.VB.Controls", "aspSample")>

    標記前置詞屬性會在命名空間 Samples.AspNet.CS.Controls 或 Samples.AspNet.VB.Controls 與前置詞 aspSample 之間建立對應。

  2. 以您稍早所使用的編譯命令，重新編譯所有原始程式檔 (使用或不使用內嵌來源)。

在 ASP.NET 網頁中使用編譯的自訂控制項

若要測試自訂控制項的編譯版本，您必須讓網站中的網頁可存取控制項的組件。

若要讓網站可存取控制項組件

  1. 在網站的根目錄下建立 Bin 目錄。

  2. 將控制項組件 (Samples.AspNet.CS.Controls.dll 或 Samples.AspNet.VB.Controls.dll) 複製至 Bin 目錄。

  3. 從 App_Code 目錄刪除控制項的原始程式檔。

    如果沒有刪除原始程式檔，控制項型別會同時存在編譯的組件中以及 ASP.NET 建立的動態產生組件中。這樣會在載入控制項時建立模稜兩可的參考，而使用控制項的網頁將產生編譯器錯誤。

您在本逐步解說中建立的組件稱為私用組件，因為這個組件必須放置在 ASP.NET 網站的 Bin 目錄中，以便讓網站中的網頁使用控制項。組件無法從其他應用程式存取，除非這些應用程式也已安裝複本。如果正在建立共用 Web 裝載應用程式的控制項，您通常會將控制項封裝在私用組件中。但是，如果建立的控制項是用於專用裝載環境，或建立 ISP 讓所有客戶都能使用的控制項套件，您可能需要將控制項封裝於安裝在全域組件快取 (GAC) 的共用 (強式名稱) 組件中。如需詳細資訊，請參閱使用組件和全域組件快取。

接著，您必須修改在 Web.config 中建立的標記前置詞對應，以指定控制項的組件名稱。

若要修改 Web.config 中的標記前置詞對應

  • 編輯 Web.config 檔案，將 assembly 屬性 (Attribute) 加入至 addtagPrefix 項目：

    <controls>
  <add tagPrefix="aspSample"   
    namespace="Samples.AspNet.CS.Controls" 
    assembly="Samples.AspNet.CS.Controls">
  </add>
</controls>

    <controls>
  <add tagPrefix="aspSample"   
    namespace="Samples.AspNet.VB.Controls" 
    assembly="Samples.AspNet.VB.Controls">
  </add>
</controls>

assembly 屬性 (Attribute) 會指定控制項的組件名稱。addtagPrefix 項目會將標記前置詞對應至命名空間和組件的組合。ASP.NET 從 App_Code 目錄的原始程式檔動態產生組件時，不需要組件屬性。未使用組件屬性時，ASP.NET 會從組件載入控制項型別，而這些組件是從 App_Code 目錄所動態產生。

若要檢視使用自訂控制項的網頁

  • 在位址列中輸入下列 URL，即可在瀏覽器中顯示 WelcomeLabelTest.aspx 網頁：

    https://localhost/ServerControlsTest/WelcomeLabelTest.aspx

如果使用視覺化設計工具 (例如 Visual Studio 2005) 中的控制項，您就可以將控制項加入至工具箱、從工具箱將控制項拖曳至設計介面，並在屬性瀏覽器中存取屬性和事件。此外，在 Visual Studio 2005 中，控制項在網頁設計工具和程式碼編輯器的原始碼檢視中，皆具有完整的 IntelliSense 支援。這包含 script 區塊中的陳述式完成，以及網頁開發人員按一下控制項標記時的屬性瀏覽器支援。

注意事項：

在許多視覺化設計工具中，您可以將自訂控制項加入至設計工具的工具箱。如需詳細資訊，請參閱您的設計工具文件。

後續步驟

本逐步解說說明如何開發簡單的自訂 ASP.NET 伺服器控制項，以及在網頁中使用此控制項的方法。您會看到如何定義屬性，以及如何將控制項編譯為組件。如需呈現、定義屬性、維護狀態，以及實作複合控制項 (Composite Control) 的詳細資訊，請參閱開發自訂的 ASP.NET 伺服器控制項。

在逐步解說中，您會看到可以對控制項提供自訂工具箱圖示。您也會瞭解如何加入設計階段中繼資料，以自訂控制項的屬性瀏覽器支援。複雜控制項 (例如 GridView 控制項) 藉由使用在設計階段和執行階段提供不同使用者介面的視覺化設計工具類別，可進一步增進設計階段經驗。伺服器控制項的 ASP.NET 2.0 設計工具物件模型，與 ASP.NET 1.0 和 1.1 提供的模型大為不同。若要瞭解在 ASP.NET 2.0 中實作控制項的自訂設計工具類別，請參閱 ASP.NET 控制項設計工具概觀。

在 ASP.NET 2.0 中，伺服器控制項可以使用配接器 (Adapter) 類別，定義用戶端瀏覽器或裝置的不同行為。如需詳細資訊，請參閱開發 ASP.NET 伺服器控制項的配置器

不同的瀏覽器 (以及相同瀏覽器的不同版本) 支援的功能也不相同。ASP.NET 伺服器控制項會自動判斷要求 .aspx 網頁的瀏覽器，並格式化為該瀏覽器正確產生的 HTML 標記。不過，有些控制項功能無法在舊的瀏覽器上進行轉譯，因此最好是盡可能在各種瀏覽器類型上檢視網頁的輸出，確定網頁能照您要的方式顯示在所有瀏覽器上。如需詳細資訊，請參閱 ASP.NET Web 伺服器控制項和瀏覽器能力。

請參閱

其他資源

開發自訂的 ASP.NET 伺服器控制項