チュートリアル : カスタム サーバー コントロールの開発と使用

  • [アーティクル]

更新 : 2007 年 11 月

このチュートリアルでは、ASP.NET カスタム サーバー コントロールを作成してコンパイルし、ページで使用する方法を示します。

このチュートリアルでは、次の作業を行う方法について説明します。

  • ASP.NET サーバー コントロールを作成します。

  • メタデータをコントロールおよびそのメンバに追加し、セキュリティおよびデザイン時の動作を制御します。

  • ASP.NET Web サイトの App_Code ディレクトリを使用して、手動でコンパイルせずにコントロールをテストします。

  • 構成ファイルとコントロールのアセンブリでタグ プリフィックスを指定します。

  • コントロールをアセンブリにコンパイルして Bin ディレクトリに追加します。

  • ビジュアル デザイナのツールボックスのアイコンとしてビットマップをコントロールのアセンブリに埋め込みます。

  • コンパイルされたコントロールをページで使用します。

Microsoft Visual Studio 2005 などのビジュアル デザイン ツールを使用すると、コントロールを簡単に開発できますが、カスタム コントロールの作成またはビルドに不可欠ではありません。コントロールは任意のテキスト エディタを使用して作成し、Windows Software Development Kit (SDK) の一部であるコンパイラを使用してコマンドラインからビルドできます。コントロールを作成する方法に関係なく、ビジュアル デザイナにおけるコントロールのデザイン時の外観と動作は同じになります。ページの開発者はコントロールをビジュアル デザイナのツールボックスに追加し、デザイン サーフェイスにドラッグし、プロパティ ブラウザでプロパティとイベントにアクセスできます。Visual Studio 2005 などのビジュアル デザイナでは、追加作業なしにカスタム コントロールに IntelliSense のサポートを追加できます。

サーバー コントロールの作成

ここで作成する WelcomeLabel というコントロールは、標準の Label コントロールと同様の簡単なコントロールです。WelcomeLabel クラスは WebControl から派生します。また、サイトのユーザーを歓迎するテキスト文字列をページに表示できる Text プロパティを定義します。ユーザーのブラウザから送信されるヘッダーにユーザー名がある場合、WelcomeLabel は、そのユーザー名をテキスト文字列に付加します。ユーザー名の取得の詳細については、User を参照してください。たとえば、Text プロパティの値に "Hello" を設定すると、WelcomeLabel は、ヘッダーにユーザー名があるかどうかに基づいて、"Hello, userName!" または "Hello!" をレンダリングします。

カスタム サーバー コントロールのコードを作成するには

  1. WelcomeLabel.cs または WelcomeLabel.vb というファイルを作成します。

  2. 次のコードをコントロールのソース ファイルに追加します。

    ' 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 というプロパティを定義し、ビューステートを使用してプロパティ値を格納します。ビューステートを使用すると、Text の値をポストバックの前後で永続化できます。各ポストバックでは、ページは再作成され、値がビューステートから復元されます。Text 値がビューステートに格納されていなければ、各ポストバックでこの値が既定値 (Empty) に設定されます。WebControl から継承される ViewState プロパティは、データ値を格納する辞書です。値は、String キーを使用して格納および取得されます。この場合、"Text" がキーとして使用されます。辞書の項目は Object 型になるため、その後にプロパティの型にキャストする必要があります。詳細については、「ASP.NET の状態管理の概要」を参照してください。

WelcomeLabel コントロールは、継承された RenderContents メソッドをオーバーライドして Text プロパティをレンダリングします。RenderContents メソッドに渡されるパラメータは HtmlTextWriter 型のオブジェクトで、タグおよびその他の HTML (および HTML バリアント) のマークアップのレンダリングのためのメソッドを含むユーティリティ クラスです。

WelcomeLabel は、文字列を連結してから Write メソッドを呼び出す代わりに、HtmlTextWriter オブジェクトの Write メソッドを連続的に呼び出します。HtmlTextWriter オブジェクトは出力ストリームに直接書き込むため、これによってパフォーマンスが向上します。文字列の連結では、文字列の作成に時間とメモリが必要で、その後にストリームに書き込みます。コントロールにレンダリングを実装するときは、このチュートリアルに記載されている方法に従ってください。

メモ :

一般に、コントロールが WebControl から派生し、1 つの要素をレンダリングする場合は、コントロールのタグの内部のコンテンツをレンダリングするために、Render メソッドではなく、RenderContents メソッドをオーバーライドする必要があります。WebControl の Render メソッドは、コントロールおよびそのスタイル属性のために開始タグをレンダリングした後に RenderContents を呼び出します。Render メソッドをオーバーライドしてコンテンツを記述すると、コントロールは WebControl の Render メソッドに組み込まれているスタイルをレンダリングするロジックが消失します。WebControl から派生するコントロールのレンダリングの詳細については、「Web コントロールのレンダリングの例」を参照してください。

