Direttiva x:Key

Identifica in modo univoco gli elementi creati e a cui viene fatto riferimento in un dizionario definito da XAML. L'aggiunta di un valore x:Key a un elemento oggetto XAML è il modo più comune per identificare una risorsa in un dizionario risorse, ad esempio in un ResourceDictionaryWPF.

Utilizzo degli attributi XAML

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

Utilizzo degli attributi XAML (specifico di WPF)

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

Valori XAML

Osservazioni

x:Key supporta il concetto di dizionario risorse XAML. XAML come linguaggio non definisce un'implementazione del dizionario risorse, lasciata a framework dell'interfaccia utente specifici. Per altre informazioni sull'implementazione dei dizionari risorse XAML in WPF, vedere Panoramica delle risorse XAML (WPF .NET).

In XAML 2006 e WPF x:Key deve essere fornito come attributo. È comunque possibile usare chiavi nonstring, ma questo richiede un utilizzo dell'estensione di markup per fornire il valore non distring in formato attributo. Se usi XAML 2009, x:Key può essere specificato come elemento per supportare in modo esplicito i dizionari con chiave in base ai tipi di oggetto diversi dalle stringhe senza richiedere un'estensione di markup intermedia. Vedere la sezione "XAML 2009" in questo argomento. La parte restante della sezione Osservazioni si applica in modo specifico all'implementazione XAML 2006.

Il valore dell'attributo di x:Key può essere qualsiasi stringa definita nel XamlName Grammar o può essere un oggetto valutato tramite un'estensione di markup. Per un esempio di WPF, vedere "Note sull'utilizzo di WPF".

Gli elementi figlio di un elemento padre che è un'implementazione IDictionary devono in genere includere un attributo x:Key che specifica un valore di chiave univoco all'interno di tale dizionario. I framework potrebbero implementare proprietà chiave con alias per sostituire x:Key su tipi specifici; I tipi che definiscono tali proprietà devono essere attribuiti con DictionaryKeyPropertyAttribute.

L'equivalente del codice di specificare x:Key è la chiave usata per l'IDictionarysottostante. Ad esempio, un x:Key applicato nel markup per una risorsa in WPF equivale al valore del parametro key di ResourceDictionary.Add quando si aggiunge la risorsa a un ResourceDictionary WPF nel codice.

Note sull'utilizzo di WPF

Gli oggetti figlio di un oggetto padre che è un'implementazione IDictionary, ad esempio WPF ResourceDictionary, devono in genere includere un attributo x:Key e il valore della chiave deve essere univoco all'interno di tale dizionario. Esistono due eccezioni rilevanti:

• Alcuni tipi WPF dichiarano una chiave implicita per l'utilizzo del dizionario. Ad esempio, un Style con un TargetTypeo un DataTemplate con un DataType, può trovarsi in un ResourceDictionary e usare la chiave implicita.

• WPF supporta un concetto di dizionario risorse unito. Le chiavi possono essere condivise tra i dizionari uniti e è possibile accedere al comportamento della chiave condivisa usando FindResource. Per altre informazioni, vedere Dizionari risorse uniti.

Nell'implementazione XAML WPF complessiva e nel modello di applicazione, l'univocità della chiave non viene controllata dal compilatore di markup XAML. Al contrario, i valori mancanti o non univoci x:Key causano errori del parser XAML in fase di caricamento. Tuttavia, la gestione di visual Studio dei dizionari per WPF spesso può notare tali errori nella fase di progettazione.

Si noti che nella sintassi mostrata l'oggetto ResourceDictionary è implicito nel modo in cui il processore XAML WPF produce una raccolta per popolare una raccolta Resources. Un ResourceDictionary non viene in genere fornito in modo esplicito come elemento nel markup, anche se in alcuni casi può essere utile per maggiore chiarezza (sarebbe un elemento oggetto raccolta tra l'elemento della proprietà Resources e gli elementi all'interno di che popolano il dizionario). Per informazioni sul motivo per cui un oggetto raccolta è quasi sempre un elemento implicito nel markup, vedere sintassi XAML in dettaglio.

Nell'implementazione XAML WPF la gestione delle chiavi del dizionario risorse viene definita dalla classe astratta ResourceKey. Tuttavia, il processore XAML WPF produce tipi di estensione sottostanti diversi per le chiavi in base ai relativi utilizzi. Ad esempio, la chiave per un DataTemplate o qualsiasi classe derivata viene gestita separatamente e produce un oggetto DataTemplateKey distinto.

Le chiavi e i nomi usano direttive ed elementi del linguaggio diversi (x:Key e x:Name) nella definizione XAML di base. Le chiavi e i nomi vengono usati anche in situazioni diverse dalla definizione e dall'applicazione WPF di questi concetti. Per informazioni dettagliate, vedere ambiti dei nomi XAML WPF.

Come indicato in precedenza, il valore di una chiave può essere fornito tramite un'estensione di markup e può essere diverso da un valore stringa. Uno scenario WPF di esempio è che il valore di x:Key può essere un ComponentResourceKey. Alcuni controlli espongono una chiave di stile di tale tipo per una risorsa di stile personalizzata che influenza parte dell'aspetto e del comportamento di tale controllo senza sostituire completamente lo stile. Un esempio di tale chiave è ButtonStyleKey.

La funzionalità del dizionario unito WPF introduce considerazioni aggiuntive per l'univocità delle chiavi e il comportamento di ricerca delle chiavi. Per altre informazioni, vedere Dizionari risorse uniti.

XAML 2009

XAML 2009 riduce la restrizione che x:Key sempre in formato attributo.

In WPF puoi usare le funzionalità XAML 2009, ma solo per XAML che non è compilato con markup. XAML compilato con markup per WPF e il formato BAML di XAML attualmente non supportano le parole chiave e le funzionalità XAML 2009.

In XAML 2009 puoi specificare x:Key elementi tramite l'utilizzo seguente:

Utilizzo elementi XAML (solo XAML 2009)

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

Valori XAML

• Il contenitore/elemento padre per questo tipo di utilizzo non è illustrato qui. object deve essere un elemento figlio di un elemento oggetto che rappresenta un'implementazione specializzata del dizionario. keyObject deve essere un'istanza dell'oggetto (o un valore di un tipo valore) appropriata come chiave per l'implementazione specifica del dizionario specializzato.

• WPF non implementa dizionari che richiedono questo utilizzo. Le chiavi oggetto sono più una funzionalità generale del linguaggio XAML, possibilmente utile per alcuni scenari di dizionario personalizzati in cui è consigliabile creare il dizionario in XAML. Per le funzionalità WPF, ad esempio gli stili impliciti che usano chiavi non stringa per le risorse, altre tecniche per stabilire o specificare le chiavi esistono, pertanto l'uso di una chiave oggetto non è necessario.

• keyObject potrebbe anche essere un utilizzo dell'estensione di markup nel formato dell'elemento oggetto, anziché un'istanza diretta dell'oggetto.

Note sull'utilizzo di Silverlight

x:Key per Silverlight è documentato separatamente. Per altre informazioni, vedere spazio dei nomi XAML (x:) Language Features (Silverlight).

Vedere anche

• Panoramica delle risorse XAML (WPF .NET)
• risorse nel codice (WPF .NET)
• dell'estensione di markup StaticResource