Panoramica dei convertitori di tipi per XAMLType Converters for XAML Overview

I convertitori di tipi forniscono la logica per un writer di oggetti che esegue una conversione da una stringa nel markup XAML in particolari oggetti in un oggetto grafico.Type converters supply logic for an object writer that converts from a string in XAML markup into particular objects in an object graph. Nei servizi XAML di .NET Framework, il convertitore di tipi deve essere una classe che deriva da TypeConverter.In .NET Framework XAML Services, the type converter must be a class that derives from TypeConverter. Alcuni convertitori supportano anche il percorso di salvataggio XAML e possono essere usati per serializzare un oggetto in un formato stringa nel markup di serializzazione.Some converters also support the XAML save path and can be used to serialize an object into a string form in serialization markup. Questo argomento descrive come e quando vengono richiamati i convertitori di tipi in XAML e vengono forniti consigli di implementazione per gli override del metodo di TypeConverter.This topic describes how and when type converters in XAML are invoked, and provides implementation advice for the method overrides of TypeConverter.

Concetti relativi alla conversione di tipiType Conversion Concepts

Le sezioni seguenti illustrano i concetti di base riguardanti il modo in cui XAML usa le stringhe e il modo in cui i writer di oggetti nei servizi XAML di .NET Framework usano i convertitori di tipi per elaborare alcuni dei valori stringa rilevati in un'origine XAML.The following sections explain basic concepts about how XAML uses strings, and how object writers in .NET Framework XAML Services use type converters to process some of the string values that are encountered in a XAML source.

Valori XAML e stringaXAML and String Values

Quando si imposta un valore dell'attributo in un file XAML, il tipo iniziale del valore è una stringa in senso generale e un valore dell'attributo di stringa in XML.When you set an attribute value in a XAML file, the initial type of that value is a string in a general sense, and a string attribute value in an XML sense. Anche altre primitive, ad esempio Double , sono inizialmente stringhe per un processore XAML.Even other primitives such as Double are initially strings to a XAML processor.

Nella maggior parte dei casi, un processore XAML deve disporre di due informazioni per elaborare un valore di attributo.In most cases, a XAML processor needs two pieces of information 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 dell'attributo fa riferimento a un'enumerazione, nella stringa specificata viene verificata la corrispondenza del nome con una costante denominata in tale enumerazione.If the value for the attribute references an enumeration, the supplied string is checked for a name match to a named constant in that enumeration. Se il valore non è né una primitiva riconosciuta dal parser né il nome di una costante di un'enumerazione, il tipo applicabile deve poter fornire un valore o un riferimento basato su una stringa convertita.If the value is neither a parser-understood primitive nor a constant name from an enumeration, the applicable type must be able to provide a value or reference that is based on a converted string.

Nota

Le direttive del linguaggio XAML non usano convertitori di tipi.XAML language directives do not use type converters.

Convertitori di tipi ed estensioni di markupType Converters and Markup Extensions

Gli utilizzi di estensioni di markup devono essere gestiti da un processore XAML prima che questo verifichi il tipo di proprietà e altre considerazioni.Markup extension usages must be handled by a XAML processor before it checks for property type and other considerations. Ad esempio, se una proprietà impostata come attributo viene associata normalmente a una conversione di tipi, ma in un caso particolare viene impostata mediante un utilizzo dell'estensione di markup, viene innanzitutto elaborato il comportamento dell'estensione di markup.For example, if a property being set as an attribute normally has a type conversion, but in a particular case is set by a markup extension usage, then the markup extension behavior processes first. Una situazione comune che richiede un'estensione di markup è la creazione di un riferimento a un oggetto già esistente.One common situation where a markup extension is necessary is to make a reference to an object that already exists. Per questo scenario, un convertitore di tipi senza stato può solo generare una nuova istanza, che non necessariamente è appropriata.For this scenario, a stateless type converter can only generate a new instance, which might not be desirable. Per ulteriori informazioni sulle estensioni di markup, vedere Markup Extensions for XAML Overview.For more information about markup extensions, see Markup Extensions for XAML Overview.

Convertitori di tipi nativiNative Type Converters

