Información general sobre los convertidores de tipos para XAMLType Converters for XAML Overview

Los convertidores de tipos proporcionan la lógica de un sistema de escritura de objetos que convierte una cadena de marcado XAML en objetos concretos en un gráfico de objetos.Type converters supply logic for an object writer that converts from a string in XAML markup into particular objects in an object graph. En los servicios XAML de .NET Framework, el convertidor de tipos tiene que ser una clase que se deriva de TypeConverter.In .NET Framework XAML Services, the type converter must be a class that derives from TypeConverter. Algunos convertidores también admiten la ruta de acceso de guardado de XAML y se pueden usar para serializar un objeto en forma de cadena en el marcado de serialización.Some converters also support the XAML save path and can be used to serialize an object into a string form in serialization markup. En este tema se describe cómo y cuándo se invocan convertidores de tipos en XAML y se incluyen consejos de implementación para los reemplazos de método de TypeConverter.This topic describes how and when type converters in XAML are invoked, and provides implementation advice for the method overrides of TypeConverter.

Conceptos de la conversión de tiposType Conversion Concepts

En las siguientes secciones se explican los conceptos básicos sobre el modo en que XAML usa cadenas y la forma en que los sistemas de escritura de objetos en los servicios XAML de .NET Framework emplean los convertidores de tipos para procesar algunos de los valores de cadena que se encuentran en un origen 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.

Valores de cadena y XAMLXAML and String Values

Cuando se establece un valor de atributo en un archivo XAML, el tipo inicial de ese valor es una cadena en sentido general y un valor de atributo de cadena desde el punto de vista de 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. Incluso otros primitivos, como Double son cadenas inicialmente para un procesador XAML.Even other primitives such as Double are initially strings to a XAML processor.

En la mayoría de los casos, un procesador XAML necesita dos fragmentos de información para procesar un valor de atributo.In most cases, a XAML processor needs two pieces of information to process an attribute value. El primer fragmento de información es el tipo de valor de la propiedad que se va a establecer.The first piece of information is the value type of the property that is being set. Cualquier cadena que defina un valor de atributo y que se procese en XAML se tiene que convertir o resolver en última instancia en un valor de ese 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. Si el valor es un primitivo que el analizador XAML entiende (por ejemplo, un valor numérico), se tratará de convertir la cadena directamente.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 el valor del atributo hace referencia a una enumeración, se buscará un nombre en la cadena proporcionada que coincida con una constante con nombre en esa enumeración.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. Si el valor no es ni un primitivo que el analizador entiende ni un nombre de constante de una enumeración, el tipo en cuestión debe poder proporcionar un valor o una referencia que se basa en una cadena convertida.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

Las directivas de lenguaje XAML no usan convertidores de tipos.XAML language directives do not use type converters.

Convertidores de tipos y extensiones de marcadoType Converters and Markup Extensions

Los usos de extensiones de marcado han de controlarse con un procesador XAML antes de buscar tipos de propiedades y otras consideraciones.Markup extension usages must be handled by a XAML processor before it checks for property type and other considerations. Por ejemplo, si una propiedad que se establece como un atributo tiene normalmente una conversión de tipos, pero en un caso determinado se establece por medio de un uso de extensión de marcado, el comportamiento de la extensión de marcado se procesa primero.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 situación común donde una extensión de marcado es necesaria es a la hora de hacer referencia a un objeto que ya existe.One common situation where a markup extension is necessary is to make a reference to an object that already exists. En este escenario, un convertidor de tipos sin estado solamente puede generar una nueva instancia, algo que puede no ser deseable.For this scenario, a stateless type converter can only generate a new instance, which might not be desirable. Para más información sobre las extensiones de marcado, vea Markup Extensions for XAML Overview.For more information about markup extensions, see Markup Extensions for XAML Overview.

Convertidores de tipos nativosNative Type Converters

En las implementaciones de servicios WPF y XAML. NET, existen ciertos tipos CLR que tienen el control de la conversión de tipo nativo, sin embargo, esos tipos CLR no se convencionalmente pensar como tipos primitivos.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 ejemplo de este tipo es DateTime.An example of such a type is DateTime. Una razón para esto es el modo en que la arquitectura de .NET Framework funciona: el tipo DateTime se define en mscorlib, la biblioteca más básica de .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. DateTime no se puede atribuir con un atributo que proceda de otro ensamblado que tiene una dependencia (TypeConverterAttribute proviene de System); por lo tanto, no se admite el mecanismo de detección de convertidores de tipos habitual mediante atribución.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. En su lugar, el analizador XAML tiene una lista de tipos que necesitan procesamiento nativo y los procesa de manera similar a como lo hacen los primitivos genuinos.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. En el caso de DateTime, este procesamiento conlleva llamar a Parse.In the case of DateTime, this processing involves a call to Parse.

