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

[アーティクル]
05/27/2012

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

カスタムサーバーコントロール構文は、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

次の方法で共有

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

属性

解説

使用例

参照

概念

その他のリソース

次の方法で共有

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

属性

解説

使用例

参照

概念

その他のリソース

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