Metadata Attributes for Custom Server Controls

Artigo
11/03/2006

Metadata attributes are applied to server controls and to their members to provide information that is used by design tools, the ASP.NET page parser, the ASP.NET run time, and the common language runtime. Design-time attributes enhance the developer experience at design time when a page developer uses the control in a visual designer. Design-time-only attributes have no effect on the functionality of a control during a page request. A control's parse-time attributes are used by the ASP.NET page parser when it reads the control's declarative syntax in a page. Parse-time and run-time attributes are essential for the functioning of a control in a page.

This topic describes the metadata attributes that you will commonly apply to controls and to their public properties and events.

Attributes Applied to a Control

Attribute Example

Attribute	Example
AspNetHostingPermissionAttribute JIT compile-time code access security attribute. Required to ensure that code that links to the control has the appropriate security permissions. The Control class is marked with two JIT compile-time code access security attributes: `AspNetHostingPermission(SecurityAction.LinkDemand, Level=AspNetHostingPermissionLevel.Minimal)` and `AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal)`. You should apply the first attribute to your control, but you do not have to apply the second because an inheritance demand is transitive and remains in effect on derived classes. For more information, see SecurityAction.	`[AspNetHostingPermission(SecurityAction.LinkDemand, Level=AspNetHostingPermissionLevel.Minimal)]` Applied to the `WelcomeLabel` example control in Walkthrough: Developing and Using a Custom Server Control.
ControlBuilderAttribute Parse-time attribute. Associates a custom control builder with the control. You need to apply this attribute only if you want to use a custom control builder to modify the default logic that the page parser uses for parsing the control's declarative syntax. If you want only to specify whether the content within a control's tags corresponds to properties or child controls, use ParseChildrenAttribute (described later in this table) instead of a custom control builder.	`[ControlBuilder(typeof(MyControlBuilder))]`
ControlValuePropertyAttribute Design-time and run-time attribute. Specifies the property that is used as the default value for a control. Applying this attribute enables a control to be used as a parameter in a query at run time, and defines the default value that a ControlParameter object binds to at run time.	`[ControlValueProperty("Text")]`
DefaultEventAttribute Design-time attribute. Specifies the default event for the control in a visual designer. In many visual designers, when the page developer double-clicks the control on the design surface, the code editor opens with the cursor positioned in the event handler for the default event.	`[DefaultEvent("Submit")]` Applied to the `Register` example control in Composite Web Control Example.
DefaultPropertyAttribute Design-time attribute. The property specified in this attribute is highlighted in a visual designer's property browser when the page developer selects the control on the design surface.	`[DefaultProperty("Text")]` Applied to the `WelcomeLabel` example control in Walkthrough: Developing and Using a Custom Server Control.
DesignerAttribute Design-time attribute. Specifies the designer class that is associated with a control. A control designer class is responsible for the appearance and behavior of the associated control on a visual designer's design surface.	`[Designer(typeof(SimpleCompositeControlDesigner))]` Applied to the example controls in Walkthrough: Creating a Basic Control Designer for a Web Server Control
ParseChildrenAttribute Parse-time attribute. Specifies whether contents within a control's tag correspond to properties or to child controls. The Control class is marked `ParseChildren(false)`, which means that the page parser interprets the content within the control's tags as child controls. The WebControl class is marked `ParseChildren(true)`, which means that the page parser interprets the content within the control's tags as properties. You need to apply this attribute only if you want to modify the logic specified in the ParseChildrenAttribute attribute on the WebControl class.	`[ParseChildren(true, "Contacts")]` Applied to the `QuickContacts` example control in Web Control Collection Property Example.
PersistChildrenAttribute Design-time attribute. Specifies whether a visual designer should persist child controls or properties within a control's tag when the control is used declaratively in a page. The Control class is marked `PersistChildren(true)`, which means that the designer persists child controls within the control's tags. The WebControl class is marked `PersistChildren(false)`, which means that the designer persists properties as attributes within the control's tags.	`[PersistChildren(false)]` Applied to the WebControl class and appropriate for most controls that derive from this class. However, container controls such as Panel that persist child controls within their tags are marked `PersistChildren(true)` and `ParseChildren(false)`.
ThemeableAttribute Parse-time attribute. Specifies whether a control can be affected by themes or control skins. If a control type is marked to indicate that themes cannot be applied to it, then all members of the control likewise are not affected by themes.	`[Themeable(false)]` Apply the attribute shown in the preceding example to prevent a control and all its members from being affected by themes or control skins.
ToolboxDataAttribute Design-time attribute. Specifies the format of the markup created for the tag by the visual designer when the control is created from the toolbox.	`[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"]` Applied to the `WelcomeLabel` example control in Walkthrough: Developing and Using a Custom Server Control.
ToolboxItemAttribute Design-time attribute. Specifies whether a visual designer should display a control or component in the toolbox. By default, controls are always displayed in the toolbox. You need to apply this only to a control (such as the owner of a template property) that you do not want to display in the toolbox.	`[ToolboxItem(false)]` Applied to the `TemplateOwner` control in Templated Server Control Example.
ValidationPropertyAttribute Design-time attribute. Specifies the name of the property that is checked by a validation control. Typically this is the property whose value is supplied by users at run time, such as a TextBox control's Text property. In a visual designer, the dialog box that allows page developers to select the target of a validation control lists properties specified with ValidationPropertyAttribute from controls on the page.	`[ValidationProperty("Text")]`

