TypeConverters et XAMLTypeConverters and XAML

Cette rubrique présente l’objectif de la conversion de types de chaîne comme une fonctionnalité générale du langage XAML.This topic introduces the purpose of type conversion from string as a general XAML language feature. Dans le .NET Framework, la TypeConverter classe sert un objectif particulier dans le cadre de l’implémentation pour une classe personnalisée managée qui peut être utilisée en tant que valeur de propriété dans l’utilisation d’attribut XAML.In the .NET Framework, the TypeConverter class serves a particular purpose as part of the implementation for a managed custom class that can be used as a property value in XAML attribute usage. Si vous écrivez une classe personnalisée, et que les instances de la classe soient utilisables comme valeurs d’attribut définissables XAML, vous devrez peut-être appliquer un TypeConverterAttribute à votre classe, écrire une personnalisée TypeConverter classe, ou les deux.If you write a custom class, and you want instances of your class to be usable as XAML settable attribute values, you might need to apply a TypeConverterAttribute to your class, write a custom TypeConverter class, or both.

Concepts de conversion de typeType Conversion Concepts

XAML et valeurs de chaîneXAML and String Values

Quand vous définissez une valeur d’attribut dans un fichier XAML, le type initial de cette valeur est une chaîne en texte pur.When you set an attribute value in a XAML file, the initial type of that value is a string in pure text. Même d’autres primitives telles que Double sont initialement des chaînes de texte à un processeur XAML.Even other primitives such as Double are initially text strings to a XAML processor.

