Vue d’ensemble des convertisseurs de types pour XAML

Article
01/30/2025

Les convertisseurs de types fournissent une logique pour un enregistreur d’objets qui convertit d’une chaîne dans le balisage XAML en objets particuliers dans un graphique d’objets. Dans les services XAML .NET, le convertisseur de types doit être une classe qui dérive de TypeConverter. Certains convertisseurs prennent également en charge le chemin d’enregistrement XAML et peuvent être utilisés pour sérialiser un objet sous forme de chaîne dans le format de balisage de sérialisation. Cette rubrique décrit comment et quand les convertisseurs de type en XAML sont appelés, et fournit des conseils d'implémentation pour les substitutions de méthode de TypeConverter.

Concepts de conversion de type

Les sections suivantes expliquent les concepts de base sur la façon dont XAML utilise des chaînes et comment les enregistreurs d’objets dans les services XAML .NET utilisent des convertisseurs de types pour traiter certaines des valeurs de chaîne rencontrées dans une source XAML.

XAML et valeurs de chaîne

Lorsque vous définissez une valeur d’attribut dans un fichier XAML, le type initial de cette valeur est une chaîne dans un sens général et une valeur d’attribut de chaîne dans un sens XML. Même d’autres primitives telles que Double sont initialement des chaînes à un processeur XAML.

Dans la plupart des cas, un processeur XAML a besoin de deux informations pour traiter une valeur d’attribut. La première information est le type de valeur de la propriété qui est définie. Toute chaîne qui définit une valeur d’attribut et qui est traitée en XAML doit finalement être convertie ou résolue en valeur de ce type. Si la valeur est une primitive comprise par l’analyseur XAML (par exemple, une valeur numérique), une conversion directe de la chaîne est tentée. Si la valeur de l’attribut fait référence à une énumération, la chaîne fournie est vérifiée pour qu’un nom corresponde à une constante nommée dans cette énumération. Si la valeur n’est pas une primitive comprise par l’analyseur ou un nom constant d’une énumération, le type applicable doit être en mesure de fournir une valeur ou une référence basée sur une chaîne convertie.

Remarque

Les directives de langage XAML n’utilisent pas de convertisseurs de type.

Convertisseurs de types et extensions de balisage

Les utilisations de l’extension de balisage doivent être gérées par un processeur XAML avant de vérifier le type de propriété et d’autres considérations. Par exemple, si une propriété définie en tant qu'attribut a généralement une conversion de type, mais que dans un cas particulier, elle est définie par une utilisation d'extension de balisage, le comportement d'extension de balisage est traité en premier. Une situation courante où une extension de balisage est nécessaire consiste à faire référence à un objet qui existe déjà. Pour ce scénario, un convertisseur de type sans état ne peut générer qu’une nouvelle instance, ce qui peut ne pas être souhaitable. Pour plus d’informations sur les extensions de balisage, consultez Vue d’ensemble des extensions de balisage pour XAML.

Convertisseurs de type natif

Dans les implémentations des services XAML Windows Presentation Foundation (WPF) et .NET, certains types CLR ont une gestion de conversion de type native. Toutefois, ces types CLR ne sont pas considérés de manière conventionnelle comme des primitives. Un exemple de ce type est DateTime. Une raison en est que l'architecture du .NET Framework fonctionne ainsi : le type DateTime est défini dans mscorlib, la bibliothèque la plus fondamentale de .NET. DateTime n’est pas autorisé à être attribué avec un attribut provenant d’un autre assembly qui introduit une dépendance (TypeConverterAttribute provient du système). Par conséquent, le mécanisme habituel de découverte des convertisseurs de type par attribution ne peut pas être pris en charge. Au lieu de cela, l’analyseur XAML a une liste de types qui nécessitent un traitement natif, et il traite ces types comme la façon dont les vraies primitives sont traitées. Dans le cas de DateTime, ce traitement implique un appel à Parse.

Implémentation d’un convertisseur de type

Les sections suivantes décrivent l’API de la classe TypeConverter.

TypeConverter

Sous Services XAML .NET, tous les convertisseurs de type utilisés à des fins XAML sont des classes qui dérivent de la classe de base TypeConverter. La classe TypeConverter existait dans les versions du .NET Framework avant que XAML n’existait ; l’un des scénarios d’origine TypeConverter était de fournir une conversion de chaîne pour les éditeurs de propriétés dans les concepteurs visuels.