AspNetHostingPermissionAttribute

JIT compile-time code access security attribute.

Required to ensure that code that links to the control has the appropriate security permissions. The Control class is marked with two JIT compile-time code access security attributes:

AspNetHostingPermission(SecurityAction.LinkDemand, Level=AspNetHostingPermissionLevel.Minimal)

and AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal).

You should apply the first attribute to your control, but you do not have to apply the second because an inheritance demand is transitive and remains in effect on derived classes. For more information, see SecurityAction.

[AspNetHostingPermission(SecurityAction.LinkDemand, Level=AspNetHostingPermissionLevel.Minimal)]

Applied to the WelcomeLabel example control in Walkthrough: Developing and Using a Custom Server Control.

ControlBuilderAttribute

Parse-time attribute.

Associates a custom control builder with the control. You need to apply this attribute only if you want to use a custom control builder to modify the default logic that the page parser uses for parsing the control's declarative syntax. If you want only to specify whether the content within a control's tags corresponds to properties or child controls, use ParseChildrenAttribute (described later in this table) instead of a custom control builder.

[ControlBuilder(typeof(MyControlBuilder))]

ControlValuePropertyAttribute

Design-time and run-time attribute.

Specifies the property that is used as the default value for a control. Applying this attribute enables a control to be used as a parameter in a query at run time, and defines the default value that a ControlParameter object binds to at run time.

[ControlValueProperty("Text")]

DefaultEventAttribute

Design-time attribute.

Specifies the default event for the control in a visual designer. In many visual designers, when the page developer double-clicks the control on the design surface, the code editor opens with the cursor positioned in the event handler for the default event.

[DefaultEvent("Submit")]

Applied to the Register example control in Composite Web Control Example.

DefaultPropertyAttribute

Design-time attribute.

The property specified in this attribute is highlighted in a visual designer's property browser when the page developer selects the control on the design surface.

[DefaultProperty("Text")]

Applied to the WelcomeLabel example control in Walkthrough: Developing and Using a Custom Server Control.

DesignerAttribute

Design-time attribute.

Specifies the designer class that is associated with a control. A control designer class is responsible for the appearance and behavior of the associated control on a visual designer's design surface.

[Designer(typeof(SimpleCompositeControlDesigner))]

Applied to the example controls in Walkthrough: Creating a Basic Control Designer for a Web Server Control

