カスタム サーバー コントロールのメタデータ属性
更新 : 2007 年 11 月
メタデータ属性は、デザイン ツール、ASP.NET ページ パーサー、ASP.NET ランタイム、および共通言語ランタイムが使用する情報を提供するためにサーバー コントロールおよびそのメンバに適用されます。デザイン時属性は、ビジュアル デザイナでコントロールを使用する際のデザイン時の操作性を向上します。デザイン時専用の属性は、ページ要求におけるコントロールの機能には影響しません。コントロールの解析時属性は、ページ内のコントロールの宣言構文を読み取るときに ASP.NET ページ パーサーが使用します。解析時属性と実行時属性は、ページ内のコントロールの動作に不可欠です。
ここでは、コントロールおよびそのパブリック プロパティとイベントに一般的に適用するメタデータ属性について説明します。
コントロールに適用される属性
属性 |
例 |
|---|---|
AspNetHostingPermissionAttribute JIT コンパイル時コード アクセス セキュリティ属性。 コントロールにリンクするコードには、適切なセキュリティ アクセス許可を確保する必要があります。Control クラスは、次の 2 つの JIT コンパイル時コード アクセス セキュリティ属性によってマークされます。 AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal) および AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal) 最初の属性はコントロールに適用する必要がありますが、2 番目の属性は継承が推移的で、派生したクラスでも有効になるため、適用する必要がない場合もあります。詳細については、「SecurityAction」を参照してください。 |
[AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)] 「チュートリアル : カスタム サーバー コントロールの開発と使用」の WelcomeLabel のサンプル コントロールに適用されます。 |
|
解析時属性。 カスタム コントロール ビルダをコントロールに関連付けます。この属性は、ページ パーサーがコントロールの宣言構文を解析するために使用する既定のロジックをカスタム コントロール ビルダを使用して変更する場合のみ適用する必要があります。コントロール内のタグの内容がプロパティまたは子コントロールに対応するかどうかのみを指定する場合は、カスタム コントロール ビルダの代わりに ParseChildrenAttribute (この表の後の説明を参照) を使用します。 |
[ControlBuilder(typeof(MyControlBuilder))] |
|
デザイン時と実行時の属性。 コントロールの既定値として使用するプロパティを指定します。この属性を適用すると、コントロールを実行時クエリのパラメータとして使用でき、ControlParameter オブジェクトが実行時に連結する既定値を定義できます。 |
[ControlValueProperty("Text")] |
|
デザイン時属性。 ビジュアル デザイナのコントロールの既定のイベントを指定します。多くのビジュアル デザイナでは、デザイン サーフェイスのコントロールをダブルクリックすると、カーソルが既定のイベントのイベント ハンドラに配置された状態でコード エディタが開きます。 |
[DefaultEvent("Submit")] 「複合 Web コントロールの例」の Register のサンプル コントロールに適用されます。 |
|
デザイン時属性。 ビジュアル デザイナのデザイン サーフェイスでコントロールを選択すると、この属性に指定されるプロパティがプロパティ ブラウザで強調表示されます。 |
[DefaultProperty("Text")] 「チュートリアル : カスタム サーバー コントロールの開発と使用」の WelcomeLabel のサンプル コントロールに適用されます。 |
|
デザイン時属性。 コントロールに関連付けるデザイナのクラスを指定します。コントロール デザイナのクラスによって、ビジュアル デザイナのデザイン サーフェイスにおける関連付けられたコントロールの外観と動作が決まります。 |
[Designer(typeof(SimpleCompositeControlDesigner))] 「チュートリアル : Web サーバー コントロール用の基本的なコントロール デザイナの作成」のサンプル コントロールに適用されます。 |
|
解析時属性。 コントロールのタグ内の内容がプロパティまたは子コントロールに対応するかどうかを指定します。Control クラスには、ページ パーサーがコントロールのタグ内の内容を子コントロールとして解釈することを意味する ParseChildren(false) のマークが付けられます。WebControl クラスには、ページ パーサーがコントロールのタグ内の内容をプロパティとして解釈することを意味する ParseChildren(true) のマークが付けられます。この属性は、WebControl クラスの ParseChildrenAttribute 属性で指定されているロジックを変更する場合のみ適用する必要があります。 |
[ParseChildren(true, "Contacts")] 「Web コントロールのコレクション プロパティの例」のQuickContacts のサンプル コントロールに適用されます。 |
|
デザイン時属性。 コントロールをページで宣言して使用する場合、ビジュアル デザイナがコントロールのタグ内のプロパティまたは子コントロールを永続化する必要があるかどうかを指定します。Control クラスには、デザイナがコントロールのタグ内の子コントロールを永続化することを意味する PersistChildren(true) のマークが付けられます。WebControl クラスには、デザイナがコントロールのタグ内のプロパティを属性として永続化することを意味する PersistChildren(false) のマークが付けられます。 |
[PersistChildren(false)] WebControl クラスに適用され、このクラスから派生するほとんどのコントロールに適しています。ただし、タグ内の子コントロールを永続化する Panel などのコンテナ コントロールには、PersistChildren(true) と ParseChildren(false) でマークが付けられます。 |
|
解析時属性。 コントロールにテーマまたはコントロール スキンを適用できるかどうかを指定します。コントロール型がテーマを適用できないと指定されている場合、このコントロールのすべてのメンバについてもテーマによる影響はありません。 |
[Themeable(false)] コントロールとそのすべてのメンバにテーマまたはコントロール スキンが影響しないようにするには、前の例に示されている属性を適用します。 |
|
デザイン時属性。 コントロールをツールボックスから作成する場合、ビジュアル デザイナがタグのために作成するマークアップの書式を指定します。 |
[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"] 「チュートリアル : カスタム サーバー コントロールの開発と使用」の WelcomeLabel のサンプル コントロールに適用されます。 |
|
デザイン時属性。 ビジュアル デザイナがツールボックスにコントロールまたはコンポーネントを表示するかどうかを指定します。既定では、コントロールは常にツールボックスに表示されます。これは、テンプレート プロパティの所有者などのツールボックスに表示しないコントロールのみに適用する必要があります。 |
[ToolboxItem(false)] 「テンプレート サーバー コントロールの例」の TemplateOwner コントロールに適用されます。 |
|
デザイン時属性。 検証コントロールがチェックするプロパティの名前を指定します。これは通常、TextBox コントロールの Text プロパティなどのように、ユーザーが実行時に値を提供するプロパティです。ビジュアル デザイナで検証コントロールのターゲットを選択するためのダイアログ ボックスには、ページのコントロールの ValidationPropertyAttribute によって指定されるプロパティが表示されます。 |
[ValidationProperty("Text")] |
パブリック プロパティに適用される属性
属性 |
例 |
|---|---|
|
デザイン時属性。 プロパティにデータを連結する意味があるかどうかを指定します。ビジュアル デザイナでは、コントロールに連結できるプロパティをプロパティ ブラウザのダイアログ ボックスに表示できます。たとえば Visual Studio では、連結できるプロパティは [データ連結] ダイアログ ボックスに表示されます。プロパティがこの属性でマークされていない場合、プロパティ ブラウザはこの値が Bindable(false) であると見なします。 |
[Bindable(true)] 「チュートリアル : カスタム サーバー コントロールの開発と使用」の WelcomeLabel サンプル コントロールの Text プロパティに適用されます。 |
|
デザイン時属性。 プロパティをビジュアル デザイナのプロパティ ブラウザに表示するかどうかを指定します。プロパティ ブラウザに表示しないプロパティには、Browsable(false) を適用します。この属性によってマークされていないプロパティは、既定値の Browsable(true) であると見なされます。 |
[Browsable(false)] 「テンプレート サーバー コントロールの例」の VacationHome サンプル コントロールの Template プロパティに適用されます。 |
|
デザイン時属性。 ビジュアル デザイナのプロパティ ブラウザでプロパティを分類する方法を指定します。たとえば、Category("Appearance") を指定したプロパティは、プロパティ ブラウザのカテゴリ ビューの Appearance カテゴリに表示されます。プロパティ ブラウザのカテゴリは、既存のカテゴリに対応する文字列引数を指定するか、または独自のカテゴリを作成できます。 |
[Category("Appearance")] 「チュートリアル : カスタム サーバー コントロールの開発と使用」の WelcomeLabel サンプル コントロールの Text プロパティに適用されます。 |
|
デザイン時属性。 プロパティの既定値を指定します。この値は、プロパティ アクセサ (取得関数) が返す既定値と同じにする必要があります。Visual Studio などの一部のビジュアル デザイナで DefaultValueAttribute 属性を使用すると、ショートカット メニューの [リセット] コマンドによってプロパティを既定値にリセットできます。 |
[DefaultValue("")] 「チュートリアル : カスタム サーバー コントロールの開発と使用」の WelcomeLabel サンプル コントロールの Text プロパティに適用されます。 |
|
デザイン時属性。 プロパティの簡単な説明を指定します。Visual Studio などのビジュアル デザイナでは、プロパティ ブラウザは選択したプロパティの説明をウィンドウの下部に表示します。 |
[Description("The welcome message text.")] 「チュートリアル : カスタム サーバー コントロールの開発と使用」の WelcomeLabel サンプル コントロールの Text プロパティに適用されます。 |
DesignerSerializationVisibilityAttribute デザイン時属性。 デザイン時に設定されるプロパティまたはその内容 (サブプロパティまたはコレクション項目など) をシリアル化するかどうかを指定します。属性のコンストラクタの引数は、DesignerSerializationVisibility 列挙の値です。この属性が適用されない場合は、既定値の Visible が使用され、プロパティの値がシリアル化されます。 |
[DesignerSerializationVisibility (DesignerSerializationVisibility.Content)] 「サーバー コントロールのプロパティの例」の Book サンプル コントロールの Author プロパティに適用されます。 |
|
デザイン時属性。 カスタムの UITypeEditor エディタをプロパティまたはプロパティ型に関連付けます。この属性をプロパティ型に適用する場合、その型のプロパティに適用する必要はありません。 |
[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))] 「Web コントロールのコレクション プロパティの例」の QuickContacts サンプル コントロールの Contacts プロパティに適用されます。 |
|
デザイン時属性。 プロパティ名がソース エディタの IntelliSense 一覧に記載するかどうかを指定します。この属性は、メソッドとイベントにも適用できます。属性のコンストラクタの引数は、EditorBrowsableState 列挙の値です。この属性が適用されない場合は、既定値の Always が使用されます。 |
[EditorBrowsableAttribute (EditorBrowsableState.Never)] 前の例の属性を適用して IntelliSense のメンバを隠します。 |
|
デザイン時と解析時の属性。 プロパティがデバイスとブラウザのフィルタ処理に参加できるかどうかを指定します。フィルタ処理を使用すると、単一のコントロールの宣言によって異なるブラウザに異なるプロパティ値を指定できます。たとえば次の構文のように、フィルタ処理を使用して Label コントロールの Text プロパティに異なる値を設定できます。 "UP" と "IE" はブラウザのフィルタです。この属性が適用されない場合は、既定値の Filterable(true) が使用されます。 |
[Filterable(false)] 前の例の属性を適用して、デバイスとブラウザのフィルタ処理からプロパティを除外します。 |
|
デザイン時属性。 プロパティをローカライズする意味があるかどうかを指定します。Localizable(true) のマークが付いているプロパティの値は、リソース ファイルに格納されます。この属性が適用されない場合は、既定値の Localizable(false) が使用されます。 |
[Localizable(true)] 「チュートリアル : カスタム サーバー コントロールの開発と使用」の WelcomeLabel サンプル コントロールの Text プロパティに適用されます。 |
|
デザイン時属性。 プロパティ ブラウザで行ったサブプロパティへの変更を親プロパティに伝達するように指定します。 |
[NotifyParentProperty(true)] 「サーバー コントロールのプロパティの例」で定義されている Author 型の FirstName、LastName、および MiddleName の各プロパティに適用されます。 |
|
デザイン時属性。 プロパティをコントロールのタグの属性として永続化するか、またはコントロールのタグ内の入れ子になったコンテンツにするかを指定します。属性のコンストラクタの引数は、PersistenceMode 列挙の値です。 |
[PersistenceMode(PersistenceMode.InnerProperty)] 「サーバー コントロールのプロパティの例」の Book サンプル コントロールの Author プロパティに適用されます。 |
|
デザイン時と解析時の属性。 ITemplate インターフェイスを返すプロパティの名前付けコンテナの型を指定します。 |
[TemplateContainer(typeof(CustomTemplateContainer))] ITemplate プロパティが CustomTemplateContainer クラスによって表現されるように指定するには、前の例に示されている属性を適用します。 |
|
デザイン時と解析時の属性。 テンプレート プロパティに対して作成できるインスタンスを 1 つのみとするか複数とするかを指定します。テンプレート プロパティに TemplateInstanceAttribute 属性が指定されていない場合、既定値は複数のインスタンスになります。 |
[TemplateInstance(TemplateInstance.Single)] 作成できるテンプレート プロパティのインスタンスを 1 つだけにする場合は、前の例に示されている属性を適用します。 |
|
解析時属性。 コントロール メンバにテーマまたはコントロール スキンを適用できるかどうかを指定します。既定では、コントロール型にテーマを適用できるようになっている場合、そのコントロールによって公開されているすべてのプロパティにもテーマを適用できます。 |
[Themeable(false)] コントロール メンバにテーマまたはコントロール スキンが影響しないようにする場合は、前の例に示されている属性を適用します。 |
|
デザイン時、解析時、および実行時の属性。 型コンバータをプロパティまたはプロパティ型に関連付けます。型コンバータは、文字列表現を指定された型に変換し、その逆の変換も行います。 |
[TypeConverter(typeof(AuthorConverter))] 「サーバー コントロールのプロパティの例」で定義されている Author 型に適用されます。 |
|
デザイン時と実行時の属性。 文字列プロパティが URL 値を表すように指定します。これによって、URL ビルダをプロパティに関連付けることができます。 |
[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)] ASP.NET ファイルに特定のファイル フィルタを設定し、絶対パスと相対パスを使用できるようにします。 |
イベントのメンバに適用する属性
イベントのメンバに適用する主な属性は、BrowsableAttribute、CategoryAttribute、および DescriptionAttribute の 3 つのデザイン時属性です。この 3 つの属性は、上の表に説明されているように、プロパティにも適用されます。コード例の詳細については、「複合 Web コントロールの例」の Register サンプル コントロールの Submit イベントを参照してください。
参照
処理手順
チュートリアル : カスタム サーバー コントロールの開発と使用