Implementación de un convertidor de tiposImplementing a Type Converter

En las siguientes secciones se describe la API de la clase TypeConverter .The following sections discuss the API of the TypeConverter class.

TypeConverterTypeConverter

En los servicios XAML de .NET Framework, todos los convertidores de tipos que se usan con fines de XAML son clases que se derivan de la clase 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 clase TypeConverter ya estaba en versiones de .NET Framework previas a la existencia de XAML; uno de los escenarios de TypeConverter originales era proporcionar la conversión de cadenas a los editores de propiedades de los diseñadores visuales.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.

Para XAML, el rol de TypeConverter se amplía.For XAML, the role of TypeConverter is expanded. Para los propósitos de XAML, TypeConverter es la clase base que proporciona compatibilidad con determinadas conversiones a cadena y desde cadena.For XAML purposes, TypeConverter is the base class for providing support for certain to-string and from-string conversions. La conversión desde cadena permite analizar un valor de atributo de cadena desde XAML.From-string enables parsing a string attribute value from XAML. En cuanto a la conversión a cadena, puede permitir el procesamiento de un valor de tiempo de ejecución de una propiedad de objeto determinado de vuelta a un atributo en XAML para su serialización.To-string might enable processing a run-time value of a particular object property back into an attribute in XAML for serialization.

TypeConverter define a cuatro miembros que son importantes para convertir a cadena y desde cadena con fines de procesamiento de XAML:TypeConverter defines four members that are relevant for converting to-string and from-string for XAML processing purposes:

De estos miembros, el método más importante es ConvertFrom, que convierte la cadena de entrada en el tipo de objeto necesario.Of these members, the most important method is ConvertFrom, which converts the input string to the required object type. El método ConvertFrom se puede implementar para convertir una gama más amplia de tipos en el tipo de destino previsto del convertidor.The ConvertFrom method can be implemented to convert a wider range of types into the intended destination type of the converter. Por lo tanto, se puede utilizar con fines que van más allá de XAML, como admitir conversiones en tiempo de ejecución.Therefore, it can serve purposes that extend beyond XAML, such as supporting run-time conversions. Con todo, en el uso de XAML, solamente es importante la ruta de código que puede procesar una entrada String .However, for XAML use, only the code path that can process a String input is important.

El segundo método en importancia es ConvertTo.The second most important method is ConvertTo. Si una aplicación se convierte en una representación de marcado (por ejemplo, si se guarda en XAML como un archivo), ConvertTo estará implicado en el escenario más amplio de un sistema de escritura de texto XAML que produce una representación de marcado.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. En tal caso, la ruta de acceso de código importante para XAML es cuando el autor de la llamada pasa un destinationType de String.In this case, the important code path for XAML is when the caller passes a destinationType of String.

CanConvertTo y CanConvertFrom son métodos de compatibilidad que se usan cuando un servicio consulta las capacidades de la implementación de TypeConverter .CanConvertTo and CanConvertFrom are support methods that are used when a service queries the capabilities of the TypeConverter implementation. Estos métodos se tienen que implementar para obtener true en los casos específicos de tipo que los métodos de conversión equivalentes de su convertidor admiten.You must implement these methods to return true for type-specific cases that the equivalent conversion methods of your converter support. Para los propósitos de XAML, esto suele traducirse en el tipo String .For XAML purposes, this generally means the String type.

Información de referencia cultural y convertidores de tipos para XAMLCulture Information and Type Converters for XAML

Cada implementación de TypeConverter puede interpretar de manera única lo que es una cadena válida para una conversión y, también, puede usar o ignorar la descripción del tipo pasado como parámetros.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 consideración importante para la conversión de tipos de referencia cultural y XAML es la siguiente: aunque XAML admite el uso de cadenas localizables como valores de atributo, estas cadenas localizables no se pueden usar como entrada del convertidor de tipos con determinados requisitos de referencia cultural.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. Esta limitación obedece a que los convertidores de tipos de los valores de atributo XAML conllevan un comportamiento de procesamiento XAML de lenguaje obligatoriamente fijo que usa la referencia cultural 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. Para obtener más información sobre los motivos de diseño de esta restricción, vea la especificación del lenguaje XAML ([MS-XAML]) o WPF Globalization and Localization Overview.For more information about the design reasons for this restriction, see the XAML language specification ([MS-XAML]) or WPF Globalization and Localization Overview.

