Atributos de CLR relacionados con XAML para los tipos y bibliotecas personalizados

En este tema se describen los atributos de Common Language Runtime (CLR) definidos por los servicios XAML de .NET. También se describen otros atributos CLR definidos en .NET que tienen un escenario relacionado con XAML para la aplicación a ensamblados o tipos. La atribución de ensamblados, tipos o miembros con estos atributos CLR proporciona información del sistema de tipos XAML relacionada con sus tipos. La información se proporciona a cualquier consumidor XAML que use servicios XAML de .NET para procesar el flujo de nodo XAML directamente o a través de los lectores XAML dedicados y los escritores XAML.

Atributos de CLR relacionados con XAML para los tipos y bibliotecas personalizados

El uso de atributos CLR implica que se usa el CLR general para definir los tipos; de lo contrario, estos atributos no están disponibles. Si usa el CLR para definir el respaldo de tipos, el contexto de esquema XAML predeterminado usado por los escritores XAML de los servicios XAML de .NET puede leer la atribución de CLR a través de la reflexión en los ensamblados de respaldo.

En las secciones siguientes se describen los atributos relacionados con XAML que se pueden aplicar a tipos personalizados o miembros personalizados. Cada atributo CLR comunica información relevante para un sistema de tipos XAML. En la ruta de acceso de carga, la información con atributos ayuda, o bien al lector XAML a formar un flujo de nodo XAML válido, o bien al escritor XAML a generar un gráfico de objetos válido. En la ruta de acceso de guardado, la información con atributos, o bien ayuda al lector XAML a formar un flujo de nodo XAML válido que reconstituye la información del sistema de tipos XAML, o bien declara sugerencias de serialización o requisitos para el escritor XAML u otros consumidores XAML.

AmbientAttribute

Documentación de referencia: AmbientAttribute

Se aplica a: miembros de clase, propiedad o descriptor de acceso get que admiten propiedades adjuntas.

Argumentos: Ninguno

AmbientAttribute indica que la propiedad o todas las propiedades que toman el tipo con atributos deben interpretarse bajo el concepto de propiedad ambiente en XAML. El concepto de ambiente se relaciona con la forma en que los procesadores XAML determinan los propietarios de tipos de los miembros. Una propiedad ambiente es una propiedad en la que se espera que el valor esté disponible en el contexto del analizador al crear un gráfico de objetos, pero donde se suspende la búsqueda típica de miembros de tipo para el conjunto inmediato de nodos XAML que se crea.

El concepto de ambiente se puede aplicar a los miembros adjuntables, que no se representan como propiedades en términos de cómo la atribución CLR define AttributeTargets. El uso de atribución del método solo se debe aplicar para un descriptor de acceso get que admita el uso adjuntable para XAML.

ConstructorArgumentAttribute

Documentación de referencia: ConstructorArgumentAttribute

Se aplica a: clase

Argumentos: una cadena que especifica el nombre de la propiedad que coincide con un único argumento de constructor.

ConstructorArgumentAttribute especifica que un objeto se puede inicializar usando una sintaxis de constructor sin parámetros y que una propiedad del nombre especificado proporciona información de construcción. Esta información sirve principalmente para la serialización XAML. Para obtener más información, vea ConstructorArgumentAttribute.

ContentPropertyAttribute

Documentación de referencia: ContentPropertyAttribute

Se aplica a: clase

Argumentos: una cadena que especifica el nombre de un miembro del tipo con atributos.

ContentPropertyAttribute indica que la propiedad denominada por el argumento debe servir como propiedad de contenido XAML para ese tipo. La definición de propiedad de contenido XAML se transmite a todos los tipos derivados que se pueden asignar al tipo de definición. Puede invalidar la definición en un tipo derivado específico aplicando ContentPropertyAttribute en el tipo derivado específico.

