This documentation is archived and is not being maintained.

How to: Implement a Type Converter

A type converter can be used to convert values between data types, and to assist property configuration at design time by providing text-to-value conversion or a drop-down list of values to select from. If configured properly, a type converter can produce property configuration code using an InstanceDescriptor and System.Reflection objects to provide the designer serialization system the information necessary to produce code that initializes the property at run time.

Type converters can be used for string-to-value conversions or translation to or from supported data types at design time and at run time. In a host such as a property browser in a forms designer, type converters allow a property value to be represented as text to the user, and they can convert user-entered text into a value of the appropriate data type.

Most native data types (Int32, String, enumeration types, and others) have default type converters that provide string-to-value conversions and perform validation checks. The default type converters are in the System.ComponentModel namespace and are named TypeConverterNameConverter. You can extend a type converter when the default functionality is not adequate for your purposes or implement a custom type converter when you define a custom type that does not have an associated type converter.

NoteNote

A TypeConverterAttribute attribute is generally applied to a property or a data member to associate it with a type converter. If a TypeConverterAttribute is applied to a type, it does not have to be reapplied to properties or data members of that type.

The implementation of a type converter is independent of any user-interface functionality. Hence the same type converter can be applied both in Windows Forms and in Web Forms.

To implement a simple type converter that can translate a string to a Point

  1. Define a class that derives from TypeConverter.

  2. Override the CanConvertFrom method that specifies which type the converter can convert from. This method is overloaded.

  3. Override the ConvertFrom method that implements the conversion. This method is overloaded.

  4. Override the CanConvertTo method that specifies which type the converter can convert to. It is not necessary to override this method for conversion to a string type. This method is overloaded.

  5. Override the ConvertTo method that implements the conversion. This method is overloaded.

  6. Override the IsValid method that performs validation. This method is overloaded.

The following code example implements a type converter that converts a String type into a Point type and a Point into a String. The CanConvertTo and IsValid methods are not overridden in this example.

No code example is currently available or this language may not be supported.

A type converter can provide a list of values for a type in a Properties window control. When a type converter provides a set of standard values for a type, the value entry field for a property of the associated type in a Properties window control displays a down arrow that displays a list of values to set the value of the property to when clicked.

When a property of the type this type converter is associated with is selected in a design-time environment property browser, the value entry field will contain a button that displays a drop-down list of the standard values for the property type that you can select from.

To implement a simple type converter that provides a drop-down list of standard values in a property browser

  1. Define a class that derives from TypeConverter.

  2. Override the GetStandardValuesSupported method and return true.

  3. Override the GetStandardValues method and return a TypeConverter::StandardValuesCollection containing the standard values for the property type. The standard values for a property must be of the same type as the property itself.

  4. Override the CanConvertFrom method and return true for a sourceType parameter value of type string.

  5. Override the ConvertFrom method and return the appropriate value for the property based on the value parameter.

  6. Apply a TypeConverterAttribute that indicates the type of your type converter to the type that you are providing a set of standard values for.

The following example demonstrates a type converter that provides a list of standard values to a Properties window control for a property of the type it is associated with. The example type converter supports properties of integer type with which it has been associated. To use the example in Visual Studio, compile the code to a class library, and add the IntStandardValuesControl component to the Toolbox. Add an instance of the IntStandardValuesControl to a form in design mode, and scroll to the TestInt property in the Properties window while the control is selected. Selecting the value entry field for the property displays a down arrow that displays a drop-down list of standard values when clicked. Entering an integer value will add the value to the list of standard values, and set the property to the specified value.

No code example is currently available or this language may not be supported.

The .NET Framework provides the capability to generate dynamic property initialization code at design time that will initialize a property at run time.

Developers can build a type converter that produces constructor-based initialization code. These type converters can generate constructor code dynamically using values set at design time in order to configure properties of a type at run time. The type converter implements the logic to configure the type and values of a constructor for the property.

If you need to produce code besides a constructor to initialize a property, it is possible to dynamically generate code by implementing a custom CodeDomSerializer and applying a DesignerSerializerAttribute that associates your CodeDomSerializer for a type with the type. This approach is typically used only for scenarios in which dynamically controlled or customized code generation for component initialization is important. For more information on this approach, see the documentation for CodeDomSerializer.

To build a custom constructor-based property initializer, you must associate a type converter with the type of the property to initialize, and the type converter must be able to convert to an InstanceDescriptor.

To implement a type converter that produces constructor-based property initialization code

  1. Define a class that derives from TypeConverter.

  2. Override the CanConvertTo method. If the destinationType parameter equals InstanceDescriptor type, return true.

  3. Override the ConvertTo method. If the destinationType parameter equals the InstanceDescriptor type, construct and return an InstanceDescriptor that represents the constructor and constructor arguments to generate code for. To create an InstanceDescriptor that represents the appropriate constructor and parameters, obtain a ConstructorInfo from the Type of the property you are initializing by calling the GetConstructoror GetConstructors method with the appropriate method signature of the constructor you are seeking. Then create a new instance descriptor and pass the ConstructorInfo for the type that represents the constructor type to use, along with an array of parameter objects that match the constructor signature.

The following example implements a type converter that can generate constructor-based property initialization code for properties of type Point.

public class PointConverter : TypeConverter 
{
   public override bool CanConvertTo(ITypeDescriptorContext context, Type destinationType) 
   {
      if (destinationType == typeof(InstanceDescriptor)) 
         return true;
      return base.CanConvertTo(context, destinationType);
   }

public override object ConvertTo(ITypeDescriptorContext context, 
CultureInfo culture, object value, Type destinationType) 
{
      // Insert other ConvertTo operations here.
      //
      if (destinationType == typeof(InstanceDescriptor) && 
value is Point) 
   {
         Point pt = (Point)value;

      ConstructorInfo ctor = typeof(Point).GetConstructor(
new Type[] {typeof(int), typeof(int)});
      if (ctor != null) 
      {
         return new InstanceDescriptor(ctor, new object[] {pt.X, pt.Y});
}
}
   return base.ConvertTo(context, culture, value, destinationType);      
}

  • When you develop your custom TypeConverter, it is recommended that you set the build number to increment with each build. This prevents older, cached versions of your TypeConverter from being created in the design environment.

Show: