Attributes to consider applying when writing a custom control

The original author published this : Eilon Lipton's Blog

 

Almost every custom control has at least one additional public property, and that public property as well as the control itself should probably have at least a few attributes applied to them. Attributes tell the designer host (Visual Studio) or the parser (ASP.NET) interesting things about your control that might not be evident from just its name and its type. Launch any decent class browser tool and you'll see that every control that shipped in ASP.NET and ASP.NET AJAX has several attributes on it as well as their properties and events.

By applying the proper set of attributes you can significantly increase the usefulness of your control in several ways. For example, the DescriptionAttribute provides helpful text to the person designing the page. The ValidationPropertyAttribute is required when the person designing the page wants to validate the value of your control. Following is a list of the most useful and important attributes you can apply to your control and its properties and events.

Control attributes:

• ControlValueProperty
   - Used by data source parameters to get the "intrinsic" value of the control. For example, DropDownList's "intrinsic" value is its SelectedValue property.
• DefaultEvent
   - Set the event for which to create an event handler when double clicking the control in the designer.
• DefaultProperty
   - Set the default selected property in the designer's property grid.
• NonVisualControl
   - Hide the control at design time when "Non Visual Controls" is unchecked from the View menu.
• ParseChildren
   - The full name is really "parse children as properties".
   - Set to true if the inner contents of the control represent properties as opposed to child controls.
   - True by default on controls deriving from WebControl; false by default otherwise.
• PersistChildren
   - The full name is really "persist child controls".
   - Set to true if the designer should persist child controls as the inner contents.
   - False by default on controls deriving from WebControl; true by default otherwise.
   - 99.9% of the time PersistChildren has the opposite value of ParseChildren.
• SupportsEventValidation
   - Indicates that the control's client-side calls to __doPostBack() should be validated on the server for security purposes.
• Themable
   - Indicates that by default all the control's properties can be customized via themes. Individual properties can also be marked with this attribute to override the behavior.
   - True by default for controls that derive from WebControl.
• ValidationProperty
   - Required when a control can be validated.
   - Somewhat similar to the ControlValueProperty in that they often point at the same property.
• ViewStateModeById
   - Indicates that viewstate should be loaded based on control IDs as opposed to being loaded based on the index of the control in the child controls collection.

Property attributes:

• Bindable
   - Indicates at design time only whether the property should appear by default in the Edit Databindings dialog.
• Browsable
   - Indicates whether the property is visible in the property grid at design time.
• Category
   - Determines in which category the property will appear when the property grid is in category mode.
• DefaultValue
   - Get-only property: Since get-only properties are never persisted anyway, no default value is needed.
   - Get/Set value type property: Must be set.
   - Get/Set reference type property: Must be null so that it shows up as non-bold in the property grid.
• Description
   - Determines the help text that will show in the property grid's lower help panel.
• DesignerSerializationVisibility
   - Controls whether the property is persisted in the markup (see also PersistenceMode).
   - Use this to prevent get/set properties from being persisted at all.
• EditorBrowsable
   - Affects whether the property appears in Intellisense.
• IDReferenceProperty
   - Specifies that the property represents a control ID, and optionally the type of the target control. Not used by Visual Studio 2005.
• MergableProperty
   - Affects whether the property shows up in the property grid when multiple controls are selected.
   - If the property is Browsable and is a reference type then set Mergable=false (except immutable reference types, such as string).
• PersistenceMode
   - Controls how the property is persisted in the markup.
   - Simple-valued properties should use the default, which is Attribute.
   - Collection, template, and complex (e.g. styles) should use InnerProperty.
   - InnerDefaultProperty should never be used since it causes compatibility problems. For example, if in the next version of your control you want another inner property, it won't work properly.
   - EncodedInnerDefaultProperty should also rarely be used for similar reasons as InnerDefaultProperty.
   - In ASP.NET 2.0 support was added for strings to be InnerProperties, which is good for large multi-line string values, such as XmlDataSource's Data property.
• Themable
   - Overrides the value of the attribute on the control to determine whether the property can be customized via themes.

Event attributes:

• Browsable
   - Same as properties.
• Category
   - Same as properties.
• Description
   - Same as properties.
• EditorBrowsable
   - Same as properties.