x:Key (Directiva)

Identifica de forma única los elementos creados y a los que se hace referencia en un diccionario definido por XAML. Agregar un valor x:Key a un elemento de objeto XAML es la manera más común de identificar un recurso en un diccionario de recursos, por ejemplo en un WPF ResourceDictionary.

Uso de atributos XAML

<object x:Key="stringKeyValue".../>  
-or-  
<object x:Key="{markupExtensionUsage}".../>  

Uso de atributos XAML (WPF-specific)

<object.Resources>  
  <object x:Key="stringKeyValue".../>  
</object.Resources>  
-or-  
<object.Resources>  
  <object x:Key="{markupExtensionUsage}".../>  
</object.Resources>  

Valores XAML

Comentarios

x:Key admite el concepto de diccionario de recursos XAML. XAML como lenguaje no define una implementación del diccionario de recursos; eso se deja a marcos de interfaz de usuario específicos. Para obtener más información sobre cómo se implementan los diccionarios de recursos XAML en WPF, consulte Introducción a los recursos XAML (WPF .NET).

En XAML 2006 y WPF, x:Key se debe proporcionar como atributo. Todavía puede usar claves que no son de cadena, pero esto requiere un uso de extensión de marcado para proporcionar el valor que no es de cadena en forma de atributo. Si está usando XAML 2009, x:Key se puede especificar como un elemento para admitir explícitamente diccionarios con claves de tipos de objeto distintos de cadenas sin necesidad de un intermedio de extensión de marcado. Consulte la sección «XAML 2009» de este tema. El resto de la sección Comentarios se aplica específicamente a la implementación de XAML 2006.

El valor de atributo de x:Key puede ser cualquier cadena definida en la gramática xamlName o puede ser un objeto evaluado a través de una extensión de marcado. Consulte «Notas de uso de WPF» para obtener un ejemplo de WPF.

Los elementos secundarios de un elemento primario que es una implementación de IDictionary normalmente deben incluir un atributo x:Key que especifique un valor de clave único dentro de ese diccionario. Los marcos de trabajo pueden implementar propiedades de clave con alias para sustituir por x:Key en tipos concretos; los tipos que definen estas propiedades deben atribuirse con DictionaryKeyPropertyAttribute.

El código equivalente para especificar x:Key es la clave que se usa para el IDictionary subyacente. Por ejemplo, un x:Key que se aplica en marcado para un recurso de WPF es equivalente al valor del parámetro key de ResourceDictionary.Add cuando se agrega el recurso a un ResourceDictionary de WPF en el código.

Notas de uso de WPF

Los objetos secundarios de un objeto primario que es una implementación de IDictionary, como ResourceDictionary de WPF, normalmente deben incluir un atributo x:Key y el valor de clave debe ser único dentro de ese diccionario. Hay dos excepciones importantes:

• Algunos tipos de WPF declaran una clave implícita para el uso del diccionario. Por ejemplo, un Style con un TargetType, o un DataTemplate con un DataType pueden estar en ResourceDictionary y usar la clave implícita.

• WPF admite un concepto de diccionario de recursos combinado. Las claves se pueden compartir entre los diccionarios combinados y se puede acceder al comportamiento de la clave compartida mediante FindResource. Para obtener más información, vea Diccionarios de recursos combinados.

En la implementación general de XAML de WPF y el modelo de aplicación, el compilador de marcado XAML no comprueba la unicidad de claves. En su lugar, los valores x:Key que faltan o no son únicos provocan errores de analizador XAML en tiempo de carga. Sin embargo, el control de Visual Studio de diccionarios para WPF puede notar a menudo estos errores en la fase de diseño.

Tenga en cuenta que, en la sintaxis que se muestra, el objeto ResourceDictionary es implícito en cómo el procesador XAML de WPF produce una colección para rellenar una colección Resources. Normalmente un ResourceDictionary no se proporciona explícitamente como un elemento en el marcado, aunque puede ocurrir en algunos casos, si lo desea, para mayor claridad (sería un elemento de objeto de colección entre el elemento de propiedad Resources y los elementos dentro de ella que rellenan el diccionario). Para obtener información sobre por qué un objeto de colección casi siempre es un elemento implícito en el marcado, consulte Sintaxis XAML en detalle.

En la implementación XAML de WPF el control de las claves de diccionario de recursos se define mediante la clase abstracta ResourceKey. Sin embargo, el procesador XAML de WPF genera diferentes tipos de extensión subyacentes para las claves en función de sus usos. Por ejemplo, la clave de un DataTemplate o una clase derivada cualquiera se controla por separado y genera un objeto DataTemplateKey distinto.

Las claves y los nombres usan diferentes directivas y elementos de lenguaje (x:Key frente a x:Name) en la definición de XAML básica. Las claves y los nombres también se usan en diferentes situaciones mediante la definición de WPF y la aplicación de estos conceptos. Para obtener más información, vea Namescopes XAML de WPF.

Como se ha indicado anteriormente, el valor de una clave se puede proporcionar a través de una extensión de marcado y puede ser distinto de un valor de cadena. Un escenario de WPF que sirve de ejemplo es que el valor de x:Key puede ser ComponentResourceKey. Algunos controles exponen una clave de estilo de ese tipo para un recurso de estilo personalizado que influye en parte de la apariencia y el comportamiento de ese control sin reemplazar totalmente el estilo. Un ejemplo de una clave así es ButtonStyleKey.

La característica de diccionario combinado de WPF presenta consideraciones adicionales para la unicidad de la clave y el comportamiento de búsqueda de claves. Para obtener más información, vea Diccionarios de recursos combinados.

XAML 2009

XAML 2009 relaja la restricción de que x:Key siempre debe proporcionarse en forma de atributo.

En WPF puede usar las características de XAML 2009 pero solo para XAML que no se haya compilado por marcado. XAML compilado por marcado para WPF y el formulario BAML de XAML no admiten de momento las palabras clave y características de XAML 2009.

En XAML 2009 se pueden especificar elementos x:Key mediante el uso siguiente:

Uso de elementos XAML (solo XAML 2009)

<object>  
  <x:Key>  
keyObject  
  </x:Key>  
...  
</object>  

Valores XAML

• El contenedor o elemento primario de este tipo de uso no se muestra aquí. object se espera que sea un elemento secundario de un elemento de objeto que representa una implementación de diccionario especializado. keyObject se espera que sea una instancia de objeto (o un valor de un tipo de valor) que sea adecuada como clave para esa implementación de diccionario especializado en particular.

• WPF no implementa diccionarios que requieren este uso. Las claves de objeto son más una característica general del lenguaje XAML, posiblemente útil para determinados escenarios de diccionario personalizados en los que es deseable crear el diccionario en XAML. En el caso de las características de WPF, como los estilos implícitos que usan claves que no son de cadena para los recursos, existen otras técnicas para establecer o especificar las claves, por lo que no es necesario usar una clave de objeto.

• keyObject también podría ser un uso de extensión de marcado en forma de elemento de objeto en lugar de una instancia de objeto directa.

Notas de uso de Silverlight

x:Key para Silverlight se documenta por separado. Para obtener más información, consulte Características de lenguaje (x:) del espacio de nombres de XAML (Silverlight).

Vea también

• Información general sobre los recursos XAML (WPF para .NET)
• Recursos en el código (WPF .NET)
• StaticResource (extensión de marcado)