Metadatenattribute für benutzerdefinierte Serversteuerelemente
Aktualisiert: November 2007
Metadatenattribute werden auf Serversteuerelemente und ihre Member angewendet, um Information bereitzustellen, die von Designtools, dem ASP.NET-Seitenparser, der ASP.NET-Laufzeit und der Common Language Runtime verwendet werden. Entwurfszeitattribute erleichtern das Entwickeln zur Entwurfszeit, wenn der Seitenentwickler das Steuerelement in einem visuellen Designer verwendet. Entwurfszeitattribute haben keine Auswirkungen auf die Funktionalität eines Steuerelements während einer Seitenanforderung. Die Analysezeitattribute eines Steuerelements werden vom ASP.NET-Seitenparser beim Lesen der deklarativen Syntax des Steuerelements in einer Seite verwendet. Analysezeitattribute und Laufzeitattribute spielen für das Funktionieren eines Steuerelements in einer Seite eine wesentliche Rolle.
In diesem Thema werden die Metadatenattribute beschrieben, die häufig auf Steuerelemente und ihre öffentlichen Eigenschaften und Ereignisse angewendet werden.
Auf Steuerelemente angewendete Attribute
Attribut |
Beispiel |
|---|---|
AspNetHostingPermissionAttribute Codezugriffssicherheits-Attribut der JIT-Kompilierzeit. Stellt sicher, dass Code mit einer Verknüpfung zu einem Steuerelement über die entsprechenden Sicherheitsberechtigungen verfügt. Die Control-Klasse wird mit zwei Codezugriffssicherheit-Attributen der JIT-Kompilierzeit gekennzeichnet: AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal) und AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal). Das erste Attribut sollte auf das Steuerelement angewendet werden, wohingegen dies für das zweite Attribut nicht unbedingt zutrifft, da eine Vererbungsforderung transitiv ist und für abgeleitete Klassen aktiv bleibt. Weitere Informationen finden Sie unter SecurityAction. |
[AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)] Angewendet auf das WelcomeLabel-Beispielsteuerelement in Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements. |
|
Analysezeitattribut. Ordnet dem Steuerelement einen benutzerdefinierten Steuerelementgenerator zu. Sie müssen dieses Attribut nur anwenden, wenn Sie mit einem benutzerdefinierten Steuerelementgenerator die Standardlogik, die der Seitenparser zum Analysieren der deklarativen Syntax des Steuerelements verwendet, ändern möchten. Wenn Sie lediglich angeben möchten, ob der Inhalt der Steuerelementtags den Eigenschaften oder untergeordneten Steuerelementen entspricht, sollten Sie keinen benutzerdefinierten Steuerelementgenerator verwenden. Setzen Sie stattdessen ParseChildrenAttribute ein (eine nähere Beschreibung erfolgt weiter unten in dieser Tabelle). |
[ControlBuilder(typeof(MyControlBuilder))] |
|
Entwurfszeitattribut und Laufzeitattribut. Gibt die Eigenschaft an, die als Standardwert für ein Steuerelement verwendet wird. Durch Anwenden dieses Attributs kann ein Steuerelement zur Laufzeit als Abfrageparameter verwendet werden. Es definiert den Standardwert, an den ein ControlParameter-Objekt zur Laufzeit gebunden wird. |
[ControlValueProperty("Text")] |
|
Entwurfszeitattribut. Gibt das Standardereignis für ein Steuerelement in einem visuellen Designer an. In vielen visuellen Designern öffnet sich in der Entwurfsoberfläche bei einem Doppelklick auf das Steuerelement durch den Seitenentwickler der Code-Editor, wobei der Cursor im Ereignishandler des Standardereignisses positioniert wird. |
[DefaultEvent("Submit")] Angewendet auf das Register-Beispielsteuerelement in Beispiel für ein zusammengesetztes Steuerelement. |
|
Entwurfszeitattribut. Die in diesem Attribut angegebene Eigenschaft wird im Eigenschaftenbrowser des visuellen Designers hervorgehoben, wenn der Seitenentwickler das Steuerelement in der Entwurfsoberfläche auswählt. |
[DefaultProperty("Text")] Angewendet auf das WelcomeLabel-Beispielsteuerelement in Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements. |
|
Entwurfszeitattribut. Gibt die Designerklasse an, die einem Steuerelement zugeordnet ist. Die Designerklasse eines Steuerelements ist für die Darstellung und das Verhalten des zugeordneten Steuerelements in der Entwurfsoberfläche eines visuellen Designers verantwortlich. |
[Designer(typeof(SimpleCompositeControlDesigner))] Angewendet auf die Beispielsteuerelemente in Exemplarische Vorgehensweise: Erstellen eines einfachen Steuerelement-Designers für ein Webserver-Steuerelement |
|
Analysezeitattribut. Gibt an, ob der Inhalt der Steuerelementtags den Eigenschaften oder untergeordneten Steuerelementen entspricht. Die Control-Klasse ist als ParseChildren(false) gekennzeichnet. Dies bedeutet, dass der Seitenparser den Inhalt der Steuerelementtags als untergeordnete Steuerelemente interpretiert. Die WebControl-Klasse ist als ParseChildren(true) gekennzeichnet. Dies bedeutet, dass der Seitenparser den Inhalt der Steuerelementtags als Eigenschaften interpretiert. Sie müssen dieses Attribut nur anwenden, wenn Sie die im ParseChildrenAttribute-Attribut angegebene Logik für die WebControl-Klasse ändern möchten. |
[ParseChildren(true, "Contacts")] Angewendet auf das QuickContacts-Beispielsteuerelement in Beispiel für eine Auflistungseigenschaft eines Webserversteuerelements. |
|
Entwurfszeitattribut. Gibt an, ob der visuelle Designer die untergeordneten Steuerelemente oder Eigenschaften in einem Steuerelementtag beibehalten soll, wenn das Steuerelement in der Seite deklarativ verwendet wird. Die Control-Klasse ist als PersistChildren(true) gekennzeichnet. Dies bedeutet, dass der Designer die untergeordneten Steuerelemente in den Steuerelementtags beibehält. Die WebControl-Klasse ist als PersistChildren(false) gekennzeichnet. Dies bedeutet, dass der Designer Eigenschaften als Attribute in den Steuerelementtags beibehält. |
[PersistChildren(false)] Angewendet auf die WebControl-Klasse und geeignet für die meisten von dieser Klasse abgeleiteten Steuerelemente. Containersteuerelemente wie Panel, die untergeordnete Steuerelemente in ihren eigenen Tags beibehalten, sind als PersistChildren(true) und ParseChildren(false) gekennzeichnet. |
|
Analysezeitattribut. Gibt an, ob sich Designs oder Steuerelementdesigns auf ein Steuerelement auswirken können. Wenn ein Steuerelement eine entsprechende Kennzeichnung aufweist, dass Designs nicht auf das Steuerelement angewendet werden können, wirken sich Designs auch auf keines der Member des Steuerelements aus. |
[Themeable(false)] Wenden Sie das Attribut aus dem vorherigen Beispiel an, wenn sich Designs oder Steuerelementdesigns nicht auf ein Steuerelement und auf keines seiner Member auswirken sollen. |
|
Entwurfszeitattribut. Gibt das Format des Markups an, das beim Erstellen des Steuerelements über die Toolbox vom visuellen Designer für das Tag erstellt wird. |
[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"] Angewendet auf das WelcomeLabel-Beispielsteuerelement in Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements. |
|
Entwurfszeitattribut. Gibt an, ob ein visueller Designer in der Toolbox ein Steuerelement oder eine Komponente anzeigt. Standardmäßig werden in der Toolbox immer Steuerelemente angezeigt. Wenden Sie das Attribut nur auf ein Steuerelement an (z. B. den Besitzer einer Vorlageneigenschaft), das nicht in der Toolbox angezeigt werden soll. |
[ToolboxItem(false)] Angewendet auf das TemplateOwner-Steuerelement in Beispiel für ein vorlagenbasiertes Serversteuerelement. |
|
Entwurfszeitattribut. Gibt den Namen der Eigenschaft an, die von einem Validierungssteuerelement überprüft wird. Dabei handelt es in der Regel um eine Eigenschaft, deren Wert von Benutzern zur Laufzeit bereitgestellt wird. Ein Beispiel dafür ist die Text-Eigenschaft eines TextBox-Steuerelements. In einem visuellen Designer werden dem Seitenentwickler im Dialogfeld zum Auswählen des Ziels eines Validierungssteuerelements Eigenschaften angezeigt, die über ValidationPropertyAttribute von Steuerelementen auf der Seite angegeben wurden. |
[ValidationProperty("Text")] |
Auf öffentliche Eigenschaften angewendete Attribute
Attribut |
Beispiel |
|---|---|
|
Entwurfszeitattribut. Gibt an, ob das Binden von Daten an eine Eigenschaft von Bedeutung ist. In einem visuellen Designer kann der Eigenschaftenbrowser die bindungsfähigen Eigenschaften eines Steuerelements in einem Dialogfeld anzeigen. (In Visual Studio werden bindungsfähige Eigenschaften beispielsweise im Dialogfeld Datenbindungen angezeigt.) Wenn eine Eigenschaft nicht mit diesem Attribut gekennzeichnet ist, geht der Eigenschaftenbrowser vom Wert Bindable(false) aus. |
[Bindable(true)] Angewendet auf die Text-Eigenschaft des WelcomeLabel-Beispielsteuerelements in Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements. |
|
Entwurfszeitattribut. Gibt an, ob eine Eigenschaft im Eigenschaftenbrowser eines visuellen Designers angezeigt werden soll. Wenden Sie Browsable(false) auf eine Eigenschaft an, die nicht im Eigenschaftenbrowser angezeigt werden soll. Wenn das Attribut nicht mit diesem Attribut gekennzeichnet ist, geht der Eigenschaftenbrowser vom Standardwert Browsable(true) aus. |
[Browsable(false)] Angewendet auf die Template-Eigenschaft im VacationHome-Beispielsteuerelement in Beispiel für ein vorlagenbasiertes Serversteuerelement. |
|
Entwurfszeitattribut. Gibt an, wie die Eigenschaft im Eigenschaftenbrowser des visuellen Designers kategorisiert wird. Beispielsweise fordert Category("Appearance") den Eigenschaftenbrowser dazu auf, die Eigenschaft in der Kategorie Darstellung anzuzeigen, wenn der Seitenentwickler im Eigenschaftenbrowser die Kategorieansicht verwendet. Sie können ein Zeichenfolgenargument angeben, das einer vorhandenen Kategorie im Eigenschaftenbrowser entspricht, oder eine eigene Kategorie erstellen. |
[Category("Appearance")] Angewendet auf die Text-Eigenschaft des WelcomeLabel-Beispielsteuerelements in Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements. |
|
Entwurfszeitattribut. Gibt den Standardwert für eine Eigenschaft an. Dieser Wert sollte mit dem Standardwert identisch sein, der vom Eigenschaftenaccessor (Getter) zurückgegeben wird. In visuellen Designern wie Visual Studio kann der Seitenentwickler mit dem DefaultValueAttribute-Attribut mit dem Befehl Zurücksetzen im Kontextmenü einen Eigenschaftenwert auf den Standardwert zurücksetzen. |
[DefaultValue("")] Angewendet auf die Text-Eigenschaft des WelcomeLabel-Beispielsteuerelements in Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements. |
|
Entwurfszeitattribut. Enthält eine kurze Beschreibung der Eigenschaft. In visuellen Designern wie Visual Studio zeigt der Eigenschaftenbrowser die Beschreibung einer ausgewählten Eigenschaft in der Regel am unteren Rand des Fensters an. |
[Description("The welcome message text.")] Angewendet auf die Text-Eigenschaft des WelcomeLabel-Beispielsteuerelements in Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements. |
DesignerSerializationVisibilityAttribute Entwurfszeitattribut. Gibt an, ob zur Entwurfszeit festgelegte Eigenschaften oder deren Inhalte (untergeordnete Eigenschaften oder Auflistungselemente) serialisiert werden sollen. Das Argument des Attributkonstruktors ist ein Wert der DesignerSerializationVisibility-Enumeration. Wenn das Attribut nicht angewendet wird, gilt der Standardwert Visible, und der Wert der Eigenschaft wird serialisiert. |
[DesignerSerializationVisibility (DesignerSerializationVisibility.Content)] Angewendet auf die Author-Eigenschaft desBook-Beispielsteuerelements in Beispiel für die Eigenschaften eines Serversteuerelements. |
|
Entwurfszeitattribut. Ordnet einer Eigenschaft oder einem Eigenschaftentyp einen benutzerdefinierten UITypeEditor zu. Wenn dieses Attribut auf den Typ angewendet wird, muss es nicht auf die Eigenschaft des Typs angewendet werden. |
[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))] Angewendet auf die Contacts-Eigenschaft desQuickContacts-Beispielsteuerelements in Beispiel für eine Auflistungseigenschaft eines Webserversteuerelements. |
|
Entwurfszeitattribut. Gibt an, ob der Eigenschaftenname in der Liste IntelliSense des Quellcode-Editors angezeigt wird. Dieses Attribut kann auf Methoden und Ereignisse angewendet werden. Das Argument das Attributkonstruktors ist ein Wert der EditorBrowsableState-Enumeration. Wenn dieses Attribut nicht angewendet wird, gilt der Standardwert Always. |
[EditorBrowsableAttribute (EditorBrowsableState.Never)] Wenden Sie das im vorherigen Beispiel gezeigte Attribut an, um in IntelliSense einen Member auszublenden. |
|
Entwurfszeitattribut und Analysezeitattribut. Gibt an, ob eine Eigenschaft an der Gerätefilterung und an der Browserfilterung teilnehmen kann. Über das Filtern kann ein Seitenentwickler unterschiedliche Eigenschaftenwerte für verschiedene Browser innerhalb einer einzelnen Steuerelementdeklaration angeben. Beispielsweise kann ein Seitenentwickler über die Filterung verschiedene Werte für die Text-Eigenschaft eines Label-Steuerelements festlegen. Siehe dazu die folgende Syntax: "UP" und "IE" sind Browserfilter. Wenn dieses Attribut nicht angewendet wird, gilt der Standardwert Filterable(true). |
[Filterable(false)] Wenden Sie das im vorherigen Beispiel gezeigt Attribut an, um eine Eigenschaft von der Gerätefilterung und der Browserfilterung auszuschließen. |
|
Entwurfszeitattribut. Gibt an, ob das Lokalisieren einer Eigenschaft von Bedeutung ist. Wenn eine Eigenschaft mit Localizable(true) markiert ist, wird der Eigenschaftenwert in einer Ressourcendatei gespeichert. Wenn dieses Attribut nicht angewendet wird, gilt der Standardwert Localizable(false). |
[Localizable(true)] Angewendet auf die Text-Eigenschaft des WelcomeLabel-Beispielsteuerelements in Exemplarische Vorgehensweise: Entwickeln und Verwenden eines benutzerdefinierten Serversteuerelements. |
|
Entwurfszeitattribut. Gibt an, dass die in einem Eigenschaftenbrowser an einer untergeordneten Eigenschaft vorgenommenen Änderungen an die übergeordnete Eigenschaft weitergegeben werden sollen. |
[NotifyParentProperty(true)] Angewendet auf die Eigenschaften FirstName, LastName und MiddleName des in Beispiel für die Eigenschaften eines Serversteuerelements definierten Author-Typs. |
|
Entwurfszeitattribut. Gibt an, ob eine Eigenschaft als Attribut auf das Steuerelementtag oder als geschachtelter Inhalt in den Steuerelementtags beibehalten werden soll. Das Argument das Attributkonstruktors ist ein Wert der PersistenceMode-Enumeration. |
[PersistenceMode(PersistenceMode.InnerProperty)] Angewendet auf die Author-Eigenschaft desBook-Beispielsteuerelements in Beispiel für die Eigenschaften eines Serversteuerelements. |
|
Entwurfszeitattribut und Analysezeitattribut. Gibt den Typ des Namenscontainers für eine Eigenschaft an, die eine ITemplate-Schnittstelle zurückgibt. |
[TemplateContainer(typeof(CustomTemplateContainer))] Wenden Sie das Attribut aus dem vorherigen Beispiel an, um anzugeben, dass die ITemplate-Eigenschaft von der CustomTemplateContainer-Klasse dargestellt wird. |
|
Entwurfszeitattribut und Analysezeitattribut. Gibt an, ob eine Vorlageneigenschaft die Erstellung einzelner oder mehrerer Instanzen zulässt. Wenn eine Vorlageneigenschaft nicht mit dem TemplateInstanceAttribute-Attribut erweitert wird, werden standardmäßig mehrere Instanzen erstellt. |
[TemplateInstance(TemplateInstance.Single)] Wenden Sie das Attribut aus dem vorherigen Beispiel an, um anzugeben, dass nur eine einzige Instanz einer Vorlageneigenschaft erstellt werden kann. |
|
Analysezeitattribut. Gibt an, ob sich Designs oder Steuerelementdesigns auf einen Steuerelementmember auswirken können. Standardmäßig können auf alle von einem Steuerelement verfügbar gemachten Eigenschaften Designs angewendet werden, wenn auf den Steuerelementtyp selbst Designs angewendet werden können. |
[Themeable(false)] Wenden Sie das Attribut aus dem vorherigen Beispiel an, wenn sich Designs oder Steuerelementdesigns nicht auf einen Steuerelementmember auswirken sollen. |
|
Entwurfszeitattribut, Analysezeitattribut und Laufzeitattribut. Ordnet einer Eigenschaft oder einem Eigenschaftentyp einen Typkonverter zu. Typkonverter führen Konvertierungen von einer Zeichenfolgendarstellung zu einem bestimmten Typ aus und umgekehrt. |
[TypeConverter(typeof(AuthorConverter))] Angewendet auf den in Beispiel für die Eigenschaften eines Serversteuerelements definierten Author-Typ. |
|
Entwurfszeitattribut und Laufzeitattribut. Gibt an, dass eine Zeichenfolgeneigenschaft einen URL-Wert darstellt, über den Sie der Eigenschaft einen URL-Generator zuordnen können. |
[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)] Wenden Sie das Attribut an, um einen bestimmten Dateifilter für ASP.NET-Dateien festzulegen, und um absolute und relative Pfade zuzulassen. |
Auf Ereignismember angewendete Attribute
Die am häufigsten auf Ereignismember angewendeten Attribute sind die folgenden drei Entwurfszeitattribute: BrowsableAttribute, CategoryAttribute und DescriptionAttribute. Diese Attribute werden auch auf Eigenschaften angewendet und sind in der obigen Tabelle beschrieben. Ein Codebeispiel finden Sie in Beispiel für ein zusammengesetztes Steuerelement im Submit-Ereignis des Register Beispielsteuerelements.
Siehe auch
Aufgaben
Weitere Ressourcen
Entwickeln von benutzerdefinierten ASP.NET-Serversteuerelementen