Vue d'ensemble des convertisseurs de types pour XAML

Article
08/10/2011

Les convertisseurs de types fournissent la logique nécessaire pour assister un writer d'objet qui convertit une chaîne de balisage XAML en objets particuliers d'un graphique d'objet. Dans les services XAML .NET Framework, le convertisseur de type doit être une classe dérivée 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 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.

Cette rubrique comprend les sections suivantes.

Concepts de conversion de types
Implémentation d'un convertisseur de type
Application de TypeConverterAttribute
Accès au contexte du fournisseur de services à partir d'une implémentation de l'extension du balisage
Convertisseurs de types dans le flux de nœud XAML
Rubriques connexes

Concepts de conversion de types

Les sections suivantes expliquent quelques concepts de base relatifs à la façon dont XAML utilise les chaînes et dont les writers d'objet des services XAML .NET Framework emploient les convertisseurs de types pour traiter certaines 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 généralement une chaîne et une valeur d'attribut de chaîne comme dans XML. Même les autres primitives telles que Double sont initialement des chaînes pour un processeur XAML.

Dans la plupart des cas, un processeur XAML a besoin de deux types d'informations pour traiter une valeur d'attribut. Le premier élément d'information est le type valeur de la propriété à définir. N'importe quelle chaîne qui définit une valeur d'attribut et qui est traitée en XAML doit être convertie ou résolue en une valeur de ce 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. Si la valeur de l'attribut référence une énumération, la chaîne fournie est utilisée pour rechercher une correspondance de nom avec une constante nommée dans cette énumération. Si la valeur n'est ni une primitive compréhensible par l'analyseur, ni un nom de constante d'une énumération, le type applicable doit pouvoir 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 convertisseur de type.

Convertisseurs de types et extensions de balisage

Les utilisations d'extension de balisage doivent être gérées par un processeur XAML avant qu'il ne recherche le type de propriété et d'autres considérations. Par exemple, si une propriété qui est généralement définie comme un attribut a 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ù il est nécessaire d'utiliser une extension de balisage est la création d'une référence à un objet existant. Pour ce scénario, un convertisseur de type sans état peut uniquement générer une nouvelle instance, ce qui n'est peut-être pas souhaitable. Pour plus d'informations sur les extensions de balisage, consultez Vue d'ensemble des extensions de balisage pour XAML.

Convertisseurs de types natifs

Dans les implémentations de WPF et des services XAML .NET Framework, certains types du Common Language Runtime (CLR) prennent en charge la conversion de type native ; cependant ce ne sont pas des types qui peuvent être considérés comme des primitives. Un exemple d'un tel type est DateTime. La raison de ceci est basée sur le fonctionnement de l'architecture .NET Framework : le type DateTime est défini dans mscorlib, la bibliothèque de base du .NET. DateTime ne peut pas être attribué avec un attribut qui provient d'un autre assembly et qui présente une dépendance (TypeConverterAttribute est de Système), c'est pourquoi le mécanisme de découverte du convertisseur de type habituel par attribution ne peut pas être pris en charge. À 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. Dans le cas de DateTime, ce traitement implique un appel à Parse.

Implémentation d'un convertisseur de type

Les sections suivantes traitent de l'API de la classe TypeConverter.

TypeConverter

En matière de services XAML .NET Framework, tous les convertisseurs de types utilisés pour XAML sont des classes qui dérivent de la classe de base TypeConverter. La classe TypeConverter existait dans les versions du .NET Framework antérieures à l'introduction de XAML ; l'un des scénarios TypeConverter d'origine consistait à fournir un mécanisme de conversion de chaînes pour les boîtes de dialogue des éditeurs de propriétés dans les concepteurs visuels.

Pour XAML, le rôle de TypeConverter a été étendu. Aux fins du langage XAML, TypeConverter est la classe de base permettant la prise en charge de certaines conversions en chaînes et à partir de chaînes. Les conversions de chaînes permettent d'analyser une valeur d'attribut de chaîne à partir du code XAML. Les conversions en chaînes permettent de reconvertir une valeur d'exécution d'une propriété d'objet particulière en attribut 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 vers le type d'objet requis. La méthode ConvertFrom peut être implémentée pour convertir une plage plus large de types vers le type de destination prévu pour le convertisseur. Par conséquent, elle peut remplir des fonctions qui dépassent le cadre du langage XAML, telles que la prise en charge des conversions au moment de l'exécution. Toutefois, pour l'utilisation de XAML, seul le chemin de code capable de traiter une entrée String est important.

La seconde méthode la plus importante est ConvertTo. Si une application est convertie en représentation de balisage (si elle est enregistrée dans XAML en tant que fichier, par exemple)ConvertTo est impliqué dans le scénario plus complet de writers de texte XAML produisant une représentation de balisage. Dans ce cas, le chemin de code principal pour XAML est lorsque l'appelant passe un destinationType de String.

CanConvertTo et CanConvertFrom sont des méthodes de support utilisées lorsqu'un service interroge les fonctions de l'implémentation TypeConverter. Vous devez implémenter ces méthodes pour retourner true pour des cas spécifiques de type pris en charge par les méthodes de conversion correspondantes de votre convertisseur. Pour XAML, cela correspond au type String.