Para la propiedad que actúa como propiedad de contenido XAML, el etiquetado de elementos de propiedad para la propiedad se puede omitir en el uso de XAML. Normalmente se designan propiedades de contenido XAML que promueven un marcado XAML simplificado para el contenido y los modelos de contención. Dado que solo se puede designar un miembro como la propiedad de contenido XAML, a veces se tienen opciones de diseño con respecto a cuál de varias propiedades de contenedor de un tipo se debe designar como la propiedad de contenido XAML. Las demás propiedades de contenedor deben usarse con elementos de propiedad explícitos.

En el flujo de nodo XAML las propiedades de contenido XAML siguen produciendo nodos StartMember y EndMember usando el nombre de la propiedad para el XamlMember. Para determinar si un miembro es la propiedad de contenido XAML, examine el valor XamlType de la posición StartObject y obtenga el valor de ContentProperty.

ContentWrapperAttribute

Documentación de referencia: ContentWrapperAttribute

Se aplica a: clase, específicamente tipos de colección.

Argumentos: un Type que especifica el tipo que se va a usar como tipo contenedor de contenido para el contenido externo.

ContentWrapperAttribute especifica uno o varios tipos en el tipo de colección asociado que se usará para encapsular el contenido externo. El contenido externo hace referencia a los casos en los que las restricciones del sistema de tipos en el tipo de la propiedad de contenido no capturan todos los casos de contenido posibles que admitiría el uso de XAML para el tipo propietario. Por ejemplo, la compatibilidad con XAML para el contenido de un tipo determinado podría admitir cadenas en un genérico Collection<T> fuertemente tipado. Los contenedores de contenido son útiles para migrar convenciones de marcado preexistentes a la concepción de XAML de valores asignables para colecciones, como la migración de modelos de contenido relacionados con texto.

Para especificar más de un tipo contenedor de contenido, aplique el atributo varias veces.

DependsOnAttribute

Documentación de referencia: DependsOnAttribute

Se aplica a: propiedad

Argumentos: una cadena que especifica el nombre de otro miembro del tipo con atributos.

DependsOnAttribute indica que la propiedad con atributos depende del valor de otra propiedad. Aplicar este atributo a una definición de propiedad garantiza que las propiedades dependientes se procesan primero en la escritura de objetos XAML. Los usos de DependsOnAttribute especifican los casos excepcionales de propiedades en los tipos en los que se debe seguir un orden específico de análisis para la creación de objetos válidos.

Puede aplicar varios casos DependsOnAttribute a una definición de propiedad.

MarkupExtensionReturnTypeAttribute

Documentación de referencia: MarkupExtensionReturnTypeAttribute

Se aplica a: clase, que se espera que sea un tipo derivado MarkupExtension.

Argumentos: un Type que especifica el tipo más preciso que se espera como el resultado ProvideValue del MarkupExtension con atributos.

Para más información, consulte Información general de extensiones de marcado para XAML.

NameScopePropertyAttribute

Documentación de referencia: NameScopePropertyAttribute

Se aplica a: clase

Argumentos: admite dos formas de atribución:

• Una cadena que especifica el nombre de una propiedad en el tipo con atributos.

• Una cadena que especifica el nombre de una propiedad y un Type para el tipo que define la propiedad con nombre. Este formulario es para especificar un miembro adjuntable como propiedad de ámbito de nombres XAML.

NameScopePropertyAttribute especifica una propiedad que proporciona el valor del ámbito de nombres XAML para la clase con atributos. Se espera que la propiedad de ámbito de nombres XAML haga referencia a un objeto que implementa INameScope y contiene el ámbito de nombres XAML real, su almacén y su comportamiento.

RuntimeNamePropertyAttribute

Documentación de referencia: RuntimeNamePropertyAttribute

Se aplica a: clase

Argumentos: una cadena que especifica el nombre de la propiedad nombre en tiempo de ejecución en el tipo con atributos.

RuntimeNamePropertyAttribute informa de una propiedad del tipo con atributos que se asigna a la directiva x:Name de XAML. La propiedad debe ser de tipo String y debe ser de lectura y escritura.

La definición se transmite a todos los tipos derivados que se pueden asignar al tipo de definición. Puede invalidar la definición en un tipo derivado específico aplicando RuntimeNamePropertyAttribute en el tipo derivado específico.

