TypeConverter e XAMLTypeConverters and XAML

Questo argomento illustra lo scopo della conversione del tipo string come funzionalità generale del linguaggio XAML.This topic introduces the purpose of type conversion from string as a general XAML language feature. In .NET Framework, il TypeConverter classe funge da parte dell'implementazione per una classe personalizzata gestita che può essere utilizzata come valore della proprietà di attributo XAML uno scopo specifico.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. Se si scrive una classe personalizzata e si desidera che le istanze della classe per essere utilizzabile come valori di attributo impostabile XAML, si potrebbe essere necessario applicare un TypeConverterAttribute alla classe, scrivere un oggetto personalizzato TypeConverter classe, o entrambi.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.

Concetti relativi alla conversione di tipiType Conversion Concepts

Valori XAML e stringaXAML and String Values

Quando si imposta un valore di attributo in un file XAML, il tipo iniziale di tale valore è una stringa di solo testo.When you set an attribute value in a XAML file, the initial type of that value is a string in pure text. Anche altre primitive, ad esempio Double sono inizialmente stringhe di testo per un processore XAML.Even other primitives such as Double are initially text strings to a XAML processor.

Un processore XAML necessita di due informazioni per elaborare un valore di attributo.A XAML processor needs two pieces of information in order to process an attribute value. La prima informazione è il tipo di valore della proprietà che si imposta.The first piece of information is the value type of the property that is being set. Qualsiasi stringa che definisce un valore di attributo e che viene elaborata in XAML deve essere convertita o risolta in un valore di quel tipo.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. Se il valore è una primitiva riconosciuta dal parser XAML (ad esempio un valore numerico), viene tentata una conversione diretta della stringa.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. Se il valore è un'enumerazione, la stringa viene usata per controllare la corrispondenza di un nome con una costante denominata in tale enumerazione.If the value is an enumeration, the string is used to check for a name match to a named constant in that enumeration. Se il valore non è né una primitiva riconosciuta dal parser né un'enumerazione, il tipo in questione deve essere in grado di fornire un'istanza del tipo o un valore basato su una stringa convertita.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. Ciò è possibile indicando una classe di convertitore di tipi.This is done by indicating a type converter class. Il convertitore di tipi è una classe helper che fornisce valori di un'altra classe, sia per gli scenari XAML che, potenzialmente, per le chiamate nel codice .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.

Uso del comportamento di conversione dei tipi esistente in XAMLUsing Existing Type Conversion Behavior in XAML

A seconda del livello di conoscenza dei concetti XAML sottostanti, è possibile che si usi già il comportamento di conversione dei tipi nel codice XAML dell'applicazione di base senza rendersene conto.Depending on your familiarity with the underlying XAML concepts, you may already be using type conversion behavior in basic application XAML without realizing it. Ad esempio, in cui WPF definisce centinaia di proprietà che accettano un valore di tipo Point.For instance, WPF defines literally hundreds of properties that take a value of type Point. Oggetto Point è un valore che descrive una coordinata in uno spazio di coordinate bidimensionale, e ha in effetti solo due proprietà importanti: X e 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. Quando si specifica un punto in XAML, viene specificato come stringa con un delimitatore (in genere una virgola) tra il X e Y valori forniti.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. Ad esempio: <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">.For example: <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">.

Anche questo tipo semplice di Point e il relativo utilizzo semplice in XAML implicano un convertitore di tipi.Even this simple type of Point and its simple usage in XAML involve a type converter. In questo caso che è la classe PointConverter.In this case that is the class PointConverter.

Il convertitore di tipi per Point definiti a livello di classe semplifica gli utilizzi di markup di tutte le proprietà che accettano Point.The type converter for Point defined at the class level streamlines the markup usages of all properties that take Point. Senza un convertitore di tipi, per l'esempio illustrato in precedenza sarebbe necessario ricorrere al seguente markup molto più dettagliato: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>

La scelta tra l'uso di una stringa di conversione del tipo o di una sintassi equivalente più dettagliata è, in genere, una questione di stile di codifica.Whether to use the type conversion string or a more verbose equivalent syntax is generally a coding style choice. Anche il flusso di lavoro degli strumenti XAML può influire sul modo in cui vengono impostati i valori.Your XAML tooling workflow might also influence how values are set. Alcuni strumenti XAML tendono a generare la forma più dettagliata del markup perché è più facile eseguire il round trip nelle visualizzazioni delle finestre di progettazione o nel meccanismo di serializzazione.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.