Informations de culture et convertisseurs de types pour XAML

Chaque implémentation de TypeConverter peut interpréter de façon unique ce qui constitue une chaîne valide dans le cadre d'une conversion ; elle peut également utiliser ou ignorer la description de type passée en tant que paramètres. Considération importante relative à la culture et à la conversion de type XAML : bien que l'utilisation de chaînes localisables en tant que valeurs d'attribut soit prise en charge par XAML, vous ne pouvez pas employer ces chaînes localisables comme entrée de convertisseur de type avec des spécifications de culture particulières. Cette restriction est due au fait que les convertisseurs de types des valeurs d'attribut XAML impliquent un comportement de traitement XAML de langage fixe qui utilise la culture en-US. Pour plus d'informations sur les raisons de conception associées à cette restriction, consultez la spécification de 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 sous forme de chaîne, ce qui peut poser un problème. Cette utilisation crée un conflit avec le comportement de nombreux convertisseurs de types existants, 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 le code XAML, la méthode ConvertFrom du convertisseur doit accepter une chaîne comme paramètre value. Si la chaîne a un format valide et peut être convertie par l'implémentation de TypeConverter, l'objet retourné doit alors pouvoir prendre en charge un cast vers le type prévu par la propriété. Sinon, l'implémentation ConvertFrom doit retourner null.

Chaque implémentation de TypeConverter peut interpréter de façon unique ce qui constitue une chaîne dans le cadre d'une conversion ; elle peut également utiliser ou ignorer la description de type ou les contextes de culture passés en tant que paramètres. Cependant, le traitement XAML WPF ne passe pas nécessairement de valeurs au contexte de description de type dans tous les cas, ni de culture en fonction de xml:lang.

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

Il convient de lever une exception si votre convertisseur de type doit accéder à un service XAML du writer d'objet de services XAML .NET Framework, mais que l'appel GetService passé par rapport au contexte ne retourne pas ce service.

Implémentation de ConvertTo

ConvertTo peut être utilisé pour assurer 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 la classe, vous devez implémenter ConvertTo.

Pour être utilisable en tant qu'implémentation de TypeConverter qui prend en charge XAML, la méthode ConvertTo de 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 pouvoir être casté en String. La chaîne retournée doit représenter une valeur sérialisée de value. Idéalement, le format de sérialisation que vous choisissez doit pouvoir générer la même valeur que si cette chaîne était passée à l'implémentation de ConvertFrom du même convertisseur, sans perte significative d'informations.

Si la valeur ne peut pas être sérialisée ou que le convertisseur ne prend pas en charge la sérialisation, l'implémentation de ConvertTo doit retourner la valeur null et peut lever une exception dans ce cas. 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 de convertisseur. En général, vous rétablirez le traitement de l'implémentation de base, qui avec ConvertTo lève une exception spécifique.

Implémentation de CanConvertFrom

L'implémentation 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 CanConvertTo doit retourner la valeur true pour destinationType de type String ou déférer à l'implémentation de base. Ne levez pas d'exceptions à partir de la méthode CanConvertTo.

Application de TypeConverterAttribute

Pour que le convertisseur de type personnalisé soit utilisé pour une classe personnalisée par le biais du traitement des services XAML .NET Framework, vous devez appliquer .NET Framework attributeTypeConverterAttribute à la définition de classe. Le ConverterTypeName que vous spécifiez à travers l'attribut doit être le nom de type du convertisseur de type personnalisé. Si vous appliquez cet attribut, lorsqu'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.

Vous pouvez également fournir un convertisseur de type en fonction de la propriété. Au lieu d'appliquer un .NET Framework attributeTypeConverterAttribute à 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). Le type de la propriété doit correspondre au type traité par le convertisseur de type personnalisé. Avec cet attribut appliqué, lorsqu'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. La technique de conversion en fonction de la propriété est particulièrement utile si vous choisissez d'utiliser un type de propriété 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 appliquer un TypeConverterAttribute à cet endroit.

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

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

Les services disponibles sont les mêmes pour tous les convertisseurs de valeurs. La seule différence réside dans le mode de réception du contexte de service par chaque convertisseur de valeurs. L'accès aux services et les services disponibles sont documentés dans la rubrique Convertisseurs de types et extensions de balisage pour XAML.

Convertisseurs de types dans le flux de nœud XAML

Si vous utilisez un flux de nœud XAML, l'action d'un convertisseur de type n'est pas encore exécutée ou n'a pas encore produit de résultat final. Dans un chemin de chargement, la chaîne d'attribut dont le type doit finalement être converti pour qu'elle puisse être chargée demeure sous la forme d'une valeur de texte dans un membre de début et un membre de fin. Le convertisseur de type qui est finalement requis 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 la disponibilité d'un contexte de schéma XAML permettant d'accéder à ces informations via le membre sous-jacent ou le type de la valeur d'objet que le membre utilise. L'appel réel du comportement de conversion de type requiert également le contexte de schéma XAML car cette opération nécessite un mappage de type et la création d'une instance de convertisseur.

Voir aussi

Partager via