Design-Time Attributes for Components

Caution

This content was written for .NET Framework. If you're using .NET 6 or a later version, use this content with caution. The designer system has changed for Windows Forms and it's important that you review the Designer changes since .NET Framework article.

If you are not familiar with applying attributes to provide metadata to the common language runtime, see Extending Metadata Using Attributes. Because components can be displayed in a designer, such as Visual Studio, they require attributes that provide metadata to design-time tools. This section describes and provides a list of commonly used design-time attributes.

Attributes and Designer Support

Design-time attributes are essential for displaying your control and its members correctly at design time, as they provide valuable information to a visual design tool.

In the following code fragment, the CategoryAttribute attribute enables the property browser to display the TextAlignment property in the Alignment category. The DescriptionAttribute attribute allows the property browser to provide a brief description of the property when a user clicks on it.

[
Category("Alignment"),
Description("Specifies the alignment of text.")
]
public ContentAlignment TextAlignment { //... }

<Category("Alignment"), _
Description("Specifies the alignment of text.")> _
Public Property _
TextAlignment As ContentAlignment
   ' ...
End Property

Note

In Visual C# and Visual Basic, an attribute class named AttributeNameAttribute can be referenced simply as AttributeName in the attribute syntax.

Some design-time attributes are applied at the class level. A DesignerAttribute attribute is applied at the class level and informs the forms designer which designer class to use to display the control. Components are associated with a default designer (System.ComponentModel.Design.ComponentDesigner), and Windows Forms and ASP.NET server controls are associated with their own default designers. Apply DesignerAttribute only if you define a custom designer for your component or control.

// Associates the designer class SimpleControl.Design.SimpleDesigner
// with Simple.
[ Designer(typeof(SimpleControl.Design.SimpleDesigner))]
    public class Simple : WebControl { //... }

' Associates the designer class SimpleControl.Design.SimpleDesigner
' with Simple.
<Designer(GetType(SimpleControl.Design.SimpleDesigner))> _
Public Class Simple
    Inherits WebControl
    ' ...
End Class

Common Attributes for Properties and Events

The following table lists the attributes that are commonly applied to properties and events.

Attribute	Applied To	Description
BrowsableAttribute	Properties and events	Specifies whether a property or an event should be displayed in the property browser.
CategoryAttribute	Properties and events	Specifies the name of the category in which to group a property or event. When categories are used, component properties and events can be displayed in logical groupings in the property browser.
DescriptionAttribute	Properties and events	Defines a small block of text to be displayed at the bottom of the property browser when the user selects a property or event.
BindableAttribute	Properties	Specifies whether a property is interesting to bind to.
DefaultPropertyAttribute	Properties (Insert this attribute before the class declaration.)	Specifies the default property for the component. This property is selected in the property browser when a user clicks on the control.
DefaultValueAttribute	Properties	Sets a simple default value for a property.
EditorAttribute	Properties	Specifies the editor to use for editing (changing) a property in a visual designer.
LocalizableAttribute	Properties	Specifies that a property can be localized. Any properties that have this attribute are automatically persisted into the resources file when a user chooses to localize a form.
DesignerSerializationVisibilityAttribute	Properties	Specifies whether (and how) a property displayed in the property browser should be persisted into code.
TypeConverterAttribute	Properties	Specifies the type converter to use for converting the type of the property to another data type.
DefaultEventAttribute	Events (Insert this attribute before the class declaration.)	Specifies the default event for the component. This is the event that is selected in the property browser when a user clicks on the component.

Unless otherwise stated, attributes for properties and events are placed in code immediately before the property or event declaration, as shown in the following example.

// To apply CategoryAttribute to the BorderColor 
// property, place it immediately before the declaration
// of the BorderColor property.
[Category("Appearance")] 
public Color BorderColor;

// To apply DescriptionAttribute to the Click event, 
// place it immediately before the declaration
// of the Click event.
[Description("The Click event of the button")]
public event EventHandler Click;

' To apply CategoryAttribute  to the BorderColor 
' property, place it before the property declaration.
<Category("Appearance")> Public BorderColor As Color

' To apply DescriptionAttribute to the Click event, 
' place it before the event declaration.
<Description("The Click event of the button")> Public Event Click

For information about design-time attributes that associate designers with components and controls, see Extending Design-Time Support.

In addition to using the attribute classes defined in the .NET Framework class library, you can define your own attribute classes. For details, refer to the documentation for your programming language or see Writing Custom Attributes.

See Also

Tasks

How to: Apply Attributes in Windows Forms Controls

Concepts

Attributes and Design-Time Support

Attributes in Windows Forms Controls

Other Resources

Extending Design-Time Support