ParseChildrenAttribute

Parse-time attribute.

Specifies whether contents within a control's tag correspond to properties or to child controls. The Control class is marked ParseChildren(false), which means that the page parser interprets the content within the control's tags as child controls. The WebControl class is marked ParseChildren(true), which means that the page parser interprets the content within the control's tags as properties. You need to apply this attribute only if you want to modify the logic specified in the ParseChildrenAttribute attribute on the WebControl class.

[ParseChildren(true, "Contacts")]

Applied to the QuickContacts example control in Web Control Collection Property Example.

PersistChildrenAttribute

Design-time attribute.

Specifies whether a visual designer should persist child controls or properties within a control's tag when the control is used declaratively in a page. The Control class is marked PersistChildren(true), which means that the designer persists child controls within the control's tags. The WebControl class is marked PersistChildren(false), which means that the designer persists properties as attributes within the control's tags.

[PersistChildren(false)]

Applied to the WebControl class and appropriate for most controls that derive from this class. However, container controls such as Panel that persist child controls within their tags are marked PersistChildren(true) and ParseChildren(false).

ThemeableAttribute

Parse-time attribute.

Specifies whether a control can be affected by themes or control skins. If a control type is marked to indicate that themes cannot be applied to it, then all members of the control likewise are not affected by themes.

[Themeable(false)]

Apply the attribute shown in the preceding example to prevent a control and all its members from being affected by themes or control skins.

ToolboxDataAttribute

Design-time attribute.

Specifies the format of the markup created for the tag by the visual designer when the control is created from the toolbox.

