TypeConverter Class (System.ComponentModel)

TypeConverter Class

Note
The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Provides a unified way of converting types of values to other types, as well as for accessing standard values and subproperties.

Namespace: System.ComponentModel
Assembly: System (in System.dll)

Inheritance Hierarchy

Syntax

[ComVisibleAttribute(true)]
[HostProtectionAttribute(SecurityAction.LinkDemand, SharedState = true)]
public class TypeConverter

[ComVisibleAttribute(true)]
[HostProtectionAttribute(SecurityAction::LinkDemand, SharedState = true)]
public ref class TypeConverter

[<ComVisibleAttribute(true)>]
[<HostProtectionAttribute(SecurityAction.LinkDemand, SharedState = true)>]
type TypeConverter = class end

<ComVisibleAttribute(True)>
<HostProtectionAttribute(SecurityAction.LinkDemand, SharedState := True)>
Public Class TypeConverter

Constructors

	Name	Description
	TypeConverter	Initializes a new instance of the TypeConverter class.

Methods

	Name	Description
	CanConvertFrom	Returns whether this converter can convert an object of the given type to the type of this converter, using the specified context.
	CanConvertFrom	Returns whether this converter can convert an object of the given type to the type of this converter.
	CanConvertTo	Returns whether this converter can convert the object to the specified type, using the specified context.
	CanConvertTo	Returns whether this converter can convert the object to the specified type.
	ConvertFrom	Converts the given object to the type of this converter, using the specified context and culture information.
	ConvertFrom	Converts the given value to the type of this converter.
	ConvertFromInvariantString	Converts the given string to the type of this converter, using the invariant culture and the specified context.
	ConvertFromInvariantString	Converts the given string to the type of this converter, using the invariant culture.
	ConvertFromString	Converts the given text to an object, using the specified context and culture information.
	ConvertFromString	Converts the given text to an object, using the specified context.
	ConvertFromString	Converts the specified text to an object.
	ConvertTo	Converts the given value object to the specified type, using the specified context and culture information.
	ConvertTo	Converts the given value object to the specified type, using the arguments.
	ConvertToInvariantString	Converts the specified value to a culture-invariant string representation, using the specified context.
	ConvertToInvariantString	Converts the specified value to a culture-invariant string representation.
	ConvertToString	Converts the given value to a string representation, using the specified context and culture information.
	ConvertToString	Converts the given value to a string representation, using the given context.
	ConvertToString	Converts the specified value to a string representation.
	CreateInstance	Re-creates an Object given a set of property values for the object.
	CreateInstance	Creates an instance of the type that this TypeConverter is associated with, using the specified context, given a set of property values for the object.
	Equals	Determines whether the specified object is equal to the current object.(Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)
	GetConvertFromException	Returns an exception to throw when a conversion cannot be performed.
	GetConvertToException	Returns an exception to throw when a conversion cannot be performed.
	GetCreateInstanceSupported	Returns whether changing a value on this object requires a call to the CreateInstance method to create a new value.
	GetCreateInstanceSupported	Returns whether changing a value on this object requires a call to CreateInstance to create a new value, using the specified context.
	GetHashCode	Serves as the default hash function. (Inherited from Object.)
	GetProperties	Returns a collection of properties for the type of array specified by the value parameter, using the specified context.
	GetProperties	Returns a collection of properties for the type of array specified by the value parameter, using the specified context and attributes.
	GetProperties	Returns a collection of properties for the type of array specified by the value parameter.
	GetPropertiesSupported	Returns whether this object supports properties.
	GetPropertiesSupported	Returns whether this object supports properties, using the specified context.
	GetStandardValues	Returns a collection of standard values from the default context for the data type this type converter is designed for.
	GetStandardValues	Returns a collection of standard values for the data type this type converter is designed for when provided with a format context.
	GetStandardValuesExclusive	Returns whether the collection of standard values returned from GetStandardValues is an exclusive list.
	GetStandardValuesExclusive	Returns whether the collection of standard values returned from GetStandardValues is an exclusive list of possible values, using the specified context.
	GetStandardValuesSupported	Returns whether this object supports a standard set of values that can be picked from a list.
	GetStandardValuesSupported	Returns whether this object supports a standard set of values that can be picked from a list, using the specified context.
	GetType	Gets the Type of the current instance.(Inherited from Object.)
	IsValid	Returns whether the given value object is valid for this type and for the specified context.
	IsValid	Returns whether the given value object is valid for this type.
	MemberwiseClone	Creates a shallow copy of the current Object.(Inherited from Object.)
	SortProperties	Sorts a collection of properties.
	ToString	Returns a string that represents the current object.(Inherited from Object.)

Remarks

The most common type of converter is one that converts to and from a text representation. The type converter for a class is bound to the class with a TypeConverterAttribute. Unless this attribute is overridden, all classes that inherit from this class use the same type converter as the base class.

Note
For general type system purposes, do not access a type converter directly. Instead, access the appropriate converter by using TypeDescriptor. For more information, see the code examples provided.

Note For XAML purposes, a XAML processor searches for the TypeConverterAttribute directly, instead of going through TypeDescriptor. For cases where you do want a TypeDescriptor instance from code, or where you create a shared instance in WPF resources, it is acceptable to construct it directly without referencing TypeDescriptor or other reflection and type system support.