Un processeur XAML a besoin de deux types d’informations pour pouvoir traiter une valeur d’attribut.A XAML processor needs two pieces of information in order to process an attribute value. Le premier élément d'information est le type valeur de la propriété à définir.The first piece of information is the value type of the property that is being set. N'importe quelle chaîne qui définit une valeur d'attribut et qui est traitée en XAML doit au final être convertie ou résolue en une valeur de ce type.Any string that defines an attribute value and that is processed in XAML must ultimately be converted or resolved to a value of that type. Si la valeur est une primitive comprise par l'analyseur XAML (telle qu'une valeur numérique), une conversion directe de la chaîne est tentée.If the value is a primitive that is understood by the XAML parser (such as a numeric value), a direct conversion of the string is attempted. Si la valeur est une énumération, la chaîne est utilisée pour rechercher une correspondance de nom à une constante nommée dans cette énumération.If the value is an enumeration, the string is used to check for a name match to a named constant in that enumeration. Si la valeur n’est ni une primitive comprise par l’analyseur, ni une énumération, le type en question doit pouvoir fournir une instance du type ou une valeur, en fonction d’une chaîne convertie.If the value is neither a parser-understood primitive nor an enumeration, then the type in question must be able to provide an instance of the type, or a value, based on a converted string. Pour cela, vous devez indiquer une classe de convertisseur de type.This is done by indicating a type converter class. Le convertisseur de type est une classe d’assistance qui sert à fournir des valeurs d’une autre classe, pour le scénario XAML et éventuellement pour les appels de code dans le code .NET.The type converter is effectively a helper class for providing values of another class, both for the XAML scenario and also potentially for code calls in .NET code.

Utilisation du comportement de conversion de types existant en XAMLUsing Existing Type Conversion Behavior in XAML

En fonction de votre connaissance des concepts XAML sous-jacents, il se peut que vous utilisiez déjà un comportement de conversion de types dans des applications XAML de base sans vous en rendre compte.Depending on your familiarity with the underlying XAML concepts, you may already be using type conversion behavior in basic application XAML without realizing it. Par exemple, WPF définit des centaines de propriétés qui prennent une valeur de type Point.For instance, WPF defines literally hundreds of properties that take a value of type Point. Un Point est une valeur qui décrit une coordonnée dans un espace de coordonnées à deux dimensions, et il a deux propriétés importantes : X et Y.A Point is a value that describes a coordinate in a two-dimensional coordinate space, and it really just has two important properties: X and Y. Lorsque vous spécifiez un point en XAML, vous le spécifiez sous forme de chaîne avec un séparateur (en général une virgule) entre le X et Y valeurs que vous fournissez.When you specify a point in XAML, you specify it as a string with a delimiter (typically a comma) between the X and Y values you provide. Par exemple : <LinearGradientBrush StartPoint="0,0" EndPoint="1,1"/>.For example: <LinearGradientBrush StartPoint="0,0" EndPoint="1,1"/>.

Même ce type simple de Point et son utilisation simple en XAML impliquent un convertisseur de type.Even this simple type of Point and its simple usage in XAML involve a type converter. Dans ce cas, c’est la classe PointConverter.In this case that is the class PointConverter.

Le convertisseur de type pour Point défini à la rationalisation de niveau classe les utilisations de balisage de toutes les propriétés qui acceptent Point.The type converter for Point defined at the class level streamlines the markup usages of all properties that take Point. Sans un convertisseur de type ici, vous auriez besoin de la balise suivante beaucoup plus détaillée pour l’exemple indiqué précédemment :Without a type converter here, you would need the following much more verbose markup for the same example shown previously:

<LinearGradientBrush>
  <LinearGradientBrush.StartPoint>
    <Point X="0" Y="0"/>
  </LinearGradientBrush.StartPoint>
  <LinearGradientBrush.EndPoint>
    <Point X="1" Y="1"/>
  </LinearGradientBrush.EndPoint>
</LinearGradientBrush>

L’utilisation d’une chaîne de conversion de type ou d’une syntaxe équivalente plus détaillée est une question de style de codage.Whether to use the type conversion string or a more verbose equivalent syntax is generally a coding style choice. Votre workflow d’outils XAML peut également influencer la définition des valeurs.Your XAML tooling workflow might also influence how values are set. Certains outils XAML ont tendance à émettre la forme la plus détaillée du balisage, car il est plus facile de parcourir les vues du concepteur ou son propre mécanisme de sérialisation.Some XAML tools tend to emit the most verbose form of the markup because it is easier to round-trip to designer views or its own serialization mechanism.

Convertisseurs de types existants peuvent être généralement découverts sur les types WPF et .NET Framework en recherchant une classe (ou propriété) de la présence d’une application TypeConverterAttribute.Existing type converters can generally be discovered on WPF and .NET Framework types by checking a class (or property) for the presence of an applied TypeConverterAttribute. Cet attribut nomme la classe qui est le convertisseur de type de prise en charge pour les valeurs de ce type, pour les besoins XAML et éventuellement d’autres usages.This attribute will name the class that is the supporting type converter for values of that type, for XAML purposes as well as potentially other purposes.

Convertisseurs de type et extensions de balisageType Converters and Markup Extensions

Les extensions de balisage et les convertisseurs de types remplissent des rôles orthogonaux quant au comportement du processeur XAML et aux scénarios auxquels ils s’appliquent.Markup extensions and type converters fill orthogonal roles in terms of XAML processor behavior and the scenarios that they are applied to. Bien que le contexte soit disponible pour les extensions de balisage, le comportement de la conversion de type des propriétés où une extension de balisage fournit une valeur n’est généralement pas vérifié dans les implémentations d’extension de balisage.Although context is available for markup extension usages, type conversion behavior of properties where a markup extension provides a value is generally is not checked in the markup extension implementations. En d’autres termes, même si une extension de balisage retourne une chaîne de texte comme sortie ProvideValue, le comportement de conversion de type associé à cette chaîne tel qu’il est appliqué à une propriété ou un type de valeur de propriété spécifique n’est pas appelé. En général, la fonction d’une extension de balisage consiste à traiter une chaîne et retourner un objet sans faire appel à un convertisseur de type.In other words, even if a markup extension returns a text string as its ProvideValue output, type conversion behavior on that string as applied to a specific property or property value type is not invoked, Generally, the purpose of a markup extension is to process a string and return an object without any type converter involved.

Dans le cadre de la création d’une référence à un objet existant, il est courant d’utiliser une extension de balisage à la place d’un convertisseur de type.One common situation where a markup extension is necessary rather than a type converter is to make a reference to an object that already exists. Au mieux, un convertisseur de type sans état générerait uniquement une nouvelle instance, ce qui peut ne pas être souhaitable.At best, a stateless type converter could only generate a new instance, which might not be desirable. Pour plus d’informations sur les extensions de balisage, consultez Extensions de balisage et XAML WPF.For more information on markup extensions, see Markup Extensions and WPF XAML.

Convertisseurs de type natifNative Type Converters

Dans une implémentation WPF et .NET Framework de l’analyseur XAML, certains types gèrent nativement la conversion de type ; cependant, ces types ne sont pas traditionnellement considérés comme des primitives.In the WPF and .NET Framework implementation of the XAML parser, there are certain types that have native type conversion handling, yet are not types that might conventionally be thought of as primitives. Un exemple d'un tel type est DateTime.An example of such a type is DateTime. La raison à cela est basée sur le fonctionne de l’architecture .NET Framework : le type DateTime est défini dans mscorlib, la bibliothèque de base dans .NET.The reason for this is based on how the .NET Framework architecture works: the type DateTime is defined in mscorlib, the most basic library in .NET. DateTime ne peut pas être attribué avec un attribut qui provient d’un autre assembly qui présente une dépendance (TypeConverterAttribute vient de System) afin du mécanisme de découverte de convertisseur de type habituel par attribution ne peut pas être pris en charge.DateTime is not permitted to be attributed with an attribute that comes from another assembly that introduces a dependency (TypeConverterAttribute is from System) so the usual type converter discovery mechanism by attributing cannot be supported. À la place, l’analyseur XAML dispose d’une liste des types qui doivent faire l’objet d’un traitement natif et traite ces types de la même façon que les véritables primitives.Instead, the XAML parser has a list of types that need such native processing and processes these similarly to how the true primitives are processed. (Dans le cas de DateTime cela implique un appel à Parse.)(In the case of DateTime this involves a call to Parse.)

Implémentation d'un convertisseur de typeImplementing a Type Converter

TypeConverterTypeConverter

Dans le Point exemple indiquée précédemment, la classe PointConverter mentionné.In the Point example given previously, the class PointConverter was mentioned. Pour les implémentations .NET de XAML, tous les convertisseurs de type qui sont utilisés à des fins XAML sont des classes qui dérivent de la classe de base TypeConverter.For .NET implementations of XAML, all type converters that are used for XAML purposes are classes that derive from the base class TypeConverter. Le TypeConverter classe existait dans les versions du .NET Framework qui précèdent l’existence de XAML ; un de ses utilisations d’origine était de fournir une conversion de chaîne pour les boîtes de dialogue de propriété dans les concepteurs visuels.The TypeConverter class existed in versions of .NET Framework that precede the existence of XAML; one of its original usages was to provide string conversion for property dialogs in visual designers. Pour XAML, le rôle de TypeConverter est étendu pour inclure la classe de base pour les conversions en chaînes et à partir de chaînes qui permettent l’analyse d’une valeur d’attribut de chaîne et le traitement d’une valeur d’exécution d’une propriété d’objet particulier dans une chaîne pour sérialisation en tant qu’attribut.For XAML, the role of TypeConverter is expanded to include being the base class for to-string and from-string conversions that enable parsing a string attribute value, and possibly processing a run-time value of a particular object property back into a string for serialization as an attribute.

TypeConverter définit quatre membres qui sont utiles pour la conversion vers et à partir de chaînes à des fins de traitement de XAML :TypeConverter defines four members that are relevant for converting to and from strings for XAML processing purposes:

Parmi ceux-ci, la méthode la plus importante est ConvertFrom.Of these, the most important method is ConvertFrom. Cette méthode convertit la chaîne d’entrée en type d’objet exigé.This method converts the input string to the required object type. À proprement parler, la ConvertFrom méthode peut être implémentée pour convertir une plage beaucoup plus large de types en type de destination prévu du convertisseur et donc permettre à des fins qui dépassent le XAML telles que la prise en charge des conversions au moment de l’exécution, mais à des fins de XAML Il est uniquement le chemin de code qui peut traiter un String entrée est important.Strictly speaking, the ConvertFrom method could be implemented to convert a much wider range of types into the converter's intended destination type, and thus serve purposes that extend beyond XAML such as supporting run-time conversions, but for XAML purposes it is only the code path that can process a String input that matters.

La méthode la plus importante suivante est ConvertTo.The next most important method is ConvertTo. Si une application est convertie en une représentation de balisage (par exemple, si elle est enregistrée en XAML sous forme de fichier), ConvertTo est chargée de produire une représentation de balisage.If an application is converted to a markup representation (for instance, if it is saved to XAML as a file), ConvertTo is responsible for producing a markup representation. Dans ce cas, le chemin d’accès du code qui est important pour XAML est lorsque vous passez un destinationType de String .In this case, the code path that matters for XAML is when you pass a destinationType of String .

CanConvertTo et CanConvertFrom sont des méthodes de support utilisées lorsqu'un service interroge les fonctions de l'implémentation TypeConverter .CanConvertTo and CanConvertFrom are support methods that are used when a service queries the capabilities of the TypeConverter implementation. Vous devez implémenter ces méthodes pour retourner true dans des cas spécifiques au type pris en charge par les méthodes de conversion correspondantes de votre convertisseur.You must implement these methods to return true for type-specific cases that the equivalent conversion methods of your converter support. Pour le langage XAML, cela correspond généralement au type String .For XAML purposes, this generally means the String type.

Informations de culture et convertisseurs de type pour XAMLCulture Information and Type Converters for XAML

Chaque TypeConverter implémentation peut avoir sa propre interprétation de ce qui constitue une chaîne valide pour une conversion et peut également utiliser ou ignorer la description de type passée comme paramètres.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 passed as parameters. Vous devez tenir compte d’un élément fondamental en ce qui concerne la culture et la conversion de type XAML.There is an important consideration with regard to culture and XAML type conversion. L’utilisation de chaînes localisables comme valeurs d’attribut est intégralement prise en charge par XAML.Using localizable strings as attribute values is entirely supported by XAML. Mais l’utilisation de cette chaîne localisable comme entrée de convertisseur de type avec des spécifications de culture spécifiques n’est pas prise en charge, car les convertisseurs de types pour les valeurs d’attribut XAML impliquent un comportement d’analyse de langage fixe, à l’aide de la culture en-US.But using that localizable string as type converter input with specific culture requirements is not supported, because type converters for XAML attribute values involve a necessarily fixed-language parsing behavior, using en-US culture. Pour plus d’informations sur les raisons de conception de cette restriction, consultez la spécification de langage XAML ([MS-XAML]).For more information on the design reasons for this restriction, you should consult the XAML language specification ([MS-XAML]).

Par exemple, certaines cultures utilisent une virgule comme séparateur décimal pour les nombres, ce qui peut être un problème.As an example where culture can be an issue, some cultures use a comma as their decimal point delimiter for numbers. Cela crée un conflit avec de nombreux convertisseurs de types XAML WPF qui utilisent une virgule comme séparateur (pour des raisons historiques : forme X,Y courante ou listes délimitées par des virgules).This will collide with the behavior that many of the WPF XAML type converters have, which is to use a comma as a delimiter (based on historical precedents such as the common X,Y form, or comma delimited lists). Même le passage d’une culture dans le XAML voisin (affectation à Language ou xml:lang de la culture sl-SI, un exemple de culture utilisant une virgule comme séparateur décimal) ne résout pas le problème.Even passing a culture in the surrounding XAML (setting Language or xml:lang to the sl-SI culture, an example of a culture that uses a comma for decimal in this way) does not solve the issue.

Implémentation de ConvertFromImplementing ConvertFrom

Pour être utilisable en tant qu'implémentation TypeConverter qui prend en charge le code XAML, la méthode ConvertFrom du convertisseur doit accepter une chaîne comme paramètre value .To be usable as a TypeConverter implementation that supports XAML, the ConvertFrom method for that converter must accept a string as the value parameter. Si la chaîne a valide de format et peut être convertie par la TypeConverter implémentation, puis l’objet retourné doit prendre en charge un cast en type attendu par la propriété.If the string was in valid format, and can be converted by the TypeConverter implementation, then the returned object must support a cast to the type expected by the property. Sinon, l'implémentation ConvertFrom doit retourner null.Otherwise, the ConvertFrom implementation must return null.

Chaque TypeConverter implémentation peut avoir sa propre interprétation de ce qui constitue une chaîne valide pour une conversion et peut également utiliser ou ignorer les contextes de culture ou de description de type passés comme paramètres.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. Cependant, le traitement XAML WPF peut ne pas passer de valeurs au contexte de description de type dans tous les cas, et également ne pas passer la culture en fonction de xml:lang.However, the WPF XAML processing might not pass values to the type description context in all cases, and also might not pass culture based on xml:lang.

Notes

N’utilisez pas les accolades, en particulier {, comme élément possible de format de chaîne.Do not use the curly brace characters, particularly {, as a possible element of your string format. Ces caractères sont réservés comme entrée et sortie d’une séquence d’extension de balisage.These characters are reserved as the entry and exit for a markup extension sequence.

Implémentation de ConvertToImplementing ConvertTo

La méthodeConvertTo peut être utilisée pour assurer la prise en charge de la sérialisation.ConvertTo is potentially used for serialization support. La prise en charge de la sérialisation via ConvertTo pour votre type personnalisé et son convertisseur de type n'est pas une spécification absolue.Serialization support through ConvertTo for your custom type and its type converter is not an absolute requirement. Toutefois, si vous implémentez un contrôle ou que vous utilisez la sérialisation dans le cadre des fonctionnalités ou de la conception de la classe, vous devez implémenter ConvertTo.However, if you are implementing a control, or using serialization of as part of the features or design of your class, you should implement ConvertTo.

Pour être utilisable en tant qu’un TypeConverter implémentation qui prend en charge XAML, la ConvertTo méthode pour ce convertisseur doit accepter une instance du type (ou une valeur) prise en charge en tant que le value paramètre.To be usable as a TypeConverter implementation that supports XAML, the ConvertTo method for that converter must accept an instance of the type (or a value) being supported as the value parameter. Lorsque le destinationType paramètre est le type String, puis l’objet retourné doit pouvoir être casté en String.When the destinationType parameter is the type String, then the returned object must be able to be cast as String. La chaîne retournée doit représenter une valeur sérialisée de value.The returned string must represent a serialized value of value. Dans l’idéal, le format de sérialisation que vous choisissez doit être capable de générer la même valeur si cette chaîne est passée à la ConvertFrom implémentation du même convertisseur, sans perte significative d’informations.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.

Si la valeur ne peut pas être sérialisée ou que le convertisseur ne prend pas en charge la sérialisation, le ConvertTo implémentation doit retourner null, il est autorisé à lever une exception dans ce cas.If the value cannot be serialized, or the converter does not support serialization, the ConvertTo implementation must return null, and is permitted to throw an exception in this case. Mais si vous levez des exceptions, vous devez signaler l’incapacité à utiliser cette conversion dans le cadre de votre CanConvertTo implémentation afin que la meilleure pratique de vérification avec CanConvertTo tout d’abord pour éviter les exceptions est pris en charge.But if you do throw exceptions, you should report the inability to use that conversion as part of your CanConvertTo implementation so that the best practice of checking with CanConvertTo first to avoid exceptions is supported.

Si destinationType paramètre n’est pas de type String, vous pouvez choisir votre propre gestion de convertisseur.If destinationType parameter is not of type String, you can choose your own converter handling. En règle générale, vous rétablissez l’implémentation de base de gestion des, qui, dans le traitement ConvertTo lève une exception spécifique.Typically, you would revert to base implementation handling, which in the basemost ConvertTo raises a specific exception.

Implémentation de CanConvertToImplementing CanConvertTo

Votre implémentation de CanConvertTo doit retourner la valeur true pour destinationType de type String, et sinon déférer à l'implémentation de base.Your CanConvertTo implementation should return true for destinationType of type String, and otherwise defer to the base implementation.

Implémentation de CanConvertFromImplementing CanConvertFrom

Votre implémentation de CanConvertFrom doit retourner la valeur true pour sourceType de type String, et sinon déférer à l'implémentation de base.Your CanConvertFrom implementation should return true for sourceType of type String, and otherwise defer to the base implementation.

Application de TypeConverterAttributeApplying the TypeConverterAttribute

Dans l’ordre pour le convertisseur de type personnalisé à utiliser en tant que le convertisseur convertisseur de type pour une classe personnalisée par un processeur XAML, vous devez appliquer le attribut .NET Framework.NET Framework attribute TypeConverterAttribute à votre définition de classe.In order for your custom type converter to be used as the acting type converter for a custom class by a XAML processor, you must apply the attribut .NET Framework.NET Framework attribute TypeConverterAttribute to your class definition. La propriété ConverterTypeName que vous spécifiez via l'attribut doit être le nom de type du convertisseur de type personnalisé.The ConverterTypeName that you specify through the attribute must be the type name of your custom type converter. Une fois cet attribut appliqué, quand un processeur XAML gère des valeurs où le type de propriété utilise votre type de classe personnalisée, il peut entrer des chaînes et retourner des instances d’objet.With this attribute applied, when a XAML processor handles values where the property type uses your custom class type, it can input strings and return object instances.

Vous pouvez également fournir un convertisseur de type en fonction de la propriété.You can also provide a type converter on a per-property basis. Au lieu d'appliquer un attribut .NET Framework.NET Framework attribute TypeConverterAttribute à la définition de classe, appliquez-le à une définition de propriété (c'est-à-dire à la définition principale, et non pas aux implémentations de get/set qu'elle contient).Instead of applying a attribut .NET Framework.NET Framework attribute TypeConverterAttribute to the class definition, apply it to a property definition (the main definition, not the get/set implementations within it). Le type de la propriété doit correspondre au type traité par votre convertisseur de type personnalisé.The type of the property must match the type that is processed by your custom type converter. Une fois cet attribut appliqué, quand un processeur XAML gère des valeurs de cette propriété, il peut traiter des chaînes d’entrée et retourner des instances d’objet.With this attribute applied, when a XAMLprocessor handles values of that property, it can process input strings and return object instances. La technique de conversion de type de chaque propriété est particulièrement utile si vous choisissez d’utiliser un type de propriété à partir de Microsoft .NET Framework ou d’une autre bibliothèque où vous ne pouvez pas contrôler la définition de classe et que vous ne pouvez pas appliquer un TypeConverterAttribute il.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 cannot apply a TypeConverterAttribute there.

Voir aussiSee also