自訂伺服器控制項語法

發行項
05/28/2012

自訂伺服器控制項語法的用途，是將使用者控制項和自訂伺服器控制項宣告為 ASP.NET 應用程式檔案 (包括 Web 網頁、使用者控制項和主版頁面）中的標記項目。除了對於自訂和使用者控制項，您通常會宣告唯一的標記前置詞和對應於控制項的標記名稱以外，這套語法與用來宣告所有 ASP.NET 伺服器控制項的語法幾乎完全相同。

<tagprefix:tagname id="OptionalID"
   attributename="value"
   eventname="eventhandlermethod"
   runat="server" />
OR
<tagprefix:tagname id="OptionalID"
   runat="server" />

屬性

tagprefix
在網頁上使用之標記項目的完整命名空間別名 (Alias)。雖然別名的值是任意的，卻提供了使自訂控制項或使用者控制項的標記與 ASP.NET 檔案所宣告的其他標記項目形成關聯的簡略方式。
tagname
對於自訂控制項，tagname 是指 ASP.NET 將會為其建立執行階段執行個體之型別的名稱。對於使用者控制項，tagname 則對應至定義使用者控制項的關聯資源檔，而該檔案則會定義 ASP.NET 為其建立執行個體的型別。
id
能以程式方式參考控制項的唯一識別項。
attributename
屬性 (Attribute) 的名稱，對應至控制項的屬性 (Property)。
value
指派給屬性的值。
eventname
控制項中事件的名稱。
eventhandlermethod
事件處理常式的名稱，定義用以處理控制項之指定事件。

備註

使用自訂伺服器控制項語法，宣告 ASP.NET 網頁主體內的使用者控制項和自訂伺服器控制項。如需使這項語法發揮作用，就必須在網頁或組態檔中註冊該控制項 (只要將控制項加入至 Web.config 檔的 <controls>，即可在應用程式的所有網頁上註冊該控制項)。您可以使用 @ Register 指示詞在個別的網頁上註冊控制項。

使用者或自訂控制項之項目的開頭標記，都必須包含 runat="server" 屬性/值組。若要啟用控制項的程式設計參考，您可以選擇性地對 id 屬性指定唯一的值。

您在使用者或自訂伺服器控制項上撰寫的任何屬性，都可以在伺服器控制項的開頭標記中以宣告方式公開。只需要將屬性 (Property) 宣告為一項屬性 (Attribute) 並且指派一個值給它。例如，假設您要建立具有 width 屬性的自訂文字方塊控制項，請在控制項的開頭標記中宣告 width="50" ，就會將伺服器控制項的顯示寬度設定為 50 個像素。

在某些情況下，屬性 (Attribute) 可以是擁有自己屬性 (Property) 的物件。這時，請在宣告中包含這個屬性 (Property) 的名稱。例如，如果您建立包含 font 屬性 (Attribute) 的自訂文字方塊控制項，此屬性 (Attribute) 就可以包含 name 屬性 (Property)。然後，您可以在伺服器控制項的開頭標記中將這個屬性 (Property) 宣告為 font-name="Arial"。如需開發具有屬性之自訂伺服器控制項的詳細資訊，請參閱 Server Control Simple Properties and SubProperties。

您可以對自訂伺服器控制項和使用者控制項宣告事件，就如同對任何 ASP.NET 伺服器控制項一樣的宣告方式。只要將屬性和值指定給伺服器控制項開頭標記中的事件繫結即可。如需撰寫支援事件之自訂伺服器控制項的詳細資訊，請參閱 Server Event Handling in ASP.NET Web Pages。

您可以使用和開發支援內嵌樣板的自訂伺服器控制項。如需如何在自訂伺服器控制項中宣告樣板的詳細資料，請參閱伺服器控制項內嵌樣板語法。若要瞭解如何撰寫支援內嵌樣板的自訂伺服器控制項，請參閱 How to: Create Templated ASP.NET User Controls。

範例

下列程式碼範例示範如何在 ASP.NET 網頁中註冊和宣告自訂伺服器控制項。程式碼的第一個區段會建立衍生自 Button 類別的公用類別。程式碼的第二個部分則是裝載自訂按鈕的 Web 網頁。請注意，Web 網頁使用 @ Register 指示詞註冊控制項的命名空間，並設定 tagprefix 屬性。然後在網頁中使用以冒號 (:) 分隔的 tagprefix 值和控制項的類別名稱來參考控制項。

如需執行程式碼範例，您必須編譯此自訂控制項。您可以明確編譯它，並將產生的組件放在網站的 [Bin] 資料夾或全域組件快取中。此外，您可以將原始程式碼放在網站的 [App_Code] 資料夾中，這樣就可以在執行階段進行動態編譯。這個程式碼範例使用動態編譯 (Compilation)，這就是網頁中的 @ Register 指示詞為何不需要宣告 Assembly 屬性的原因 (因為程式碼會在執行階段動態地進行編譯)。如需示範如何編譯的逐步解說，請參閱Walkthrough: Developing and Using a Custom Server Control。

安全性提示
這個範例有一個可接受使用者輸入的文字方塊，這可能會造成安全性威脅。ASP.NET Web 網頁預設會驗證使用者輸入，但不包含當中的指令碼或 HTML 項目。如需詳細資訊，請參閱Script Exploits Overview。

// A custom Button control to reference in the page.
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Security.Permissions
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

namespace Samples.AspNet.CS.Controls
{
  [AspNetHostingPermission(SecurityAction.Demand,
  Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class CustomButton : Button
  {
    public CustomButton()
    {
      this.Text = "Click Here";
    }
  }
}

<!-- A page that references the custom control. -->
<%@Page language="C#" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"  
    namespace="Samples.AspNet.CS.Controls" %>
    
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html>   
 <script runat="server">
     private void custButton_Click(Object sender, EventArgs e)
     {
       TextBox.BackColor = System.Drawing.Color.Green;
       TextBox.Text = "You clicked the button";
     }       
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton" 
         onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

' A custom Button control to reference in the page.
Imports System
Imports System.Collections
Imports System.ComponentModel
Imports System.Drawing
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.Configuration
Imports System.Data.Sql
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts

Namespace Samples.AspNet.VB.Controls

  <AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  <AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class CustomButton
    Inherits Button

    Public Sub New()
      Me.Text = "Click Here"
    End Sub

  End Class

End Namespace
<!-- A page that references the custom control. -->
<%@ Page Language="VB" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"
    namespace="Samples.AspNet.VB.Controls" %>

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

<html>   
 <script runat="server">
   Sub custButton_Click(ByVal sender As Object, _
    ByVal e As EventArgs)
     TextBox.BackColor = Drawing.Color.Green
     TextBox.Text = "You clicked the button."
   End Sub
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton" 
         onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

請參閱

概念

ASP.NET Web Page Syntax Overview

自訂伺服器控制項語法

屬性

備註

範例

請參閱

概念

其他資源