[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"]

Applied to the WelcomeLabel example control in Walkthrough: Developing and Using a Custom Server Control.

ToolboxItemAttribute

Design-time attribute.

Specifies whether a visual designer should display a control or component in the toolbox. By default, controls are always displayed in the toolbox. You need to apply this only to a control (such as the owner of a template property) that you do not want to display in the toolbox.

[ToolboxItem(false)]

Applied to the TemplateOwner control in Templated Server Control Example.

ValidationPropertyAttribute

Design-time attribute.

Specifies the name of the property that is checked by a validation control. Typically this is the property whose value is supplied by users at run time, such as a TextBox control's Text property. In a visual designer, the dialog box that allows page developers to select the target of a validation control lists properties specified with ValidationPropertyAttribute from controls on the page.

[ValidationProperty("Text")]

Attributes Applied to Public Properties

Attribute Example

Attribute	Example
BindableAttribute Design-time attribute. Specifies whether it is meaningful to bind data to a property. In a visual designer, the property browser can display a control's bindable properties in a dialog box. (For example, in Visual Studio, bindable properties are displayed in the DataBindings dialog box.) If a property is not marked with this attribute, the property browser infers the value to be `Bindable(false)`.	`[Bindable(true)]` Applied to the `Text` property of the `WelcomeLabel` example control in Walkthrough: Developing and Using a Custom Server Control.
BrowsableAttribute Design-time attribute. Specifies whether a property should be displayed in a visual designer's property browser. Apply `Browsable(false)` to a property that you do not want to be displayed in the property browser. The default value, `Browsable(true)`, is inferred by the property browser when a property is not marked with this attribute.	`[Browsable(false)]` Applied to the `Template` property in the `VacationHome` example control in Templated Server Control Example.
CategoryAttribute Design-time attribute. Specifies how to categorize the property in a visual designer's property browser. For example, `Category("Appearance")` tells the property browser to display the property in the Appearance category when the page developer uses category view in the property browser. You can specify a string argument corresponding to an existing category in the property browser or create your own category.	`[Category("Appearance")]` Applied to the `Text` property of the `WelcomeLabel` example control in Walkthrough: Developing and Using a Custom Server Control
DefaultValueAttribute Design-time attribute. Specifies a default value for a property. This value should be the same as the default value you return from the property accessor (getter). In some visual designers such as Visual Studio, the DefaultValueAttribute attribute allows a page developer to reset a property value to its default using the Reset command on the shortcut menu.	`[DefaultValue("")]` Applied to the `Text` property of the `WelcomeLabel` example control in Walkthrough: Developing and Using a Custom Server Control
DescriptionAttribute Design-time attribute. Specifies a brief description of the property. In a visual designer such as Visual Studio, the property browser displays the description of the selected property, typically at the bottom of the window.	`[Description("The welcome message text.")]` Applied to the `Text` property of the `WelcomeLabel` example control in Walkthrough: Developing and Using a Custom Server Control
DesignerSerializationVisibilityAttribute Design-time attribute. Specifies whether to serialize a property or its contents (such as subproperties or collection items) that are set at design time. The argument of the attribute's constructor is a value of the DesignerSerializationVisibility enumeration. The default value, Visible, is implied when this attribute is not applied, and the value of the property is serialized.	`[DesignerSerializationVisibility` `(DesignerSerializationVisibility.Content)]` Applied to the `Author` property of the `Book` example control in Server Control Properties Example.
EditorAttribute Design-time attribute. Associates a custom UITypeEditor editor with a property or property type. If this attribute is applied to the type, it does not have to be applied to a property of that type.	`[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))]` Applied to the `Contacts` property of the `QuickContacts` example control in Web Control Collection Property Example.
EditorBrowsableAttribute Design-time attribute. Specifies whether the property name appears in a source editor's IntelliSense list. This attribute can also be applied to methods and events. The argument of the attribute's constructor is a value of the EditorBrowsableState enumeration. The default value, Always, is implied when this attribute is not applied.	`[EditorBrowsableAttribute` `(EditorBrowsableState.Never)]` Apply the attribute shown in the preceding example to hide a member in IntelliSense.
FilterableAttribute Design-time and parse-time attribute. Specifies whether a property can participate in device and browser filtering. Filtering enables a page developer to specify different property values for different browsers within a single control declaration. For example, a page developer can use filtering to set different values for the Text property of a Label control, as shown in the following syntax: `<asp:Label UP:Text="Hello" and IE:Text="Welcome to my site" runat="server" />` "UP" and "IE" are browser filters. The default value `Filterable(true)` is implied when this attribute is not applied.	`[Filterable(false)]` Apply the attribute shown in the preceding example to exclude a property from device and browser filtering.
LocalizableAttribute Design-time attribute. Specifies whether it is meaningful to localize the property. When a property is marked `Localizable(true)`, the property value is stored in a resource file. The default value, `Localizable(false)`, is implied when this attribute is not applied.	`[Localizable(true)]` Applied to the `Text` property of the `WelcomeLabel` example control in Walkthrough: Developing and Using a Custom Server Control.
NotifyParentPropertyAttribute Design-time attribute. Specifies that in a property browser, changes made to a subproperty should be propagated to the parent property.	`[NotifyParentProperty(true)]` Applied to the `FirstName`, `LastName`, and `MiddleName` properties of the `Author` type defined in Server Control Properties Example.
PersistenceModeAttribute Design-time attribute. Specifies whether to persist a property as an attribute on the control's tag or as nested content within the control's tags. The argument of the attribute's constructor is a value of the PersistenceMode enumeration.	`[PersistenceMode(PersistenceMode.InnerProperty)]` Applied to the `Author` property of the `Book` example control in Server Control Properties Example.
TemplateContainerAttribute Design-time and parse-time attribute. Specifies the type of naming container for a property that returns an ITemplate interface.	`[TemplateContainer(typeof(CustomTemplateContainer))]` Apply the attribute shown in the preceding example to specify that the ITemplate property is represented by the `CustomTemplateContainer` class.
TemplateInstanceAttribute Design time and parse-time attribute. Specifies whether a template property allows the creation of single or multiple instances. If a template property is not extended with the TemplateInstanceAttribute attribute, multiple instances are the default.	`[TemplateInstance(TemplateInstance.Single)]` Apply the attribute shown in the preceding example to specify that only one instance of a template property can be created.
ThemeableAttribute Parse-time attribute. Specifies whether a control member can be affected by themes or control skins. By default, all properties exposed by a control can have themes applied if the control type itself can have themes applied.	`[Themeable(false)]` Apply the attribute shown in the preceding example to prevent a control member from being affected by themes or control skins.
TypeConverterAttribute Design-time, parse-time, and run-time attribute. Associates a type converter with a property or property type. Type converters perform conversions from a string representation to a given type and vice versa.	`[TypeConverter(typeof(AuthorConverter))]` Applied to the `Author` type defined in Server Control Properties Example.
UrlPropertyAttribute Design-time and run-time attribute. Specifies that a string property represents a URL value, which allows you to associate a URL builder with the property.	`[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute\|UrlTypes.RootRelative\|UrlTypes.AppRelative)]` Apply to set a specific file filter for ASP.NET files and allow absolute and relative paths.

BindableAttribute

Design-time attribute.

Specifies whether it is meaningful to bind data to a property. In a visual designer, the property browser can display a control's bindable properties in a dialog box. (For example, in Visual Studio, bindable properties are displayed in the DataBindings dialog box.) If a property is not marked with this attribute, the property browser infers the value to be Bindable(false).

[Bindable(true)]

Applied to the Text property of the WelcomeLabel example control in Walkthrough: Developing and Using a Custom Server Control.

BrowsableAttribute

Design-time attribute.

Specifies whether a property should be displayed in a visual designer's property browser. Apply Browsable(false) to a property that you do not want to be displayed in the property browser. The default value, Browsable(true), is inferred by the property browser when a property is not marked with this attribute.

[Browsable(false)]

Applied to the Template property in the VacationHome example control in Templated Server Control Example.

CategoryAttribute

Design-time attribute.

Specifies how to categorize the property in a visual designer's property browser. For example, Category("Appearance") tells the property browser to display the property in the Appearance category when the page developer uses category view in the property browser. You can specify a string argument corresponding to an existing category in the property browser or create your own category.

[Category("Appearance")]

Applied to the Text property of the WelcomeLabel example control in Walkthrough: Developing and Using a Custom Server Control

DefaultValueAttribute

Design-time attribute.

Specifies a default value for a property. This value should be the same as the default value you return from the property accessor (getter). In some visual designers such as Visual Studio, the DefaultValueAttribute attribute allows a page developer to reset a property value to its default using the Reset command on the shortcut menu.

[DefaultValue("")]

Applied to the Text property of the WelcomeLabel example control in Walkthrough: Developing and Using a Custom Server Control

DescriptionAttribute

Design-time attribute.

Specifies a brief description of the property. In a visual designer such as Visual Studio, the property browser displays the description of the selected property, typically at the bottom of the window.

[Description("The welcome message text.")]

Applied to the Text property of the WelcomeLabel example control in Walkthrough: Developing and Using a Custom Server Control

DesignerSerializationVisibilityAttribute

Design-time attribute.

Specifies whether to serialize a property or its contents (such as subproperties or collection items) that are set at design time. The argument of the attribute's constructor is a value of the DesignerSerializationVisibility enumeration. The default value, Visible, is implied when this attribute is not applied, and the value of the property is serialized.

[DesignerSerializationVisibility

(DesignerSerializationVisibility.Content)]

Applied to the Author property of the Book example control in Server Control Properties Example.

EditorAttribute

Design-time attribute.

Associates a custom UITypeEditor editor with a property or property type. If this attribute is applied to the type, it does not have to be applied to a property of that type.

[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))]

