次の方法で共有


カスタム サーバー コントロール構文

[このドキュメントはプレビューのみを目的としており、以降のリリースで変更される可能性があります。プレースホルダーとして空白のトピックが含まれています。]

カスタム サーバー コントロール構文は、Web ページ、ユーザー コントロール、マスター ページなどの 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
    コントロールをプログラムによって参照できるようにするための一意の ID。

  • attributename
    属性の名前。コントロールのプロパティに対応します。

  • value
    属性 (プロパティ) に割り当てられた値。

  • eventname
    コントロールのイベント名。

  • eventhandlermethod
    コントロールに対する指定されたイベントを処理するよう定義されたイベント ハンドラー名。

解説

ASP.NET Web ページの本体に含まれるユーザー コントロールおよびカスタム サーバー コントロールを宣言するには、カスタム サーバー コントロール構文を使用します。 この構文が動作するには、対象となるコントロールがページまたは構成ファイルに登録されている必要があります (1 つのアプリケーションの全ページに存在する同じコントロールを登録する場合は、それを 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 Web ページでカスタム サーバー コントロールを登録および宣言する方法を次のコード例に示します。 コードの最初のセクションでは、Button クラスの派生としてパブリック クラスを作成します。 コードの次の部分は、カスタム ボタンをホストする Web ページです。 Web ページは @ Register ディレクティブを使用して、コントロールの名前空間を登録し、tagprefix 属性を設定します。 これにより、このコントロールはページにおいて、tagprefix 値とコントロールのクラス名をコロン (:) で区切って参照されます。

コード例を実行するには、このカスタム コントロールをコンパイルする必要があります。 それを明示的にコンパイルし、コンパイル済みのアセンブリを Web サイトの Bin フォルダーまたはグローバル アセンブリ キャッシュに配置できます。 サイトの App_Code フォルダーにソース コードを配置し、実行時に動的にコンパイルすることもできます。 コード例では動的コンパイルを使用しているので、ページの @ 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