Un ejemplo donde la referencia cultural puede ser un problema son algunas referencias culturales que usan una coma en lugar de un punto como delimitador de separador decimal para los números en forma de cadena.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. Este uso entra en conflicto con el comportamiento de muchos convertidores de tipos existentes, que consiste en usar una coma como delimitador.This use collides with the behavior that many existing type converters have, which is to use a comma as a delimiter. Pasar una referencia cultural por xml:lang en el XAML adyacente no soluciona el problema.Passing a culture through xml:lang in the surrounding XAML does not solve the issue.

Implementación de ConvertFromImplementing ConvertFrom

Para ser igual de utilizable que una implementación de TypeConverter que admite XAML, el método ConvertFrom para ese convertidor tiene que aceptar una cadena como parámetro 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 cadena tiene un formato válido y la implementación de TypeConverter puede convertirla, el objeto devuelto debe admitir una conversión al tipo que la propiedad espera.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. De lo contrario, la implementación de ConvertFrom debe devolver null.Otherwise, the ConvertFrom implementation must return null.

Cada implementación de TypeConverter puede interpretar de manera única qué constituye una cadena válida para una conversión y, también, puede usar o ignorar la descripción del tipo o los contextos de referencia cultural pasados como parámetros.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. Sin embargo, el procesamiento de XAML de WPF podría no pasar valores al contexto de descripción del tipo en todos los casos y, asimismo, no pasar referencias culturales basadas en 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

No utilice las llaves ({}), específicamente la llave de apertura ({}), como un elemento de su formato de cadena.Do not use the braces ({}), specifically the opening brace ({), as an element of your string format. Estos caracteres están reservados como entrada y salida de una secuencia de extensión de marcado.These characters are reserved as the entry and exit for a markup extension sequence.

Resulta adecuado generar una excepción cuando el convertidor de tipos ha de tener acceso a un servicio XAML desde el sistema de escritura de objeto de los servicios XAML de .NET Framework, pero la llamada a GetService que se realiza en el contexto no devuelve ese servicio.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.

Implementación de ConvertToImplementing ConvertTo

ConvertTo se usa en teoría para admitir la serialización.ConvertTo is potentially used for serialization support. La compatibilidad con la serialización a través de ConvertTo para el tipo personalizado y su convertidor de tipos no es un requisito imprescindible.Serialization support through ConvertTo for your custom type and its type converter is not an absolute requirement. Pero, si implementa un control, o usa la serialización como parte de las características o del diseño de la clase, conviene implementar 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.

Para ser igual de utilizable que una implementación de TypeConverter que admite XAML, el método ConvertTo para ese convertidor tiene que aceptar una instancia del tipo (o un valor) que se pueda usar como parámetro 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. Cuando el parámetro destinationType es de tipo String, el objeto devuelto debe poder convertirse en String.When the destinationType parameter is of type String, the returned object must be able to be cast as String. La cadena devuelta debe representar un valor serializado de value.The returned string must represent a serialized value of value. Lo ideal sería que el formato de serialización elegido sea capaz de generar el mismo valor que si esa cadena se pasara a la implementación de ConvertFrom del mismo convertidor sin incurrir en una pérdida significativa de información.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.

Si el valor no se puede serializar o el convertidor no admite la serialización, la implementación de ConvertTo debe devolver null y puede producir una excepción.If the value cannot be serialized or the converter does not support serialization, the ConvertTo implementation must return null and can throw an exception. Pero, si se producen excepciones, será necesario dejar constancia de la imposibilidad de usar esa conversión como parte de su implementación de CanConvertTo para, así, poder dar cabida al procedimiento recomendado de comprobar primero con CanConvertTo para evitar excepciones.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.

Si el parámetro destinationType no es de tipo String, puede elegir su propio control de convertidor.If the destinationType parameter is not of type String, you can choose your own converter handling. Normalmente, se vuelve al control de implementación base, que en el ConvertTo base genera una excepción específica.Typically, you revert to base implementation handling, which in the base ConvertTo raises a specific exception.

Resulta adecuado generar una excepción cuando el convertidor de tipos ha de tener acceso a un servicio XAML desde el sistema de escritura de objeto de los servicios XAML de .NET Framework, pero la llamada a GetService que se realiza en el contexto no devuelve ese servicio.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.

Implementación de CanConvertFromImplementing CanConvertFrom

Su implementación de CanConvertFrom debe devolver true para sourceType de tipo String o, si no, respetar la implementación base.Your CanConvertFrom implementation should return true for sourceType of type String and otherwise, defer to the base implementation. No genere excepciones desde CanConvertFrom.Do not throw exceptions from CanConvertFrom.

Implementación de CanConvertToImplementing CanConvertTo

Su implementación de CanConvertTo debe devolver true para destinationType de tipo Stringo, si no, respetar la implementación base.Your CanConvertTo implementation should return true for destinationType of type String, and otherwise defer to the base implementation. No genere excepciones desde CanConvertTo.Do not throw exceptions from CanConvertTo.

Aplicación de TypeConverterAttributeApplying the TypeConverterAttribute

Para que los servicios XAML de .NET Framework usen su convertidor de tipos personalizado como el convertidor de tipos que actúa para una clase personalizada, es necesario aplicar el Atributo de .NET Framework.NET Framework attribute TypeConverterAttribute en su definición de clase.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 Atributo de .NET Framework.NET Framework attribute TypeConverterAttribute to your class definition. El ConverterTypeName que se especifica a través del atributo debe ser el nombre de tipo del convertidor de tipos personalizado.The ConverterTypeName that you specify through the attribute must be the type name of your custom type converter. Si aplica este atributo, cuando un procesador XAML controla valores donde el tipo de propiedad usa el tipo de la clase personalizada, puede especificar cadenas y devolver instancias de objeto.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.

También puede proporcionar un convertidor de tipos por cada propiedad.You can also provide a type converter on a per-property basis. En lugar de aplicar un Atributo de .NET Framework.NET Framework attribute TypeConverterAttribute a la definición de clase, aplíquelo a una definición de propiedad (la definición principal, no las implementaciones de get/set dentro de ella).Instead of applying a Atributo de .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). El tipo de la propiedad tiene que coincidir con el tipo que el convertidor de tipos personalizado procesa.The type of the property must match the type that is processed by your custom type converter. Con este atributo aplicado, cuando un procesador XAML controla valores de esa propiedad, puede procesar cadenas de entrada y devolver instancias de objeto.With this attribute applied, when a XAML processor handles values of that property, it can process input strings and return object instances. La técnica de convertidor de tipos por propiedad resulta especialmente útil si decide usar un tipo de propiedad de Microsoft .NET Framework o de alguna otra biblioteca donde no se puede controlar la definición de clase y no se puede aplicar un TypeConverterAttribute no existe.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.