Applied to the Contacts property of the QuickContacts example control in Web Control Collection Property Example.

EditorBrowsableAttribute

Design-time attribute.

Specifies whether the property name appears in a source editor's IntelliSense list. This attribute can also be applied to methods and events. The argument of the attribute's constructor is a value of the EditorBrowsableState enumeration. The default value, Always, is implied when this attribute is not applied.

[EditorBrowsableAttribute

(EditorBrowsableState.Never)]

Apply the attribute shown in the preceding example to hide a member in IntelliSense.

FilterableAttribute

Design-time and parse-time attribute.

Specifies whether a property can participate in device and browser filtering. Filtering enables a page developer to specify different property values for different browsers within a single control declaration. For example, a page developer can use filtering to set different values for the Text property of a Label control, as shown in the following syntax:

<asp:Label UP:Text="Hello" and IE:Text="Welcome to my site" runat="server" />

"UP" and "IE" are browser filters. The default value Filterable(true) is implied when this attribute is not applied.

[Filterable(false)]

Apply the attribute shown in the preceding example to exclude a property from device and browser filtering.

LocalizableAttribute

Design-time attribute.

Specifies whether it is meaningful to localize the property. When a property is marked Localizable(true), the property value is stored in a resource file. The default value, Localizable(false), is implied when this attribute is not applied.