Convertitori di tipi esistenti possono essere individuati in genere nei tipi WPF e .NET Framework mediante il controllo di una classe o proprietà, la presenza di un applicato 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. Questo attributo assegnerà un nome alla classe che costituisce il convertitore di tipi di supporto per i valori del tipo in questione, sia per gli scenari XAML sia, eventualmente, per altri scopi.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.

Convertitori di tipi ed estensioni di markupType Converters and Markup Extensions

Le estensioni di markup e i convertitori di tipi rivestono ruoli ortogonali in termini di comportamento del processore XAML e di scenari ai cui sono applicati.Markup extensions and type converters fill orthogonal roles in terms of XAML processor behavior and the scenarios that they are applied to. Anche se il contesto è disponibile per gli utilizzi di estensione di markup, il comportamento della conversione di tipi di proprietà in cui un'estensione di markup fornisce un valore in genere non è selezionato nelle implementazioni dell'estensione di markup.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. In altre parole, anche se un'estensione di markup restituisce una stringa di testo come output di ProvideValue, il comportamento di conversione dei tipi su tale stringa così come applicato a una proprietà o a un tipo di valore della proprietà specifico non viene richiamato. In genere, lo scopo di un'estensione di markup è quello di elaborare una stringa e restituire un oggetto senza coinvolgere alcun convertitore di tipi.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.

Una situazione comune che richiede un'estensione di markup invece che un convertitore di tipi è il riferimento a un oggetto già esistente.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. Nella migliore delle ipotesi, un convertitore di tipi senza stato può solo generare una nuova istanza, che potrebbe non essere il comportamento ottimale.At best, a stateless type converter could only generate a new instance, which might not be desirable. Per altre informazioni sulle estensioni di markup, vedere Estensioni di markup e XAML WPF.For more information on markup extensions, see Markup Extensions and WPF XAML.

Convertitori di tipi nativiNative Type Converters

Nell'implementazione WPF e .NET Framework del parser XAML ci sono determinati tipi che prevedono la gestione nativa della conversione del tipo, anche se non si tratta di tipi convenzionalmente considerati primitive.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 esempio dei tipi in questione è DateTime.An example of such a type is DateTime. Il motivo è basato sul funzionamento dell'architettura di .NET Framework: il tipo DateTime è definito in mscorlib, la libreria più elementare di .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 non è autorizzato ad essere attribuito un attributo fornito da un altro assembly che introduce una dipendenza (TypeConverterAttribute è dal sistema) il consueto meccanismo di individuazione convertitore di tipi mediante assegnazione di attributi non può essere supportato.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. Il parser XAML ha invece di un elenco di tipi che necessitano di tale elaborazione nativa ed elabora questi tipi in modo analogo all'elaborazione delle primitive effettive.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. (Nel caso di DateTime ciò comporta una chiamata a Parse.)(In the case of DateTime this involves a call to Parse.)

Implementazione di un convertitore di tipiImplementing a Type Converter

TypeConverterTypeConverter

Nel Point esempio riportato in precedenza, la classe PointConverter indicato.In the Point example given previously, the class PointConverter was mentioned. Per le implementazioni .NET di XAML, tutti i convertitori di tipi che sono usati per XAML sono classi che derivano dalla classe di 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. La TypeConverter classe disponibili nelle versioni di .NET Framework precedenti all'introduzione di XAML; uno dei relativi utilizzi originali consisteva nel fornire la conversione delle stringhe per le finestre di dialogo proprietà nelle finestre di progettazione.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. Per XAML, il ruolo di TypeConverter viene espansa per includere la classe base per le conversioni da e dalla stringa che consentono l'analisi di un valore di attributo di stringa, nonché l'eventuale valore in fase di esecuzione di una particolare proprietà dell'oggetto in una stringa per essere serializzazione come attributo.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 definisce quattro membri rilevanti per la conversione da e verso le stringhe per ragioni di elaborazione XAML:TypeConverter defines four members that are relevant for converting to and from strings for XAML processing purposes:

Tra questi, il metodo più importante è ConvertFrom.Of these, the most important method is ConvertFrom. Questo metodo converte la stringa di input nel tipo di oggetto richiesto.This method converts the input string to the required object type. In teoria, il ConvertFrom metodo potrebbe essere implementato per convertire una più vasta gamma di tipi nel tipo di destinazione previsto dal convertitore e pertanto scopi che si estendono oltre XAML, ad esempio il supporto delle conversioni in fase di esecuzione, ma per XAML è solo il percorso del codice in grado di elaborare un String input a cui si è interessati.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.

