Integrating Your Controls with Visual Studio
Now that you have learned the ins and outs of building controls for your own libraries, the next step—perhaps the most important—is to integrate your controls into Visual Studio so they operate as cleanly, intuitively, and professionally as the native .NET framework controls. You achieve this primarily by assigning attributes to your classes, properties, methods, and events.
An attribute is essentially a property, that is, a characteristic of some object. The terms attribute and property are often considered synonymous. In XML, for example, you provide attributes for elements. In .NET, you provide properties for classes. Because you can attach attributes to almost any entity in the .NET framework—including attaching them to properties—you must take care to use the right terminology. Attaching attributes to properties is, in fact, the main technique you will see in this and subsequent sections. To attach an attribute to an element in your code, determine the attribute you want to use along with its arguments, surround it with square brackets (in C#), and place it on the line immediately preceding the element's definition. This code fragment shows four attributes being attached to the
ClockForeColor property:
[Description("Foreground color of the clock")]
[Category("Clock")]
[EditorBrowsable(EditorBrowsableState.Always)]
[Localizable(True)]
public Color ClockForeColor
{
. . .
}
Attributes behave like other elements in the code editor in two important respects. First, Intellisense will help with auto-completion of your choice of attribute. Second, you must have the appropriate references in your project for the attribute you intend to use; otherwise you will get a compilation error.
See these MSDN documents for more information:
The document
Attributes in Windows Forms Controls is probably the best reference for attributes relevant to controls. And for purists, I found this (possibly outdated)
Attribute Hierarchy that contains a complete list of attributes, including some not applicable to user controls.
Table 5 lists the more universal attributes for integrating your controls into Visual Studio, along with one important aspect of integration (in the final row) that you do with documentation comments instead of attributes.
Table 5. Aspects of Integration: The table lists attributes that are commonly helpful in integrating your controls into Visual Studio. The shaded row is not an attribute; you get documentation comments by adding XML comments to code.
Attribute |
Operates On |
Description |
Browsable |
Property, event |
Specifies whether a property or event should be displayed or hidden in the Properties window. |
Category |
Property, event |
Organizes your property into one of the existing categories (e.g. Accessibility, Appearance, Behavior, Data, Design, etc.) in the property grid or a new one of your own choosing. Only relevant when the property grid is set to Categorized mode (as opposed to alphabetic mode). |
Description |
Property, event |
Defines a short block of text that displays at the bottom of the property browser when you select a property or event. |
DisplayName |
Property, event, method |
Specifies an alias for the name of a property, event, or public void method that takes no arguments. This alias is shown in the Properties window instead of the actual name of the property. |
EditorBrowsable |
Property, event, method |
Specifies whether a property or method is revealed via Intellisense in the code editor. |
Localizable |
Property |
Specifies that a property can be localized. Any properties that have this attribute are automatically persisted into the resources file (rather than in the designer-generated portion of code) when a user chooses to localize a form. |
PasswordPropertyText |
Property |
Indicates that an object's text representation is obscured by characters such as asterisks. |
ReadOnly |
Property |
Specifies whether a property is read-only or read/write at design time. If the property has no setter accessor, then this attribute has no effect. |
DefaultEvent |
Class |
Specifies the event that VS initially selects when you view the Events window for a control. Double-clicking the control in the designer generates stub code to handle this event. |
DefaultProperty |
Class |
Specifies the property that VS initially selects when you view the Properties window for a control. |
DefaultValue |
Property |
The .NET framework distinguishes between an initial value of a property and a default value; this attribute does not assign an initial value; it determines only whether the property is serialized in the list of property assignments in your winformapp.Designer.cs file. See MSDN for more details. |
Documentation comments |
Class, property, event, method |
XML documentation comments that you apply to document your classes, methods, properties, and events are automatically incorporated by Visual Studio's Intellisense. |