VS.Net 2005 DesignTime Integration

Origin: http://blogs.msdn.com/gurbir/archive/2007/03/16/vs-net-2005-design-time-integration.aspx

This article provides an overview of the VS.NET 2005 Design-Time Integration Support. The article highlights the .NET design-time architecture and discusses the design-time attributes and the various design-time components in details with reference to the web controls. The article also lists the reference and the namespaces required for adding design-time support to your projects.

 

The figure below provides a high-level representation of the VS.NET design-time architecture and highlights the linking among the various blocks.

 

 

Design-Time Attributes

An Attribute associates a component with the Design-Time Components. This association can be done at the component type level as well as at the component member level. The design-time attributes can be broadly categorized into two categories based upon the type of association:

 

1.      Type Level Attributes

2.      Member Level Attributes

 

Type Level Attributes

Type Level Attributes associates the type of the component with the other components. Type Level Attributes are specified just before the class declaration. The following code shows the type level association for the class MyTextBox.

 

[DefaultProperty("Text")]

[DefaultEvent("OnChange")]

public class MyTextBox : TextBox

{

    public MyTextBox()

    {

    }

}

 

In the above code, the design-time attribute DefaultProperty specifies the default property for the class which is shown selected in the property grid when the user clicks on the component. Similarly, the design-time attribute DefaultEvent specifies the default event for the class.

 

Member Level Attributes

Member Level Attributes associates the member of the component with the other components. Member Level Attributes are specified just before the property definition. The following code shows the member level association for the property Text.

 

[Browsable(true)]

[Category("Appearance")]

[DefaultValue("")]

[Description("Gets/Sets the text value.")]

public string Text

{

    ...

}

 

In the above code, the design-time attribute Browsable specifies whether the property will be visible in the property grid or not. The attribute Category specifies the category below which the property will be displayed in the property grid. The attribute DefaultValue specifies the default value for the property whereas the attribute Description specifies the brief text about the property that is displayed in the property grid description panel.

 

The component can specify multiple attributes for the type as well as for the members.

 

Design-Time Components

The Design-Time Components are the components that extend the design-time behavior. These components use the design-time environment and provide extended design-time functionality to customize the component behavior and user-interface.

 

The .NET Framework provides the following three basic design-time components:

 

1.      Designers

2.      Type Converters

3.      UI Type Editors

 

Designers

A designer provides the support to customize the behavior of the component at design-time. The designer can be considered as a helper class that provides a set of properties and methods to customize the component's design-time behavior. The designer provides the following support.

 

• Allows to specify the design-time HTML for the custom controls.
• Allows to add, remove or override the existing properties of the control.
• Allows to specify and execute certain control methods/properties from ContextMenu or ActionList.
• Allows to specify the design-time datasource for the data-bound controls.
• Allows to modify the control templates using the design-time WYSIWYG editor.
• Allows to specify the data-bindings for the child controls of a composite control.

 

The following figure shows the design-time appearance of the .NET Framework DropDownList control. The designer ListControlDesigner specifies some design-time properties/methods like Choose DataSource..., Edit Items..., Enable AutPostBack, etc and shows them in the ActionList. The designer links these properties to the control properties and allows user to set them from the ActionList.

 

 

The following figure shows the design-time editing of the ItemTemplate of the .NET Framework DataList control. The designer DataListDesigner provides the WYSIWYG editor for the editing of templates. The designer also allows user to specify the data-bindings for the template child controls.

 

 

The .NET Framework provides the designer classes for almost all the server controls. For example: the designer HyperLinkDesigner provides the design-time support for the HyperLink control, the designer ListControlDesigner provides the support for the DropDownList control and the designer DataListDesigner provides the support for the DataList control. Some other common designer classes include LabelDesigner, CheckBoxDesigner, LinkButtonDesigner, DataGridDesigner, PanelDesigner, TableDesigner, MenuDesigner, etc. All these designer classes are derived from the base class ControlDesigner. These designer classes can be easily linked to custom controls using the design-time attributes.

 

[DesignerAttribute(typeof(DataListDesigner))]

public class MyList : DataList

{

    public MyList()

    {

    }

}

 

The above code shows the linking of a custom control MyList to a designer DataListDesigner using the design-time attribute DesignerAttribute.

 

Type Converters

A type converter, as the name indicates, provides the support to convert the property values between the data types the component is built to support and the data types the component can translate values to and from. The type converter provides the following support.

 

• Design-time configuration of property values within property grid.
• Listing of standard values for a property within the property grid.
• Data type validation of property values within the property grid.
• Generation of initialization code to initialize a property at design-time.

 

The VS.Net property grid allows the configuration of property values at design-time. Since the property browser allows entering only the string values, therefore there should be some mechanism to convert these string values to the appropriate data type of the property. This mechanism is provided by Type Converters. They also provide support to list the standard values for the property in the property grid.

 

The following figure shows the design-time configuration of the property Font within the property grid. The figure also shows the standard values for the property Size displayed as a dropdown list in the property grid.

 

 