Il metodo più importante successivo è ConvertTo.The next most important method is ConvertTo. Se un'applicazione viene convertita in una rappresentazione del markup (ad esempio, se viene salvata in XAML come file), ConvertTo è responsabile della creazione di una rappresentazione del markup.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. In questo caso, il percorso del codice che è importante per XAML è quando si passa un destinationType di String .In this case, the code path that matters for XAML is when you pass a destinationType of String .

CanConvertTo e CanConvertFrom sono metodi di supporto usati quando un servizio esegue una query sulle funzionalità dell'implementazione di TypeConverter .CanConvertTo and CanConvertFrom are support methods that are used when a service queries the capabilities of the TypeConverter implementation. È necessario implementare questi metodi per restituire true per i casi specifici del tipo supportati dai metodi di conversione equivalenti del convertitore.You must implement these methods to return true for type-specific cases that the equivalent conversion methods of your converter support. Per XAML, si tratta in genere del tipo String .For XAML purposes, this generally means the String type.

Informazioni relative alle impostazioni cultura e convertitori di tipi per XAMLCulture Information and Type Converters for XAML

Ogni TypeConverter implementazione può avere un'interpretazione di ciò che costituisce una stringa valida per una conversione e può anche usare o ignorare la descrizione del tipo passata come parametri.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. C'è un'importante considerazione per quanto riguarda le impostazioni cultura e la conversione di tipi in XAML.There is an important consideration with regard to culture and XAML type conversion. L'uso di stringhe localizzabili come valori di attributo è completamente supportato in XAML.Using localizable strings as attribute values is entirely supported by XAML. L'uso di una stringa localizzabile come input del convertitore di tipi con requisiti di impostazioni cultura specifici non è però supportato, perché i convertitori di tipi per i valori di attributi XAML implicano un comportamento di analisi basato su un'unica lingua e sulle impostazioni cultura 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. Per altre informazioni sui motivi legati alla progettazione alla base di questa limitazione, vedere la specifica del linguaggio XAML ([MS-XAML]).For more information on the design reasons for this restriction, you should consult the XAML language specification ([MS-XAML]).

Un caso in cui le impostazioni cultura possono rappresentare un problema è ad esempio l'uso, in alcune impostazioni cultura, della virgola come separatore decimale per i numeri.As an example where culture can be an issue, some cultures use a comma as their decimal point delimiter for numbers. Tale caratteristica è in conflitto con il comportamento di molti convertitori di tipi XAML di WPF, che usano la virgola come delimitatore (in base a precedenti storici come il formato X,Y comune o gli elenchi delimitati da virgole).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). Nemmeno il passaggio di impostazioni cultura nel codice XAML adiacente (impostando ad esempio Language o xml:lang sulle impostazioni cultura sl-SI che prevedono l'uso della virgola come separatore decimale) può consentire di risolvere il problema.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.

Implementazione di ConvertFromImplementing ConvertFrom

Per essere utilizzabile come implementazione di TypeConverter che supporti XAML, il metodo ConvertFrom per il convertitore deve accettare una stringa come parametro 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. Se la stringa non valido, formattare e possono essere convertiti dal TypeConverter implementazione, quindi l'oggetto restituito deve supportare un cast nel tipo previsto dalla proprietà.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. In caso contrario, l'implementazione ConvertFrom deve restituire null.Otherwise, the ConvertFrom implementation must return null.

Ogni TypeConverter implementazione può avere un'interpretazione di ciò che costituisce una stringa valida per una conversione e può anche usare o ignorare i contesti di tipo descrizione o delle impostazioni cultura passati come parametri.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. L'elaborazione della sintassi XAML di WPF potrebbe tuttavia non passare i valori al contesto della descrizione del tipo in tutti i casi e potrebbe non passare nemmeno le impostazioni cultura basate su 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.

Nota

