x:Directiva-chave

Identifica exclusivamente elementos criados e referenciados em um dicionário definido por XAML. Adicionar um valor x:Key a um elemento de objeto XAML é a maneira mais comum de identificar um recurso em um dicionário de recursos, por exemplo, em um WPF ResourceDictionary.

Uso de atributos XAML

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

Uso de atributos XAML (específico do WPF)

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

Valores XAML

Comentários

x:Key suporta o conceito de dicionário de recursos XAML. XAML como uma linguagem não define uma implementação de dicionário de recursos, que é deixada para estruturas de interface do usuário específicas. Para saber mais sobre como os dicionários de recursos XAML são implementados no WPF, consulte Visão geral dos recursos XAML (WPF .NET).

Em XAML 2006 e WPF, x:Key deve ser fornecido como um atributo. Você ainda pode usar chaves não string, mas isso requer um uso de extensão de marcação para fornecer o valor nonstring na forma de atributo. Se você estiver usando XAML 2009, x:Key pode ser especificado como um elemento para oferecer suporte explícito a dicionários digitados por tipos de objeto diferentes de cadeias de caracteres sem exigir uma extensão de marcação intermediária. Consulte a seção "XAML 2009" neste tópico. O restante da seção Comentários se aplica especificamente à implementação do XAML 2006.

O valor do atributo de pode ser qualquer cadeia de caracteres definida no Gramática XamlName ou pode ser um objeto avaliado por meio de uma extensão de marcação. Consulte "WPF Usage Notes" para obter um exemplo do WPF.

Os elementos filho de um elemento pai que é uma implementação IDictionary normalmente devem incluir um atributo x:Key que especifica um valor de chave exclusivo dentro desse dicionário. As estruturas podem implementar propriedades de chave aliased para substituir x:Key em tipos específicos; Os tipos que definem tais propriedades devem ser atribuídos com DictionaryKeyPropertyAttribute.

O código equivalente à especificação de x:Key é a chave usada para o IDictionarysubjacente . Por exemplo, um x:Key que é aplicado na marcação para um recurso no WPF é equivalente ao valor do parâmetro key de ResourceDictionary.Add quando você adiciona o recurso a um WPF ResourceDictionary no código.

Notas de uso do WPF

Os objetos filho de um objeto pai que é uma implementação IDictionary, como o WPF ResourceDictionary, normalmente devem incluir um atributo x:Key e o valor da chave deve ser exclusivo dentro desse dicionário. Existem duas exceções notáveis:

• Alguns tipos WPF declaram uma chave implícita para uso de dicionário. Por exemplo, um Style com um TargetType, ou um DataTemplate com um DataType, pode estar em um ResourceDictionary e usar a chave implícita.

• O WPF suporta um conceito de dicionário de recursos mesclados. As chaves podem ser compartilhadas entre os dicionários mesclados e o comportamento de chave compartilhada pode ser acessado usando FindResource. Para obter mais informações, consulte Dicionários de recursos mesclados.

No modelo geral de implementação e aplicativo WPF XAML, a exclusividade da chave não é verificada pelo compilador de marcação XAML. Em vez disso, valores de x:Key ausentes ou não exclusivos causam erros do analisador XAML em tempo de carregamento. No entanto, Visual Studio manipulação de dicionários para WPF muitas vezes pode observar tais erros na fase de design.

Observe que, na sintaxe mostrada, o objeto ResourceDictionary está implícito em como o processador WPF XAML produz uma coleção para preencher uma coleção Resources. Um ResourceDictionary normalmente não é fornecido explicitamente como um elemento na marcação, embora possa ser em alguns casos se desejado para clareza (seria um elemento de objeto de coleção entre o elemento de propriedade Resources e os itens dentro que preenchem o dicionário). Para obter informações sobre por que um objeto de coleção é quase sempre um elemento implícito na marcação, consulte Sintaxe XAML em detalhes.

Na implementação WPF XAML, a manipulação de chaves de dicionário de recursos é definida pela classe abstrata ResourceKey. No entanto, o processador WPF XAML produz diferentes tipos de extensão subjacentes para chaves com base em seus usos. Por exemplo, a chave para um DataTemplate ou qualquer classe derivada é manipulada separadamente e produz um objeto DataTemplateKey distinto.

Chaves e nomes usam diretivas e elementos de linguagem diferentes (x:Key versus x:Name) na definição básica de XAML. Chaves e nomes também são usados em diferentes situações pela definição e aplicação desses conceitos pelo WPF. Para obter detalhes, consulte Namescopes WPF XAML.

Como dito anteriormente, o valor de uma chave pode ser fornecido por meio de uma extensão de marcação e pode ser diferente de um valor de cadeia de caracteres. Um exemplo de cenário WPF é que o valor de x:Key pode ser um ComponentResourceKey. Certos controles expõem uma chave de estilo desse tipo para um recurso de estilo personalizado que influencia parte da aparência e do comportamento desse controle sem substituir totalmente o estilo. Um exemplo dessa chave é ButtonStyleKey.

O recurso de dicionário mesclado do WPF introduz considerações adicionais para a exclusividade da chave e o comportamento de pesquisa de chaves. Para obter mais informações, consulte Dicionários de recursos mesclados.

XAML 2009

O XAML 2009 relaxa a restrição de que sempre x:Key ser fornecida na forma de atributo.

No WPF, você pode usar recursos XAML 2009, mas somente para XAML que não é compilado por marcação. Atualmente, o XAML compilado por marcação para WPF e o formulário BAML de XAML não suportam atualmente as palavras-chave e os recursos do XAML 2009.

Em XAML 2009, você pode especificar elementos x:Key por meio do seguinte uso:

Uso do elemento XAML (somente XAML 2009)

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

Valores XAML

• O recipiente/pai para este tipo de uso não é mostrado aqui. Espera-se que object seja filho de um elemento object que representa uma implementação de dicionário especializado. Espera-se que keyObject seja uma instância de objeto (ou um valor de um tipo de valor) que seja apropriada como a chave para essa implementação específica de dicionário especializado.

• WPF não implementa dicionários que exigem esse uso. As chaves de objeto são mais um recurso geral da linguagem XAML, possivelmente útil para certos cenários de dicionário personalizados em que a criação do dicionário em XAML é desejável. Para recursos do WPF, como estilos implícitos que usam chaves sem cadeia de caracteres para recursos, existem outras técnicas para estabelecer ou especificar as chaves, portanto, o uso de uma chave de objeto não é necessário.

• keyObject também pode ser um uso de extensão de marcação na forma de elemento de objeto, em vez de uma instância de objeto direto.

Notas de uso do Silverlight

x:Key do Silverlight é documentado separadamente. Para obter mais informações, consulte Recursos de linguagem do namespace XAML (x:) (Silverlight).

Ver também

• Visão geral dos recursos XAML (WPF .NET)
• Recursos em código (WPF .NET)
• Extensão de marcação StaticResource