自定义服务器控件语法

  • 项目

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

自定义服务器控件语法用于将用户控件和自定义服务器控件声明为 ASP.NET 应用程序文件中的标记元素，包括网页、用户控件和母版页。 此语法几乎与用于声明所有 ASP.NET 服务器控件的语法相同，其中的差别仅在于：对于自定义和用户控件，您通常会声明一个唯一的标记前缀和一个与您的控件相对应的标记名称。

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

特性

  • tagprefix
    用于页面上的标记元素的完全限定命名空间的别名。 该别名的值是任意值，但它提供一种简写方法，以将自定义控件或用户控件的标记与 ASP.NET 文件中声明的其他标记元素的命名空间相关联。

  • tagname
    对于自定义控件，tagname 引用 ASP.NET 将会为其创建运行时实例的类型的名称。 对于用户控件，tagname 映射到定义该用户控件的关联的源文件，而该源文件又定义 ASP.NET 为其创建一个实例的类型。

  • id
    启用对控件的编程引用的唯一标识符。

  • attributename
    与控件上的属性相对应的特性的名称。

  • value
    分配给特性（属性）的值。

  • eventname
    控件中的事件的名称。

  • eventhandlermethod
    定义的用来处理控件的指定事件的事件处理程序的名称。

备注

使用自定义服务器控件语法声明 ASP.NET 网页正文内的用户控件和自定义服务器控件。 要使此语法正常工作，必须在页上或配置文件中注册控件（可以通过将控件添加到 Web.config 文件的 <controls> 来在应用程序的所有页上注册控件）。 可以通过使用 @ Register 指令来在单个页上注册控件。

用户或自定义控件的元素的开始标记必须包括 runat="server" 特性/值对。 若要启用控件的编程引用，您可以选择为 id 特性指定唯一值。

在用户服务器控件或自定义服务器控件上创作的任何属性都可以在服务器控件的开始标记中以声明的方式公开。 只要将该属性声明为特性并为其赋值即可。 例如，如果您创建一个具有 width 属性的自定义文本框控件，那么在控件的开始标记中声明 width="50" 会将服务器控件的显示宽度设置为 50 个像素。

在某些情况下，特性可能是具有自己的属性的对象。 在这种情况下，请在声明中包含属性名。 例如，如果您创建一个包含 font 特性的自定义文本框控件，那么该特性可以包含一个 name 属性。 然后，您可以在服务器控件的开始标记中将该属性声明为 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 类派生的公共类。 代码的第二部分是承载自定义按钮的网页。 请注意，该网页使用 @ Register 指令注册控件的命名空间并设置 tagprefix 特性。 然后通过使用 tagprefix 值和控件的类名称（二者之间使用冒号 (:) 分隔）在页中引用该控件。

必须编译此自定义控件，代码示例才能运行。 可以显式编译源代码，并将结果程序集放在网站的 Bin 文件夹或全局程序集缓存中。 另外，也可将源代码放入站点的 App_Code 文件夹中，源代码将在运行时在此文件夹中进行动态编译。 此代码示例使用动态编译，这也是页中的 @ Register 指令无需声明 Assembly 特性的原因（因为源在运行时进行动态编译）。 有关演示如何编译的演练，请参见Walkthrough: Developing and Using a Custom Server Control。

安全说明安全说明

该示例具有一个文本框，用于接受用户输入，这是一个潜在的安全威胁。默认情况下，ASP.NET 网页验证用户输入是否不包括脚本或 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