TrimSurroundingWhitespaceAttribute

Documentación de referencia: TrimSurroundingWhitespaceAttribute

Se aplica a: tipos

Argumentos: ninguno.

TrimSurroundingWhitespaceAttribute se aplica a tipos específicos que pueden aparecer como elementos secundarios dentro del contenido significativo del espacio en blanco (contenido mantenido por una colección que tiene WhitespaceSignificantCollectionAttribute). TrimSurroundingWhitespaceAttribute es principalmente relevante para la ruta de acceso de guardado, pero está disponible en el sistema de tipos XAML en la ruta de acceso de carga al examinar XamlType.TrimSurroundingWhitespace. Para obtener más información, consulte Procesamiento del espacio en blanco en XAML.

TypeConverterAttribute

Documentación de referencia: TypeConverterAttribute

Se aplica a: clase, propiedad, método (el único caso de método válido para XAML es un descriptor de acceso get que admita un miembro adjuntable).

Argumentos: el Type del TypeConverter.

TypeConverterAttribute en un contexto XAML hace referencia a un TypeConverter personalizado. Este TypeConverter proporciona un comportamiento de conversión de tipos para tipos personalizados o miembros de ese tipo.

Aplique el atributo TypeConverterAttribute al tipo, haciendo referencia a la implementación del convertidor de tipos. Puede definir convertidores de tipos para XAML en clases, estructuras o interfaces. No es necesario proporcionar la conversión de tipos para enumeraciones, esa conversión está habilitada de forma nativa.

El convertidor de tipos debe ser capaz de convertir una cadena que se usa para atributos o texto de inicialización en el marcado en el tipo de destino previsto. Para obtener más información, consulte TypeConverters y XAML.

En lugar de aplicar a todos los valores de un tipo, un comportamiento de convertidor de tipos para XAML también se puede establecer en una propiedad específica. En este caso se aplica TypeConverterAttribute a la definición de propiedad (a la definición externa, no a las definiciones específicas get y set).

Un comportamiento de convertidor de tipos para el uso XAML de un miembro adjuntable personalizado se puede asignar mediante la aplicación de TypeConverterAttribute al descriptor de acceso del método get que admite el uso de XAML.

De forma similar a TypeConverter, TypeConverterAttribute existía en .NET antes de la existencia de XAML y el modelo de convertidor de tipos tenía otros fines. Para hacer referencia a y usar TypeConverterAttribute, debe calificarlo completamente o proporcionar una instrucción using para System.ComponentModel. Incluya también el ensamblado del sistema en el proyecto.

UidPropertyAttribute

Documentación de referencia: UidPropertyAttribute

Se aplica a: clase

Argumentos: una cadena que hace referencia a la propiedad pertinente por nombre.

Indica la propiedad CLR de una clase que renombra la directiva x:Uid.

UsableDuringInitializationAttribute

Documentación de referencia: UsableDuringInitializationAttribute

Se aplica a: clase

Argumentos: un booleano. Si se usa para el propósito previsto del atributo, el valor debe establecerse en true.

Indica si este tipo se compila de arriba a abajo durante la creación de gráficos de objetos XAML. Se trata de un concepto avanzado que probablemente esté estrechamente relacionado con la definición del modelo de programación. Para obtener más información, vea UsableDuringInitializationAttribute.

ValueSerializerAttribute

Documentación de referencia: ValueSerializerAttribute

Se aplica a: clase, propiedad, método (el único caso de método válido para XAML es un descriptor de acceso get que admita un miembro adjuntable).

Argumentos: un Type que especifica la clase de compatibilidad del serializador de valor que se usará al serializar todas las propiedades del tipo con atributos o la propiedad con atributos específica.

ValueSerializerespecifica una clase de serialización de valores que requiere más estado y contexto que un TypeConverter. ValueSerializer se puede asociar a un miembro adjuntable aplicando el atributo ValueSerializerAttribute al método de descriptor de acceso estático get para el miembro adjuntable. La serialización de valores también es aplicable a enumeraciones, interfaces y estructuras, pero no para delegados.