WelcomeLabel に適用されている属性には、共通言語ランタイムとデザイン時ツールが使用するメタデータが含まれます。

クラス レベルでは、WelcomeLabel は次の属性でマークされます。

  • AspNetHostingPermissionAttribute は、コード アクセス セキュリティ属性です。これによって、JIT コンパイラは WelcomeLabel にリンクされているコードに AspNetHostingPermission アクセス許可が与えられているかどうかをチェックします。ASP.NET のすべてのパブリック クラスは、この属性でマークされています。AspNetHostingPermissionAttribute は、部分的に信頼された呼び出し元に対するセキュリティ チェックとしてコントロールに適用してください。

  • DefaultPropertyAttribute は、コントロールの既定のプロパティを指定するデザイン時の属性です。ビジュアル デザイナでデザイン サーフェイスのコントロールをクリックすると、プロパティ ブラウザは既定のプロパティを強調表示します。

  • ToolboxDataAttribute には、要素の書式指定文字列を指定します。ツールボックスでコントロールをダブルクリックするか、ツールボックスからデザイン サーフェイスにドラッグすると、その文字列がコントロールのマークアップになります。WelcomeLabel では、文字列は次のステートメントを生成します。

    <aspSample:WelcomeLabel runat="server"> </aspSample:WelcomeLabel>

WelcomeLabel コントロールは、WebControl 基本クラスから ParseChildrenAttribute 属性と PersistChildrenAttribute 属性の 2 つの属性を継承します。これらは、ParseChildren(true) と PersistChildren(false) として適用されます。この 2 つの属性と ToolboxDataAttribute 属性は共に動作して、子要素がプロパティとして解釈され、プロパティが属性として永続化されます。

WelcomeLabel の Text プロパティに適用される次の属性は、一般にコントロールのすべてのパブリック プロパティに適用する標準のデザイン時属性です。

  • BindableAttribute は、プロパティをデータに連結する意味があるかどうかを true または false によってビジュアル デザイナに指定します。たとえば Visual Studio 2005 では、Bindable(true) のマークが付いているプロパティは [データ連結] ダイアログ ボックスに表示されます。プロパティがこの属性でマークされていない場合、プロパティ ブラウザはこの値が Bindable(false) であると見なします。

  • CategoryAttribute には、ビジュアル デザイナのプロパティ ブラウザでプロパティを分類する方法を指定します。たとえば、Category("Appearance") を指定したプロパティは、プロパティ ブラウザのカテゴリ ビューの [表示] カテゴリに表示されます。プロパティ ブラウザのカテゴリは、既存のカテゴリに対応する文字列引数を指定するか、独自のカテゴリを作成できます。

  • DescriptionAttribute には、プロパティの簡単な説明を指定します。Visual Studio 2005 では、プロパティ ブラウザは選択したプロパティの説明を [プロパティ] ウィンドウの下部に表示します。

  • DefaultValueAttribute には、プロパティの既定値を指定します。この値は、プロパティ アクセサ (取得関数) が返す既定値と同じにする必要があります。Visual Studio 2005 では、ページの開発者は DefaultValueAttribute を使用して [プロパティ] ウィンドウにショートカット メニューを表示し、[リセット] をクリックしてこのプロパティを既定値に再設定できます。

  • LocalizableAttribute は、プロパティをローカライズする意味があるかどうかを true または false によってビジュアル デザイナに指定します。ビジュアル デザイナは、ローカライズするリソースをシリアル化する際に Localizable(true) のマークが付いているプロパティを含めます。ビジュアル デザイナは、コントロールに対してローカライズ可能なプロパティが要求された場合に、プロパティ値をカルチャに依存しないリソース ファイルまたはその他のローカライズ ソースに永続化します。

    メモ :

    ASP.NET バージョン 1.0 と 1.1 では、ASP.NET ローカライズ モデルが異なっていたために、LocalizableAttribute をカスタム サーバー コントロールに適用できませんでした。

コントロールおよびそのメンバに適用されるデザイン時の属性は、実行時のコントロールの機能に影響しませんが、コントロールをビジュアル デザイナで使用する際の操作性が向上します。サーバー コントロールのデザイン時、解析時、および実行時の属性の完全な一覧は、「カスタム サーバー コントロールのメタデータ属性」にあります。

コンパイルせずに App_Code ディレクトリを使用してコントロールをテストする