Nelle implementazioni dei servizi WPF e XAML di .NET, alcuni tipi CLR che dispongono di gestione della conversione del tipo nativo, tuttavia, i tipi CLR non sono propriamente considerati primitive.In the WPF and .NET XAML services implementations, there are certain CLR types that have native type conversion handling, however, those CLR types are not conventionally thought of as primitives. Un esempio dei tipi in questione è DateTime.An example of such a type is DateTime. Un motivo consiste nel funzionamento dell'architettura di .NET Framework: il tipo DateTime è definito in mscorlib, la libreria più elementare di .NET.One reason for this is how the .NET Framework architecture works: the type DateTime is defined in mscorlib, the most basic library in .NET. Poiché non è consentito assegnare aDateTime un attributo fornito da un altro assembly che introduce una dipendenza (TypeConverterAttribute è fornito da System), il consueto meccanismo di individuazione del 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); therefore, the usual type converter discovery mechanism by attributing cannot be supported. Il parser XAML dispone invece di un elenco di tipi che necessitano di elaborazione nativa ed elabora questi tipi con modalità analoghe all'elaborazione delle primitive effettive.Instead, the XAML parser has a list of types that need native processing, and it processes these types similar to how the true primitives are processed. Nel caso di DateTime, l'elaborazione comporta una chiamata a Parse.In the case of DateTime, this processing involves a call to Parse.

Implementazione di un convertitore di tipiImplementing a Type Converter

Le sezioni seguenti illustrano l'API della classe TypeConverter .The following sections discuss the API of the TypeConverter class.

TypeConverterTypeConverter

Nei servizi XAML di .NET Framework tutti i convertitori di tipi usati per XAML sono classi derivanti dalla classe base TypeConverter.Under .NET Framework XAML Services, all type converters that are used for XAML purposes are classes that derive from the base class TypeConverter. La classe TypeConverter era presente nelle versioni di .NET Framework precedenti all'introduzione di XAML; in origine, uno degli scenari di TypeConverter consisteva nel fornire la conversione delle stringhe per gli editor delle proprietà nelle finestre di progettazione visiva.The TypeConverter class existed in versions of the .NET Framework before XAML existed; one of the original TypeConverter scenarios was to provide string conversion for property editors in visual designers.

Per XAML, il ruolo di TypeConverter viene esteso.For XAML, the role of TypeConverter is expanded. In XAML, TypeConverter è la classe base che fornisce il supporto per determinate conversioni da stringa e in stringa.For XAML purposes, TypeConverter is the base class for providing support for certain to-string and from-string conversions. La conversione da stringa consente l'analisi di un valore dell'attributo di stringa da XAML.From-string enables parsing a string attribute value from XAML. La conversione in stringa può permettere l'elaborazione di un valore di runtime di una particolare proprietà dell'oggetto in un attributo in XAML per la serializzazione.To-string might enable processing a run-time value of a particular object property back into an attribute in XAML for serialization.

TypeConverter definisce quattro membri rilevanti per la conversione da e in stringa per l'elaborazione XAML:TypeConverter defines four members that are relevant for converting to-string and from-string for XAML processing purposes:

Di questi membri, il metodo più importante è ConvertFrom, che converte la stringa di input nel tipo di oggetto richiesto.Of these members, the most important method is ConvertFrom, which converts the input string to the required object type. È possibile implementare il metodo ConvertFrom per convertire una più vasta gamma di tipi nel tipo di destinazione previsto dal convertitore.The ConvertFrom method can be implemented to convert a wider range of types into the intended destination type of the converter. Il metodo assolve quindi scopi che si estendono oltre quelli definiti per XAML, ad esempio il supporto delle conversioni in fase di esecuzione.Therefore, it can serve purposes that extend beyond XAML, such as supporting run-time conversions. Per quanto riguarda XAML, tuttavia, l'unico elemento importante è il percorso del codice che consente di elaborare un input String .However, for XAML use, only the code path that can process a String input is important.