Classes derived from TypeConverter are often referenced as part of how a XAML processor converts an attribute or initialization text value from markup (which is inherently a string) and generates an object for a run-time representation. Custom type authors that intend to support a type conversion behavior for XAML typically implement a TypeConverter class that supports their own unique ConvertFrom behavior from a string. This behavior enables type conversion from the string provided as a XAML attribute value and provides a XAML processor with the support needed to create an object from the string, so that the object can be produced in a parsed object graph. Custom types or members of custom types are indicated by applying TypeConverterAttribute to the definitions, with the attribute referencing the custom TypeConverter implementation. For more information, see Type Converters for XAML Overview.

Notes to Inheritors:

Inherit from TypeConverter to implement your own conversion requirements. When you inherit from this class, you can override the following methods:

To support custom type conversion, override the CanConvertFrom, CanConvertTo, ConvertFrom, and ConvertTo methods.
To convert types that must re-create the object to change its value, override the CreateInstance and GetCreateInstanceSupported methods.
To convert types that support properties, override the GetProperties and GetPropertiesSupported methods. If the class you are converting does not have properties, and you need to implement properties, you can use the TypeConverterSimplePropertyDescriptor class as a base for implementing the property descriptors. When you inherit from TypeConverterSimplePropertyDescriptor, you must override the GetValue and SetValue methods.
To convert types that support standard values, override the GetStandardValues, GetStandardValuesExclusive, GetStandardValuesSupported and IsValid methods.

Note
Your derived type might be marked as internal or private, but an instance of your type can be created with the TypeDescriptor class. Do not write insecure code by assuming the caller is trusted. Assume instead that callers might create instances of your type in partial trust.

For more information about type converters for general (non-XAML) purposes, see How to: Implement a Type Converter or Generalized Type Conversion.

Examples

The following code example shows how to create an instance of a type converter and bind it to a class. The class implementing the converter, MyClassConverter, must inherit from the TypeConverter class.

[TypeConverter(typeof(MyClassConverter))]
 public class MyClass {
    // Insert code here.
}

<TypeConverter(GetType(MyClassConverter))> _
Public Class Class1
    ' Insert code here.
End Class 'MyClassMyClass

public:
   [TypeConverter(Sample::MyClassConverter::typeid)]
   ref class MyClass
   {
      // Insert code here.
   };

When you have a property that has an enumeration, check to see whether an enumeration value is valid before setting the property. The next code example requires that an enumeration called MyPropertyEnum has been declared.

public MyPropertyEnum MyProperty {
    set {
       // Checks to see if the value passed is valid.
       if (!TypeDescriptor.GetConverter(typeof(MyPropertyEnum)).IsValid(value)) {
          throw new ArgumentException();
       }
       // The value is valid. Insert code to set the property.
    }
 }


Public WriteOnly Property MyProperty() As MyPropertyEnum
    Set
        ' Checks to see if the value passed is valid.
        If Not TypeDescriptor.GetConverter(GetType(MyPropertyEnum)).IsValid(value) Then
            Throw New ArgumentException()
        End If
        ' The value is valid. Insert code to set the property.
    End Set 
End Property

public:
   property MyPropertyEnum MyProperty 
   {
      void set( MyPropertyEnum value )
      {
         // Checks to see if the value passed is valid.
         if ( !TypeDescriptor::GetConverter( MyPropertyEnum::typeid )->IsValid( value ) )
         {
            throw gcnew ArgumentException;
         }
         // The value is valid. Insert code to set the property.
      }
   }

Another common type converter usage is to convert an object to a string. The following code example prints out the name of the Color stored in the variable c.

Color c = Color.Red;
    Console.WriteLine(TypeDescriptor.GetConverter(c).ConvertToString(c));

Dim c As Color = Color.Red
Console.WriteLine(TypeDescriptor.GetConverter(c).ConvertToString(c))

Color c = Color::Red;
Console::WriteLine( TypeDescriptor::GetConverter( c )->ConvertToString( c ) );

You can also use a type converter to convert a value from its name, as shown in the next code example.

Color c = (Color)TypeDescriptor.GetConverter(typeof(Color)).ConvertFromString("Red");

Dim c As Color = CType(TypeDescriptor.GetConverter(GetType(Color)).ConvertFromString("Red"), Color)

Color c =  (Color)(TypeDescriptor::GetConverter( Color::typeid )->ConvertFromString( "Red" ));

In the following code example, you can use a type converter to print out the set of standard values that the object supports.

foreach(Color c in TypeDescriptor.GetConverter(typeof(Color)).GetStandardValues()) {
    Console.WriteLine(TypeDescriptor.GetConverter(c).ConvertToString(c));
 }

Dim c As Color
For Each c In  TypeDescriptor.GetConverter(GetType(Color)).GetStandardValues()
    Console.WriteLine(TypeDescriptor.GetConverter(c).ConvertToString(c))
Next c

for each ( Color c in TypeDescriptor::GetConverter( Color::typeid )->GetStandardValues() )
{
   Console::WriteLine( TypeDescriptor::GetConverter( c )->ConvertToString( c ) );
}

Version Information

.NET Framework
Available since 1.1
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0

Thread Safety

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.