ASP.NET の動的コンパイル機能を使用すると、コントロールをアセンブリにコンパイルせずにページのコントロールをテストできます。ASP.NET は、ASP.NET Web サイトのルートの App_Code ディレクトリに格納されているコードを動的にコンパイルします。App_Code のソース ファイルにあるクラスには、手動でアセンブリにコンパイルせずにページからアクセスできます。コントロールのソース ファイルを App_Code ディレクトリに格納すると、コントロールのコードに対する変更は、コントロールを使用するページに即座に反映されます。

メモ :

App_Code ディレクトリは、ASP.NET 1.0 および 1.1 では使用できなかった新しい機能です。コントロールの初期テストに App_Code ディレクトリを使用するかどうかは任意です。次の「コントロールのアセンブリへのコンパイル」で説明されているように、サーバー コントロールのビルドの主な手順は以前のバージョンと同じです。

ASP.NET Web サイトと App_Code ディレクトリを作成するには

  1. ServerControlsTest という Web サイトを作成します。このサイトは、IIS で ServerControlsTest という仮想ディレクトリとして作成できます。IIS の仮想ディレクトリの作成と構成の詳細については、「方法 : IIS 5.0 および 6.0 内で仮想ディレクトリを作成および構成する」を参照してください。

  2. この Web サイトのルート ディレクトリ (または Web アプリケーション ルート) の直下に App_Code ディレクトリを作成します。

  3. App_Code ディレクトリにコントロールのソース ファイル (WelcomeLabel.cs または WelcomeLabel.vb) をコピーします。

タグ プリフィックスの作成

タグ プリフィックスは、コントロールを宣言によってページに作成する場合にコントロールの型名の前に記述される <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 ディレクティブに慣れているユーザーは、以前の Register ディレクティブにあったコントロールのアセンブリの名前を指定する assembly 属性がないことがわかります。assembly 属性がないと、ASP.NET はアセンブリが App_Code ディレクトリのソース ファイルから動的にコンパイルされると見なします。

タグ プリフィックス/名前空間のマッピングは、.aspx の各ページで @ Register ディレクティブを使用して指定する代わりに、Web.config ファイルで指定することもできます。この方法は、Web アプリケーションの複数のページでカスタム コントロールを使用する場合に便利です。マップするタグ プリフィックスを Web.config ファイルで指定する方法については、次の手順で説明します。

Web.config ファイルにタグ プリフィックスのマッピングを追加するには

  1. Web サイトのルート ディレクトリに 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 ファイルに存在しない場合は、前述した処理手順に示した要領でこれらの要素を作成します。

    メモ :

    タグ プリフィックスのエントリは、system.web セクションの下の pages セクションの下の controls セクションの子にする必要があります。

構成ファイルでタグ プリフィックスのマッピングを指定すると、Web サイトの任意のページで WelcomeLabel コントロールを <aspSample:WelcomeLabel /> として宣言して使用できます。

メモ :

構成ファイルのタグ プリフィックスのエントリは、ASP.NET 2.0 の新しい機能です。ASP.NET 1.0 および 1.1 におけるタグ プリフィックスのマッピングは、カスタム コントロールを使用する各ページの @ Register ディレクティブで指定していました。

コントロールを使用するページの作成

カスタム コントロールを使用するページを作成するには

  1. Web サイトに 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" runat="server">
    <title>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" runat="server">
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
          runat="server" 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" runat="server">
    <title>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" runat="server">
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
          runat="server" 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 基本クラスから継承してこの 2 つプロパティおよびその他のスタイルに関連するプロパティを取得しています。さらに、WelcomeLabel では、追加作業なしにスキンを割り当て、特定のテーマを組み込むことができます。

コントロールのアセンブリへのコンパイル

App_Code ディレクトリによって、コンパイルせずにコントロールをテストできますが、他の開発者にオブジェクト コードとしてコントロールを配布する場合はコンパイルする必要があります。また、コンパイルしてアセンブリを生成しなければ、コントロールをビジュアル デザイナのツールボックスに追加することはできません。

コントロールをアセンブリにコンパイルするには

  1. 次の手順を実行して、コンピュータの Windows の PATH 環境変数に .NET Framework のインストール パスを含めます。

    1. Windows で、[マイ コンピュータ] アイコンを右クリックし、[プロパティ] をクリックします。次に、[詳細設定] タブで、[環境変数] をクリックします。

    2. [システム環境変数] の一覧の Path 変数をダブルクリックします。

    3. [変数値] ボックスで、既存の値の最後にセミコロン (;) を追加し、各自の .NET Framework のインストール パスを入力します。通常の場合、.NET Framework は Windows のインストール ディレクトリ (\Microsoft.NET\Framework\versionNumber) にインストールされます。

    4. [OK] をクリックしてダイアログ ボックスを閉じます。

  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 オプションにはこのアセンブリにリンクするアセンブリを列挙します。