Pour XAML, le rôle de TypeConverter est développé. À des fins XAML, TypeConverter est la classe de base pour fournir le support de certaines conversions de et vers des chaînes. La fonctionnalité "from-string" permet d'analyser une valeur d'attribut de chaîne à partir de XAML. Les conversions en chaînes permettent de reconvertir une valeur d'exécution d'une propriété d'objet particulière en attribut en XAML pour la sérialisation.

TypeConverter définit quatre membres qui sont utiles pour la conversion en chaînes et à partir de chaînes à des fins de traitement XAML :

Parmi ces membres, la méthode la plus importante est ConvertFrom, qui convertit la chaîne d’entrée en type d’objet requis. La méthode ConvertFrom peut être implémentée pour convertir un large éventail de types en type de destination prévu du convertisseur. Par conséquent, il peut servir à des fins qui s’étendent au-delà de XAML, telles que la prise en charge des conversions au moment de l’exécution. Toutefois, pour une utilisation XAML, seul le chemin du code qui peut traiter une entrée String est important.

La deuxième méthode la plus importante est ConvertTo. Si une application est convertie en représentation de balisage (par exemple, si elle est enregistrée en XAML en tant que fichier), ConvertTo est impliquée dans le scénario plus large d’un enregistreur de texte XAML pour produire une représentation de balisage. Dans ce cas, le chemin de code important pour XAML est lorsque l'appelant passe un destinationType de String.

CanConvertTo et CanConvertFrom sont des méthodes de prise en charge utilisées lorsqu’un service interroge les fonctionnalités de l’implémentation TypeConverter. Vous devez implémenter ces méthodes pour retourner true pour les cas spécifiques au type pris en charge par les méthodes de conversion équivalentes de votre convertisseur. À des fins XAML, cela signifie généralement le type String.

Informations culturelles et convertisseurs de type pour XAML

Chaque implémentation de TypeConverter peut interpréter de manière unique ce qui est une chaîne valide pour une conversion, et elle peut également utiliser ou ignorer la description de type passée en tant que paramètres. Une considération importante pour la conversion de type CULTURE et XAML est la suivante : bien que l’utilisation de chaînes localisables comme valeurs d’attribut soit prise en charge par XAML, vous ne pouvez pas utiliser ces chaînes localisables comme entrée de convertisseur de type avec des exigences de culture spécifiques. Cette limitation est due au fait que les convertisseurs de type pour les valeurs d’attribut XAML impliquent un comportement de traitement XAML avec une langue fixe qui utilise la culture en-US. Pour plus d’informations sur les raisons de conception de cette restriction, consultez la spécification du langage XAML ([MS-XAML]) ou vue d’ensemble de la globalisation et de la localisation WPF.

Par exemple, certaines cultures utilisent une virgule au lieu d'un point comme séparateur décimal pour les nombres en notation chiffrée. Cette utilisation entre en collision avec le comportement que de nombreux convertisseurs de types existants ont, qui consiste à utiliser une virgule comme délimiteur. Le passage d'une culture via xml:lang dans le code XAML environnant ne résout pas le problème.

Implémentation de ConvertFrom

Pour être utilisable en tant qu’implémentation TypeConverter qui prend en charge XAML, la méthode ConvertFrom pour ce convertisseur doit accepter une chaîne comme paramètre value. Si la chaîne est dans un format valide et peut être convertie par l’implémentation TypeConverter, l’objet retourné doit supporter une conversion vers le type attendu par la propriété. Sinon, l’implémentation ConvertFrom doit retourner null.

Chaque implémentation de TypeConverter peut interpréter de manière unique ce qui constitue une chaîne valide pour une conversion, et peut également utiliser ou ignorer la description de type ou les contextes de culture qui sont passés en tant que paramètres. Cependant, le traitement XAML WPF ne passe pas nécessairement des valeurs au contexte de description de type dans tous les cas, ni de culture en fonction de xml:lang.

Remarque