The type converter also performs the type validation for the property values within the property grid to ensure the proper type conversion. For example, if the user enters an invalid value, say some string value for a property of type int, then the property grid shows the following validation message.

 

 

The .NET Framework provides the type converter classes for almost all the basic data types. For example: the class ArrayConverter provides the type conversion support for the Array data type, the class BooleanConverter provides the support for the bool data type and the class DateTimeConverter provides the support for the DateTime data type. Some other common type converter classes include ByteConverter, CharConverter, DecimalConverter, DoubleConverter, Int16Converter, Int32Converter, EnumConverter, etc. All these type converter classes are derived from the base class TypeConverter. These type converter classes can be easily linked to custom controls using the design-time attributes.

 

[TypeConverterAttribute(typeof(StringArrayConverter))]

public string[] Items

{

    ...

}

 

The above code shows the linking of a control property Items to a type converter class StringArrayConverter using the design-time attribute TypeConverterAttribute. The StringArrayConverter is a new class provided in .NET 2.0 that provides a type converter for converting a string of comma-separated values to and from an array of strings. So, this type converter allows the user to specify the comma-separated values in the property grid for the property Items of type string[].

 

UI Type Editors

A UI type editor provides a custom user interface to display and edit the value of a property at design time. This custom user interface can either be a drop down list displayed within the property grid or it can be a windows form displayed as a model dialog. A UI type editor is type-specific and can display or edit values for only those types that it supports. The UI type editor provides the following support.

 

• Providing a custom UI for representation of property value at design time.
• Listing of property values as a drop-down list within the property grid.
• Configuration of the property value of the type it is built to support.

 

The following figure shows the design-time representation of the some property of type ListItemCollection displayed as a windows form dialog. The figure shows the complete details of each list item in the collection and allows user to further edit the individual list item properties within the model dialog only. It’s not possible to represent such property values within the property grid, so the editors provide extended functionality to represent such property values using custom user interfaces.

 

 

The .NET Framework provides the editor classes for some of the common component property types. For example: the editor class ArrayEditor provides the UI for representing the value of the property of type Array, the class CollectionEditor provides the UI for the property of type Collection and the class DateTimeEditor provides the UI for the property of type DateTime. Some other common editor classes include MultilineStringEditor, ImageUrlEditor, ConnectionStringEditor, XmlUrlEditor, DataGridColumnCollectionEditor, ListItemsCollectionEditor, etc. All these editor classes are derived from the base class UITypeEditor. These editor classes can be easily linked to custom controls using the design-time attributes.

 

The following code shows the linking of a property Items of type ListItemCollection of a custom control to an editor ListItemsCollectionEditor using the design-time attribute EditorAttribute.

                                                                         

[EditorAttribute(typeof(ListItemsCollectionEditor), typeof(UITypeEditor))]

public ListItemCollection Items

{

    ...

}

 

Adding Design-Time Support to your Project

Adding the design-time support to your project requires adding some references to your project and including certain namespaces in your related code files. The following section lists the reference and the namespaces required for design-time support:

 

1. To provide the Design-Time support to your components, you will need to add the reference to the .NET Framework Assembly System.Design.dll in your project.

2. To use the .NET Framework existing design-time attributes, include the namespace System.ComponentModel in your related code files. It allows you to use all the design-time atrributes like EditorAttribute, DesignerAttribute, TypeConverterAttribute, etc.

To create a new custom design-time attribute for your web controls, you will have to derive from the base class Attribute. This base class exists at the root level in the System namespace.

3. To use the .NET Framework designer classes for the existing web controls, include the namespace System.Web.UI.Design.WebControls in your related code files. It allows you to use the existing designer classes like ButtonDesigner, LabelDesigner, CheckBoxDesigner, DataGridDesigner, PanelDesigner, MenuDesigner, etc.

To create a new custom designer class for your web controls, you will have to derive from the base class ControlDesigner. This base class exists in the System.Web.UI.Design namespace. 

4. To use the .NET Framework type converter classes for the existing data types, include the namespace System.ComponentModel in your related code files. It allows you to use the existing type converter classes like ByteConverter, CharConverter, DecimalConverter, Int16Converter, Int32Converter, etc.

To create a new custom type converter class for your properties, you will have to derive from the base class TypeConverter. This base class exists in the System.ComponentModel namespace.

5. To use the .NET Framework editor classes for the existing data types, include the namespace System.ComponentModel.Design in your related code files. It allows you to use the existing editor classes like CollectionEditor, DateTimeEditor, etc. Some of the editor classes common to web controls exists in the namespace System.Web.UI.Design like ImageUrlEditor, XmlUrlEditor, etc. Other editor classes related to specific web controls exists in the namespace System.Web.UI.Design.WebControls like DataGridColumnCollectionEditor, ListItemsCollectionEditor, etc.

To create a new custom editor class for your properties, you will have to derive from the base class UITypeEditor. This base class exists in the System.Drawing.Design namespace.