Il secondo metodo in ordine di importanza è ConvertTo.The second most important method is ConvertTo. Se un'applicazione viene convertita in una rappresentazione del markup (quando ad esempio viene salvata in XAML come file), ConvertTo è coinvolto nel più ampio scenario più ampio della creazione di una rappresentazione di markup da parte di writer di testi XAML.If an application is converted to a markup representation (for example, if it is saved to XAML as a file), ConvertTo is involved in the larger scenario of a XAML text writers produce a markup representation. In questo caso, il percorso di codice importante per XAML è il passaggio di destinationType di Stringda parte del chiamante.In this case, the important code path for XAML is when the caller passes 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 implementazione di TypeConverter può interpretare in modo univoco il concetto di stringa valida per una conversione e può quindi usare o ignorare la descrizione del tipo passata come parametri.Each TypeConverter implementation can uniquely interpret what is a valid string for a conversion, and it can also use or ignore the type description that is passed as parameters. Una considerazione importante circa le impostazioni cultura e la conversione di tipi XAML: anche se l'uso di stringhe localizzabili come valori di attributo è supportato da XAML, non è possibile usare queste stringhe come input del convertitore di tipi con requisiti specifici per le impostazioni cultura.An important consideration for culture and XAML type conversion is the following: although using localizable strings as attribute values is supported by XAML, you cannot use these localizable strings as type converter input with specific culture requirements. Questa limitazione è dovuta al fatto che i convertitori di tipi per i valori di attributo XAML implicano necessariamente un comportamento di elaborazione XAML basato su un'unica lingua che usa le impostazioni cultura en-US .This limitation is because type converters for XAML attribute values involve a necessarily fixed-language XAML-processing behavior that uses en-US culture. Per ulteriori informazioni sui motivi legati alla progettazione per questa restrizione, vedere la specifica del linguaggio XAML ([MS-XAML]) o WPF Panoramica della globalizzazione e localizzazione.For more information about the design reasons for this restriction, see the XAML language specification ([MS-XAML]) or WPF Globalization and Localization Overview.

Un esempio delle problematiche che possono presentarsi con le impostazioni cultura è rappresentato dal separatore decimale per i numeri in formato stringa, che per alcune impostazioni cultura è la virgola anziché il punto.As an example where culture can be an issue, some cultures use a comma instead of a period as the decimal point delimiter for numbers in string form. Quest'uso è in conflitto con il comportamento di molti convertitori di tipi esistenti, che prevede l'uso della virgola come delimitatore.This use collides with the behavior that many existing type converters have, which is to use a comma as a delimiter. Il passaggio di impostazioni cultura tramite xml:lang nel codice XAML adiacente non risolve il problema.Passing a culture through xml:lang in the surrounding XAML 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 ha un formato valido e può essere convertita dall'implementazione di TypeConverter , l'oggetto restituito deve supportare un cast nel tipo previsto dalla proprietà.If the string is in a valid format and can be converted by the TypeConverter implementation, the returned object must support a cast to the type that is expected by the property. In caso contrario, l'implementazione ConvertFrom deve restituire null.Otherwise, the ConvertFrom implementation must return null.

Ogni implementazione di TypeConverter può interpretare in modo univoco il concetto di stringa valida per una conversione e può anche usare o ignorare i contesti di descrizione del tipo o di impostazione cultura passati come parametri.Each TypeConverter implementation can uniquely interpret what constitutes a valid string for a conversion, and it can also use or ignore the type description or culture contexts that are passed as parameters. Tuttavia, l'elaborazione della sintassi XAML di WPF potrebbe non passare i valori al contesto della descrizione del tipo in tutti i casi e potrebbe perfino non passare 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 utilizzare le parentesi graffe ({}), in particolare la parentesi graffa aperta ({), come un elemento del formato stringa.Do not use the braces ({}), specifically the opening brace ({), as an 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.

È opportuno generare un'eccezione quando il convertitore di tipi deve avere accesso a un servizio XAML dal writer di oggetti di servizi XAML di .NET Framework, ma la chiamata a GetService eseguita rispetto al contesto non restituisce tale servizio.It is appropriate to throw an exception when your type converter must have access to a XAML service from the .NET Framework XAML Services object writer, but the GetService call that is made against the context does not return that service.

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 implementazione di TypeConverter che supporti XAML, il metodo ConvertTo per il convertitore deve accettare un'istanza del tipo (o un valore) supportata come parametro value .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) that is supported as the value parameter. Quando il parametro destinationType è di tipo String, deve essere possibile eseguire il cast dell'oggetto restituito come String.When the destinationType parameter is of type String, 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 che si otterrebbe se quella stringa venisse passata all'implementazione di ConvertFrom dello stesso convertitore, senza perdite significative di informazioni.Ideally, the serialization format that you choose should be able to generate the same value as 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, l'implementazione di ConvertTo deve restituire null e può generare un'eccezione.If the value cannot be serialized or the converter does not support serialization, the ConvertTo implementation must return null and can throw an exception. Tuttavia, se si generano eccezioni, sarà necessario segnalare l'impossibilità di usare tale conversione nell'implementazione di CanConvertTo in modo da supportare un controllo preventivo con CanConvertTo , che rappresenta la procedura consigliata per evitare eccezioni.However, 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 il parametro destinationType non è di tipo String, è possibile scegliere la gestione del convertitore.If the destinationType parameter is not of type String, you can choose your own converter handling. In genere viene ripristinata la gestione dell'implementazione di base, che nella forma base di ConvertTo genera un'eccezione specifica.Typically, you revert to base implementation handling, which in the base ConvertTo raises a specific exception.