N’utilisez pas les accolades ({}), en particulier l’accolade ouvrante ({), en tant qu’élément de votre format de chaîne de caractères. Ces caractères sont réservés comme entrée et sortie pour une séquence d’extension de balisage.

Il est approprié de lever une exception lorsque votre convertisseur de types doit avoir accès à un service XAML à partir de l’enregistreur d’objets des services XAML .NET, mais que l’appel GetService effectué par rapport au contexte ne retourne pas ce service.

Implémentation de ConvertTo

ConvertTo est potentiellement utilisé pour la prise en charge de la sérialisation. 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. 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 votre classe, vous devez implémenter ConvertTo.

Pour être utilisable en tant qu’implémentation TypeConverter prenant en charge XAML, la méthode ConvertTo pour ce convertisseur doit accepter une instance du type (ou une valeur) prise en charge comme paramètre value. Lorsque le paramètre destinationType est de type String, l’objet retourné doit être converti en tant que String. La chaîne retournée doit représenter une valeur sérialisée de value. Dans l’idéal, le format de sérialisation que vous choisissez doit être en mesure de générer la même valeur que si cette chaîne a été passée à l’implémentation ConvertFrom du même convertisseur, sans perte significative d’informations.

Si la valeur ne peut pas être sérialisée ou si le convertisseur ne prend pas en charge la sérialisation, l’implémentation ConvertTo doit retourner null et peut lever une exception. Toutefois, si vous levez des exceptions, vous devez signaler que cette conversion ne peut pas être utilisée dans le cadre de votre implémentation de CanConvertTo afin que la meilleure pratique qui consiste à effectuer d'abord une vérification avec CanConvertTo pour éviter les exceptions soit prise en charge.

Si le paramètre destinationType n’est pas de type String, vous pouvez choisir votre propre gestion du convertisseur. En général, vous rétablissez le traitement de l'implémentation de base, ce qui, dans la méthode ConvertTo de base, lève une exception spécifique.

Implémentation de 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. Ne levez pas d'exceptions à partir de la méthode CanConvertFrom.

Implémentation de 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. Ne levez pas d'exceptions à partir de la méthode CanConvertTo.

Application de l'attribut TypeConverterAttribute

Pour que votre convertisseur de type personnalisé soit utilisé comme convertisseur de type agissant pour une classe personnalisée par les services XAML .NET, vous devez appliquer la TypeConverterAttribute à votre définition de classe. La ConverterTypeName que vous spécifiez via l’attribut doit être le nom de type de votre convertisseur de type personnalisé. Si vous appliquez cet attribut, lorsqu’un processeur XAML gère les valeurs où le type de propriété utilise votre type de classe personnalisé, il peut entrer des chaînes et retourner des instances d’objet.

Vous pouvez également fournir un convertisseur de type en fonction de la propriété. Au lieu d’appliquer une TypeConverterAttribute à la définition de classe, appliquez-la à une définition de propriété (la définition principale, et non les implémentations get/set dans celle-ci). Le type de la propriété doit correspondre au type traité par votre convertisseur de type personnalisé. Avec cet attribut appliqué, lorsqu’un processeur XAML gère les valeurs de cette propriété, il peut traiter les chaînes d’entrée et retourner des instances d’objet. La technique de convertisseur de type par propriété est 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 ne pouvez pas y appliquer un TypeConverterAttribute.

Pour fournir un comportement de conversion de type pour un membre attaché personnalisé, appliquez TypeConverterAttribute à la méthode d’accesseur Get du modèle d’implémentation du membre attaché.

Accès au contexte du fournisseur de services à partir d’une implémentation d’extension de balisage

Les services disponibles sont identiques pour n’importe quel convertisseur de valeur. La différence réside dans la façon dont chaque convertisseur de valeurs reçoit le contexte de service. L'accès aux services et des services disponibles est documenté dans la rubrique Convertisseurs de types et extensions de balisage pour XAML.

Convertisseurs de type et flux de nœud XAML

Si vous utilisez un flux de nœud XAML, l’action ou le résultat final d’un convertisseur de type n’est pas encore exécuté. Dans un chemin de chargement, la chaîne d’attribut qui doit éventuellement être convertie en type afin de charger reste en tant que valeur de texte au sein d’un membre de début et d’un membre final. Le convertisseur de type qui est finalement nécessaire pour cette opération peut être déterminé à l’aide de la propriété XamlMember.TypeConverter. Toutefois, l’obtention d’une valeur valide à partir de XamlMember.TypeConverter repose sur l’utilisation d’un contexte de schéma XAML, qui peut accéder à ces informations via le membre sous-jacent ou le type de la valeur d’objet utilisée par le membre. L’appel du comportement de conversion de type nécessite également le contexte de schéma XAML, car cela nécessite un mappage de type et la création d’une instance de convertisseur.

Partager via