TypeConverters and XAML
The TypeConverter class serves a particular purpose as part of the implementation for a managed class that can be used as a property value in Extensible Application Markup Language (XAML) attribute usage. If you write a custom class, and you want instances of your class to be usable as Extensible Application Markup Language (XAML) settable attribute, you might need to apply a TypeConverterAttribute to your class, write a custom TypeConverter class, or both.
This topic contains the following sections.
- XAML and String Values
- Implementing a Type Converter
- Applying the TypeConverterAttribute
- Related Topics
XAML and String Values
When you set an attribute value in XAML, the initial type of that value is String. Even other primitives such as Double are initially strings to a XAML loader, although the conversion between primitive values and named values of an enumeration is relatively straightforward.
A XAML loader needs two pieces of information in order to process an attribute value. The first piece of information is the value type of the property that is being set. Any string value that is loaded in XAML must ultimately be converted or resolved to a value of that type. If the value is a primitive, a direct conversion of the string is attempted. If the value is an enumeration, the string is used to check for a name match in that enumeration. If there is a name match, the value associated with the name is returned.
Another special case is a markup extension. Markup extension usages must be processed by a XAML loader prior to checking for property type and other considerations. The purpose of a markup extension is to process a string and return an object. If the object returned is a type match for the property, the markup extension supplies a value for a property in a manner that avoids any type conversion taking place outside of the markup extension implementation code. For more information on markup extensions, see Markup Extensions and XAML.
TypeConverter
If the value is not a primitive type or enum, and there is no markup extension usage, then there must be some means of converting a String to the appropriate value type. This is the role of the TypeConverter implementation. TypeConverter defines four members that are relevant for converting to and from strings for XAML purposes:
Of these, the most important method is ConvertFrom. This method converts a string to the required object type.
The next most important method is ConvertTo. If a WPF application is converted to a markup representation, ConvertTo is responsible for producing a markup representation of the value.
CanConvertTo and CanConvertFrom are support methods that are used when some service queries the capabilities of a TypeConverter implementation. You must implement these methods to return true for certain cases, particularly for the String type.
Implementing a Type Converter
Implementing ConvertFrom
To be usable as a TypeConverter implementation that supports XAML, the ConvertFrom method for that converter must accept a string as the value parameter. If the string was in valid format, TypeConverter implementation, then the returned object must castable to the type expected by the property. Otherwise, the ConvertFrom implementation must return null.
Each TypeConverter implementation can have its own interpretation of what constitutes a valid string for a conversion, and can also use or ignore the type description or culture contexts passed as parameters.
.gif) Note: |
|---|
Do not use the curly brace characters, particularly {, as a possible element of your string format. These characters are reserved as the entry and exit for a markup extension sequence. |
Implementing ConvertTo
ConvertTo is for serialization support. Serialization support for your custom type is not an absolute requirement. However, if you are implementing a control, or using serialization of as part of the features or design of your class, you will need to implement ConvertTo.
To be usable as a TypeConverter implementation that supports XAML, the ConvertTo method for that converter must accept an instance of the type being supported as the value parameter. When the destinationType parameter is type String, then the returned object must castable to String. The returned string must represent a serialized value of value. Ideally, the serialization format you choose should be capable of generating the same value if that string were passed to the ConvertFrom implementation of the same converter, without significant loss of information.
If the value cannot be serialized, or the converter does not support serialization, the ConvertTo implementation must return null, and is permitted to raise an exception in this case.
If destinationType parameter is not of type String, you can choose your own converter handling. Typically you would revert to base implementation handling.
Each TypeConverter implementation can have its own interpretation of what constitutes a valid string for a conversion, and can also use or ignore the type description or culture contexts passed as parameters.
| Note: |
|---|
Do not use the curly brace characters, particularly {, as a possible element of your string format. These characters are reserved as the entry and exit for a markup extension sequence. |
Implementing CanConvertTo
Your CanConvertTo implementation should return true for destinationType of type String., and otherwise revert to the base implementation.
Implementing CanConvertTo
Your CanConvertFrom implementation should return true for sourceType of type String., and otherwise revert to the base implementation.
Applying the TypeConverterAttribute
In order for your custom type converter to be used as the acting type converter for a custom class, you must apply the .NET Framework attribute TypeConverterAttribute to your class definition. The ConverterTypeName that you specify through the attribute must be the type of your custom type converter. With this attribute applied, when a XAML loader processes values where the property type uses your custom class type, the XAML loader can process input strings and return object instances.
You can also provide a type converter on a per-property basis. Instead of applying a .NET Framework attribute TypeConverterAttribute to the class definition, apply it to a property definition (the main definition, not the get/set implementations within it). The type of the property must match the type that is processed by your custom type converter. With this attribute applied, when a XAML loader processes values of that property, the XAML loader can process input strings and return object instances. The per-property type converter technique is particularly useful if you choose to use a property type from Microsoft .NET Framework or from some other library where you cannot control the class definition and apply a TypeConverterAttribute there.
See Also
Reference
Concepts
XAML Overview
Markup Extensions and XAML
XAML Syntax Terminology