この例が独立して動作できるように、このチュートリアルではコントロールを 1 つだけ使用してアセンブリを作成しています。.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 ファイルでタグ プリフィックスを指定する方法については以前に説明しました。コントロールにアセンブリ レベルの 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 ページでのコンパイルされたカスタム コントロールの使用

カスタム コントロールのコンパイル済みバージョンをテストするには、コントロールのアセンブリを Web サイトでページからアクセスできるようにする必要があります。

コントロールのアセンブリを Web サイトからアクセスできるようにするには

  1. Web サイトのルートに Bin ディレクトリを作成します。

  2. Bin ディレクトリにコントロールのアセンブリ (Samples.AspNet.CS.Controls.dll または Samples.AspNet.VB.Controls.dll) をコピーします。

  3. App_Code ディレクトリからコントロールのソース ファイルを削除します。

    ソース ファイルを削除しないと、コントロールの型はコンパイルしたアセンブリと、ASP.NET で動的に生成されたアセンブリの両方に存在することになります。その結果、コントロールを読み込むときにあいまいな参照が発生し、そのコントロールを使用しているページでコンパイラ エラーが生成されます。

このチュートリアルで作成したアセンブリは、Web サイトのページでコントロールを使用するために ASP.NET Web サイトの Bin ディレクトリに格納する必要があるためプライベート アセンブリと呼ばれます。他のアプリケーションは、アセンブリのコピーをインストールしない限り、このアセンブリにアクセスすることはできません。共有された Web ホスト アプリケーションのためのコントロールを作成する場合は、一般にプライベート アセンブリに各自のコントロールをパッケージします。ただし、専用のホスト環境で使用するコントロールを作成する場合、または ISP がすべての顧客に提供する一連のコントロールを作成する場合は、グローバル アセンブリ キャッシュにインストールする厳密な名前が付けられた共有のアセンブリでコントロールをパッケージする必要があります。詳細については、「アセンブリとグローバル アセンブリ キャッシュの使用」を参照してください。

次に、Web.config に作成したタグ プリフィックスのマッピングを変更してコントロールのアセンブリ名を指定する必要があります。

Web.config のタグ プリフィックスのマッピングを変更するには

  • Web.config ファイルを編集し、addtagPrefix 要素に assembly 属性を追加します。

    <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 属性に、コントロールが含まれるアセンブリ名を指定します。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 カスタム サーバー コントロールを開発してページで使用する方法を示しました。また、プロパティを定義し、コントロールをアセンブリにコンパイルする方法についても説明しました。レンダリング、プロパティの定義、状態の維持、および複合コントロールの実装の詳細については、「ASP.NET カスタム サーバー コントロールの開発」を参照してください。

このチュートリアルでは、コントロールにカスタム ツールボックス アイコンを提供する方法について説明しました。また、デザイン時にメタデータを追加してコントロールのプロパティ ブラウザのサポートをカスタマイズする方法についても学びました。GridView コントロールなどの複雑なコントロールでは、デザイン時と実行時に異なるユーザー インターフェイスを提供するビジュアル デザイナのクラスを使用することによって、デザイン時の操作性を向上できます。サーバー コントロールのための ASP.NET 2.0 デザイナのオブジェクト モデルは、ASP.NET 1.0 および 1.1 が提供するモデルと大きく異なります。ASP.NET 2.0 でコントロールのためのカスタム デザイナのクラスの実装については、「ASP.NET コントロール デザイナの概要」を参照してください。

ASP.NET 2.0 のサーバー コントロールでは、クライアント ブラウザとアダプタのクラスを使用するデバイス用に異なる動作を定義できます。詳細については、「ASP.NET サーバー コントロールのアダプタの開発」を参照してください。

種類の異なるブラウザ、または同一種類であってもバージョンの異なるブラウザでは、サポートする機能がそれぞれ異なっています。ASP.NET サーバー コントロールは、.aspx ページを要求したブラウザを自動的に判別し、生成する HTML マークアップをブラウザに合わせて適切に書式化します。ただし、以前のバージョンのブラウザでは、コントロールの一部の機能が表示されない場合があります。したがって、できるだけ多くのブラウザ上でページ出力を確認し、目的のページが意図したとおりに表示されるかどうかを確認することをお勧めします。詳細については、「ASP.NET Web サーバー コントロールとブラウザの機能」を参照してください。

参照

その他の技術情報

ASP.NET カスタム サーバー コントロールの開発