Non usare i caratteri parentesi graffa, in particolare {, come elemento del formato stringa.Do not use the curly brace characters, particularly {, as a possible element of your string format. Questi caratteri vengono usati esclusivamente come punti di ingresso e di uscita di una sequenza di estensione del markup.These characters are reserved as the entry and exit for a markup extension sequence.

Implementazione di ConvertToImplementing ConvertTo

ConvertTo viene potenzialmente usato per il supporto della serializzazione.ConvertTo is potentially used for serialization support. Il supporto della serializzazione tramite ConvertTo per il tipo personalizzato e il relativo convertitore di tipi non è un requisito assoluto.Serialization support through ConvertTo for your custom type and its type converter is not an absolute requirement. Tuttavia, se si implementa un controllo o si usa la serializzazione come parte delle funzionalità o della progettazione della classe, sarà necessario implementare 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.

Per essere utilizzabile come un TypeConverter implementazione che supporti XAML, il ConvertTo metodo per il convertitore deve accettare un'istanza di tipo (o un valore) come il value parametro.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. Quando il destinationType parametro è il tipo String, l'oggetto restituito deve essere in grado di eseguire il cast come String.When the destinationType parameter is the type String, then the returned object must be able to be cast as String. La stringa restituita deve rappresentare un valore serializzato di value.The returned string must represent a serialized value of value. In teoria, il formato di serializzazione scelto deve essere in grado di generare lo stesso valore se quella stringa venisse passata per il ConvertFrom implementazione dello stesso convertitore, senza perdite significative di informazioni.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.

Se il valore non può essere serializzato o il convertitore non supporta la serializzazione, la ConvertTo deve restituire l'implementazione nulle la possibilità di generare un'eccezione in questo caso.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. Tuttavia se si generano eccezioni, sarà necessario segnalare l'impossibilità di usare tale conversione come parte del CanConvertTo implementazione in modo che la procedura consigliata di un controllo con CanConvertTo innanzitutto per evitare eccezioni è supportata.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.

Se destinationType parametro non è di tipo String, è possibile scegliere la gestione del convertitore.If destinationType parameter is not of type String, you can choose your own converter handling. In genere, viene ripristinata per la gestione, che nella forma più elementare dell'implementazione base ConvertTo genera un'eccezione specifica.Typically, you would revert to base implementation handling, which in the basemost ConvertTo raises a specific exception.

Implementazione di CanConvertToImplementing CanConvertTo

L'implementazione di CanConvertTo deve restituire true per un oggetto destinationType di tipo String; in caso contrario, deve rinviare all'implementazione di base.Your CanConvertTo implementation should return true for destinationType of type String, and otherwise defer to the base implementation.

Implementazione di CanConvertFromImplementing CanConvertFrom

L'implementazione di CanConvertFrom deve restituire true per un oggetto sourceType di tipo String; in caso contrario, deve rinviare all'implementazione di base.Your CanConvertFrom implementation should return true for sourceType of type String, and otherwise defer to the base implementation.

Applicazione di TypeConverterAttributeApplying the TypeConverterAttribute

Affinché il convertitore di tipi personalizzato da utilizzare come convertitore di tipi per una classe personalizzata da un processore XAML, è necessario applicare il attributo .NET Framework.NET Framework attribute TypeConverterAttribute alla definizione della 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 attributo .NET Framework.NET Framework attribute TypeConverterAttribute to your class definition. L'oggetto ConverterTypeName specificato tramite l'attributo deve corrispondere al nome di tipo del convertitore dei tipi personalizzato.The ConverterTypeName that you specify through the attribute must be the type name of your custom type converter. Se si applica questo attributo, quando un processore XAML gestisce valori per i quali il tipo di proprietà usa il tipo di classe personalizzato, può usare stringhe di input e restituire istanze di oggetti.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.

Si può anche fornire un convertitore dei tipi per le singole proprietà.You can also provide a type converter on a per-property basis. Anziché applicare un attributo .NET Framework.NET Framework attribute TypeConverterAttribute alla definizione della classe, applicarlo a una definizione di proprietà (la definizione principale, non il get / set implementazioni all'interno di esso).Instead of applying a attributo .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). Il tipo della proprietà deve corrispondere al tipo elaborato dal convertitore dei tipi personalizzato.The type of the property must match the type that is processed by your custom type converter. Se questo attributo viene applicato, quando un processore XAML gestisce i valori di tale proprietà, può elaborare stringhe di input e restituire istanze di oggetti.With this attribute applied, when a XAMLprocessor handles values of that property, it can process input strings and return object instances. La tecnica del convertitore tipo singole proprietà risulta particolarmente utile se si sceglie di usare un tipo di proprietà da Microsoft .NET Framework o da qualche altra libreria in cui si può controllare la definizione di classe e non è possibile applicare un TypeConverterAttribute non esiste.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.

Vedere ancheSee Also

TypeConverter
Cenni preliminari su XAML (WPF)XAML Overview (WPF)
Estensioni di markup e XAML WPFMarkup Extensions and WPF XAML
Descrizione dettagliata della sintassi XAMLXAML Syntax In Detail