WhitespaceSignificantCollectionAttribute

Documentación de referencia: WhitespaceSignificantCollectionAttribute

Se aplica a: clase, específicamente a los tipos de colección que se espera que hospeden contenido mixto, donde el espacio en blanco alrededor de los elementos objeto puede ser significativo para la representación de la interfaz de usuario.

Argumentos: ninguno.

WhitespaceSignificantCollectionAttribute indica que un tipo de colección debería ser procesado como espacio en blanco significativo por un procesador XAML, lo que influye en la construcción de los nodos de valor del flujo de nodo XAML dentro de la colección. Para obtener más información, consulte Procesamiento del espacio en blanco en XAML.

XamlDeferLoadAttribute

Documentación de referencia: XamlDeferLoadAttribute

Se aplica a: clase, propiedad.

Argumentos: admite dos tipos de formularios de atribución como cadenas o tipos como Type. Vea XamlDeferLoadAttribute.

Indica que una clase o propiedad usa la carga aplazada para XAML (como el comportamiento de una plantilla) e informa de la clase que habilita el comportamiento de carga aplazada así como el tipo de contenido/destino.

XamlSetMarkupExtensionAttribute

Documentación de referencia: XamlSetMarkupExtensionAttribute

Se aplica a: clase

Argumentos: asigna un nombre a la devolución de llamada.

Indica que una clase puede usar una extensión de marcado para proporcionar un valor para una o varias de sus propiedades y que esa clase hace referencia a un controlador al que debería llamar un escritor XAML antes de realizar una operación de conjunto de extensiones de marcado en cualquier propiedad de la clase.

XamlSetTypeConverterAttribute

Documentación de referencia: XamlSetTypeConverterAttribute

Se aplica a: clase

Argumentos: asigna un nombre a la devolución de llamada.

Indica que una clase puede usar un convertidor de tipos para proporcionar un valor para una o varias de sus propiedades y que esa clase hace referencia a un controlador al que debería llamar un escritor XAML antes de realizar una operación de conjunto de convertidores de tipos en cualquier propiedad de la clase.

XmlLangPropertyAttribute

Documentación de referencia: XmlLangPropertyAttribute

Se aplica a: clase

Argumentos: una cadena que especifica el nombre de la propiedad cuyo alias se va a establecer en xml:lang en el tipo con atributos.

XmlLangPropertyAttribute informa de una propiedad del tipo con atributos que se asigna a la directiva lang de XML. La propiedad no es necesariamente de tipo String, pero debe ser asignable desde una cadena (la asignación se puede realizar asociando un convertidor de tipos con el tipo de la propiedad o con la propiedad específica). La propiedad debe ser de lectura y escritura.

El escenario de asignación de xml:lang es para que un modelo de objetos en tiempo de ejecución tenga acceso a la información de lenguaje especificada por XML sin procesar específicamente con XMLDOM.

La definición se transmite a todos los tipos derivados que se pueden asignar al tipo de definición. Puede invalidar la definición en un tipo derivado específico aplicando XmlLangPropertyAttribute al tipo derivado específico, aunque es un escenario poco común.

Atributos CLR relacionados con XAML en el nivel de ensamblado

En las secciones siguientes se describen los atributos relacionados con XAML que no se aplican a tipos o definiciones de miembro, sino que se aplican a los ensamblados. Estos atributos son pertinentes para el objetivo general de definir una biblioteca que contiene los tipos personalizados que se van a usar en XAML. Algunos de los atributos no influyen necesariamente en el flujo de nodo XAML directamente, pero se pasan en el flujo de nodo para que otros consumidores los usen. Los consumidores de la información incluyen entornos de diseño o procesos de serialización que necesitan información del espacio de nombres XAML e información de prefijo asociada. Un contexto de esquema XAML (incluido el valor predeterminado de los servicios XAML de .NET) también usa esta información.

XmlnsCompatibleWithAttribute

Documentación de referencia: XmlnsCompatibleWithAttribute