Para proporcionar un comportamiento de conversión de tipos para un miembro asociado personalizado, aplique TypeConverterAttribute al método de descriptor de acceso Get del patrón de implementación del miembro asociado.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.

Acceso al contexto del proveedor de servicios desde una implementación de extensión de marcadoAccessing Service Provider Context from a Markup Extension Implementation

Los servicios disponibles son los mismos para todos los convertidores de valores.The available services are the same for any value converter. La diferencia radica en la manera en que cada convertidor de valores recibe el contexto de servicio.The difference is in how each value converter receives the service context. El acceso a los servicios y los servicios disponibles se documentan en el tema 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.

Convertidores de tipos en el flujo de nodo XAMLType Converters in the XAML Node Stream

Si está trabajando con un flujo de nodo XAML, la acción o el resultado final de un convertidor de tipos no se ejecuta todavía.If you are working with a XAML node stream, the action or end result of a type converter is not yet executed. En una ruta de acceso de carga, la cadena de atributo que finalmente se debe convertir en tipo para poder cargarse permanece como un valor de texto dentro de un miembro de inicio y un miembro de finalización.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. El convertidor de tipos necesario en última instancia para esta operación se puede averiguar con la propiedad XamlMember.TypeConverter .The type converter that is eventually needed for this operation can be determined by using the XamlMember.TypeConverter property. Sin embargo, para obtener un valor válido de XamlMember.TypeConverter hay que tener un contexto de esquema XAML, que puede tener acceso a dicha información a través del miembro subyacente, o el tipo del valor del objeto que el miembro usa.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. Invocar el comportamiento de conversión de tipos también precisa del contexto de esquema XAML, porque requiere la asignación de tipos y crear una instancia del convertidor.Invoking the type conversion behavior also requires the XAML schema context because that requires type-mapping and creating a converter instance.

Vea tambiénSee also