[Localizable(true)]

Applied to the Text property of the WelcomeLabel example control in Walkthrough: Developing and Using a Custom Server Control.

NotifyParentPropertyAttribute

Design-time attribute.

Specifies that in a property browser, changes made to a subproperty should be propagated to the parent property.

[NotifyParentProperty(true)]

Applied to the FirstName, LastName, and MiddleName properties of the Author type defined in Server Control Properties Example.

PersistenceModeAttribute

Design-time attribute.

Specifies whether to persist a property as an attribute on the control's tag or as nested content within the control's tags. The argument of the attribute's constructor is a value of the PersistenceMode enumeration.

[PersistenceMode(PersistenceMode.InnerProperty)]

Applied to the Author property of the Book example control in Server Control Properties Example.

TemplateContainerAttribute

Design-time and parse-time attribute.

Specifies the type of naming container for a property that returns an ITemplate interface.

[TemplateContainer(typeof(CustomTemplateContainer))]

Apply the attribute shown in the preceding example to specify that the ITemplate property is represented by the CustomTemplateContainer class.

TemplateInstanceAttribute

Design time and parse-time attribute.

Specifies whether a template property allows the creation of single or multiple instances. If a template property is not extended with the TemplateInstanceAttribute attribute, multiple instances are the default.

[TemplateInstance(TemplateInstance.Single)]

Apply the attribute shown in the preceding example to specify that only one instance of a template property can be created.

ThemeableAttribute

Parse-time attribute.

Specifies whether a control member can be affected by themes or control skins. By default, all properties exposed by a control can have themes applied if the control type itself can have themes applied.

[Themeable(false)]

Apply the attribute shown in the preceding example to prevent a control member from being affected by themes or control skins.

TypeConverterAttribute

Design-time, parse-time, and run-time attribute.

Associates a type converter with a property or property type. Type converters perform conversions from a string representation to a given type and vice versa.

[TypeConverter(typeof(AuthorConverter))]

Applied to the Author type defined in Server Control Properties Example.

UrlPropertyAttribute

Design-time and run-time attribute.

Specifies that a string property represents a URL value, which allows you to associate a URL builder with the property.

[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)]

Apply to set a specific file filter for ASP.NET files and allow absolute and relative paths.

Attributes Applied to Event Members

The main attributes applied to event members are three design-time attributes: BrowsableAttribute, CategoryAttribute, and DescriptionAttribute. These attributes are also applied to properties and are described in the preceding table. For a code example, see the Submit event in the Register example control in Composite Web Control Example.

Compartilhar via

Metadata Attributes for Custom Server Controls

Attributes Applied to a Control

Attributes Applied to Public Properties

Attributes Applied to Event Members

See Also

Tasks

Other Resources

Recursos adicionais