Argumentos:

• Cadena que especifica el identificador del espacio de nombres XAML que se va a subsumir.

• Una cadena que especifica el identificador del espacio de nombres XAML que puede subsumir el espacio de nombres XAML del argumento anterior.

  XmlnsCompatibleWithAttribute especifica que un espacio de nombres XAML puede subsumir a otro espacio de nombres XAML. Normalmente, el espacio de nombres XAML que realiza la inclusión se indica en un objeto XmlnsDefinitionAttribute definido anteriormente. Esta técnica se puede usar para el control de versiones de un vocabulario XAML en una biblioteca y para que sea compatible con el marcado definido previamente en el vocabulario de versiones anteriores.

XmlnsDefinitionAttribute

Documentación de referencia: XmlnsDefinitionAttribute

Argumentos:

• Una cadena que especifica el identificador del espacio de nombres XAML que se va a definir.

• Una cadena que asigna un nombre a un espacio de nombres CLR. El espacio de nombres CLR debe definir tipos públicos en el ensamblado, y al menos uno de los tipos de espacio de nombres CLR debe estar pensado para su uso en XAML.

  XmlnsDefinitionAttribute especifica una asignación por ensamblado entre un espacio de nombres XAML y un espacio de nombres CLR, que un escritor de objetos XAML o un contexto de esquema XAML usa a continuación para la resolución de tipos.

  Se puede aplicar más de un XmlnsDefinitionAttribute a un ensamblado. Esto puede hacerse por cualquier combinación de los siguientes motivos:

• El diseño de la biblioteca contiene varios espacios de nombres CLR para la organización lógica del acceso a la API en tiempo de ejecución; sin embargo, quiere que todos los tipos de esos espacios de nombres puedan usarse con XAML haciendo referencia al mismo espacio de nombres XAML. En este caso, se aplican varios atributos XmlnsDefinitionAttribute con el mismo valor XmlNamespace, pero diferentes valores ClrNamespace. Esto es especialmente útil si se definen asignaciones para el espacio de nombres XAML que el marco o la aplicación va a establecer como el espacio de nombres XAML predeterminado de uso común.

• El diseño de la biblioteca contiene varios espacios de nombres CLR y quiere una separación deliberada del espacio de nombres XAML entre los usos de tipos en esos espacios de nombres de CLR.

• Define un espacio de nombres CLR en el ensamblado y quiere que sea accesible a través de más de un espacio de nombres XAML. Este escenario se produce cuando se admiten varios vocabularios con el mismo código base.

• La compatibilidad del lenguaje XAML se define en uno o varios espacios de nombres CLR. En este caso, el valor XmlNamespace debería ser http://schemas.microsoft.com/winfx/2006/xaml.

XmlnsPrefixAttribute

Documentación de referencia: XmlnsPrefixAttribute

Argumentos:

• Una cadena que especifica el identificador de un espacio de nombres XAML.

• Una cadena que especifica un prefijo recomendado.

  XmlnsDefinitionAttribute especifica un prefijo recomendado que se usará para un espacio de nombres XAML. El prefijo es útil al escribir elementos y atributos en un archivo XAML serializado por los servicios XamlXmlWriter de XAML de .NET, o cuando una biblioteca que implementa XAML interactúa con un entorno de diseño que tiene características de edición XAML.

  Se puede aplicar más de un XmlnsPrefixAttribute a un ensamblado. Esto puede hacerse por cualquier combinación de los siguientes motivos:

• El ensamblado define tipos para más de un espacio de nombres XAML. En este caso, define valores de prefijo diferentes para cada espacio de nombres XAML.

• Se admiten varios vocabularios y se usan prefijos diferentes para cada vocabulario y espacio de nombres XAML.

• La compatibilidad del lenguaje XAML se define en el ensamblado y tiene un XmlnsDefinitionAttribute para http://schemas.microsoft.com/winfx/2006/xaml. En este caso, normalmente debe promover el prefijo x.

Vea también

• Attribute
• Definición de tipos personalizados para usarlos con los servicios XAML de .NET