È opportuno generare un'eccezione quando il convertitore di tipi deve avere accesso a un servizio XAML dal writer di oggetti di servizi XAML di .NET Framework, ma la chiamata a GetService eseguita rispetto al contesto non restituisce tale servizio.It is appropriate to throw an exception when your type converter must have access to a XAML service from the .NET Framework XAML Services object writer, but the GetService call that is made against the context does not return that service.

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. Non generare eccezioni da CanConvertFrom.Do not throw exceptions from CanConvertFrom.

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. Non generare eccezioni da CanConvertTo.Do not throw exceptions from CanConvertTo.

Applicazione di TypeConverterAttributeApplying the TypeConverterAttribute

Affinché il convertitore di tipi personalizzato venga usato come convertitore di tipi operativo per una classe personalizzata dall'elaborazione dei servizi XAML di .NET Framework, è necessario applicare l' attributo .NET Framework.NET Framework attribute TypeConverterAttribute alla definizione della classe.For your custom type converter to be used as the acting type converter for a custom class by .NET Framework XAML Services, 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 cui il tipo di proprietà usa il tipo di classe personalizzato, può immettere stringhe e restituire istanze di oggetti.If you apply this attribute, 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 della proprietà (la definizione principale, non le implementazioni di get/set al suo interno).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 quella proprietà, può elaborare stringhe di input e restituire istanze di oggetti.With this attribute applied, when a XAML processor 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.

Per fornire un comportamento di conversione di tipi per un membro associato personalizzato, applicare TypeConverterAttribute al metodo della funzione di accesso Get del modello di implementazione per il membro associato.To supply a type conversion behavior for a custom attached member, apply TypeConverterAttribute to the Get accessor method of the implementation pattern for the attached member.

Accesso al contesto del provider di servizi da un'implementazione dell'estensione di markupAccessing Service Provider Context from a Markup Extension Implementation

I servizi disponibili sono gli stessi per qualsiasi convertitore di valori.The available services are the same for any value converter. L'unica differenza risiede nel modo in cui ogni convertitore di valori riceve il contesto del servizio.The difference is in how each value converter receives the service context. L'accesso ai servizi e i servizi disponibili sono illustrati nell'argomento Type Converters and Markup Extensions for XAML.Accessing services and the services available are documented in the topic Type Converters and Markup Extensions for XAML.

Convertitori di tipi nel flusso di nodi XAMLType Converters in the XAML Node Stream

Se si usa un flusso del nodo XAML, l'azione o il risultato finale di un convertitore di tipi non è ancora eseguito.If you are working with a XAML node stream, the action or end result of a type converter is not yet executed. In un percorso di caricamento, la stringa dell'attributo che necessita di una conversione di tipi ai fini del caricamento resta sotto forma di valore testuale all'interno di un membro iniziale e di un membro finale.In a load path, the attribute string that eventually needs to be type-converted in order to load remains as a text value within a start member and end member. Il convertitore di tipi eventualmente necessario per questa operazione può essere determinato tramite la proprietà XamlMember.TypeConverter.The type converter that is eventually needed for this operation can be determined by using the XamlMember.TypeConverter property. Tuttavia, per ottenere un valore valido da XamlMember.TypeConverter è necessario avere un contesto dello schema XAML, che può accedere a queste informazioni tramite il membro sottostante, o il tipo del valore dell'oggetto usato dal membro.However, obtaining a valid value from XamlMember.TypeConverter relies on having a XAML schema context, which can access such information through the underlying member, or the type of the object value that the member uses. Il richiamo del comportamento di conversione di tipi richiede anche il contesto dello schema XAML poiché ciò richiede il mapping dei tipi e la creazione di un'istanza del convertitore.Invoking the type conversion behavior also requires the XAML schema context because that requires type-mapping and creating a converter instance.

Vedere ancheSee Also

TypeConverterAttribute
Convertitori di tipi ed estensioni di markup per XAMLType Converters and Markup Extensions for XAML
Cenni preliminari su XAML (WPF)XAML Overview (WPF)