x:Key Directive

Identifiziert eindeutig Elemente, die in einem XAML-definierten Wörterbuch erstellt und referenziert werden. Das Hinzufügen eines x:Key Werts zu einem XAML-Objektelement ist die am häufigsten verwendete Methode zum Identifizieren einer Ressource in einem Ressourcenwörterbuch, z. B. in einem WPF-ResourceDictionary.

XAML-Attributverwendung

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

XAML-Attributverwendung (WPF-spezifisch)

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

XAML-Werte

Bemerkungen

x:Key unterstützt das XAML-Ressourcenwörterbuchkonzept. XAML als Sprache definiert keine Ressourcenwörterbuchimplementierung, die bestimmten BENUTZEROBERFLÄCHEN-Frameworks überlassen ist. Weitere Informationen zur Implementierung von XAML-Ressourcenwörterbüchern in WPF finden Sie unter Übersicht über XAML-Ressourcen (WPF .NET).

In XAML 2006 und WPF müssen x:Key als Attribut bereitgestellt werden. Sie können weiterhin Nichtzeichenfolgenschlüssel verwenden, aber dies erfordert eine Markuperweiterungsverwendung, um den Nichtzeichenfolgenwert in Attributform bereitzustellen. Wenn Sie XAML 2009 verwenden, kann x:Key als Element angegeben werden, um Wörterbücher, die von anderen Objekttypen als Zeichenfolgen schlüsselt, explizit zu unterstützen, ohne dass eine Markuperweiterung zwischengeschaltet werden muss. Weitere Informationen finden Sie im Abschnitt "XAML 2009" in diesem Thema. Der rest des Abschnitts "Hinweise" gilt speziell für die XAML 2006-Implementierung.

Der Attributwert von x:Key kann eine beliebige Zeichenfolge sein, die im XamlName Grammar definiert ist oder ein Objekt sein kann, das über eine Markuperweiterung ausgewertet wird. Ein Beispiel aus WPF finden Sie unter "WPF-Verwendungshinweise".

Untergeordnete Elemente eines übergeordneten Elements, das eine IDictionary Implementierung ist, müssen in der Regel ein x:Key Attribut enthalten, das einen eindeutigen Schlüsselwert innerhalb dieses Wörterbuchs angibt. Frameworks können aliasierte Schlüsseleigenschaften implementieren, um x:Key für bestimmte Typen zu ersetzen; Typen, die solche Eigenschaften definieren, sollten DictionaryKeyPropertyAttributezugeordnet werden.

Das Codeäquivalent zum Angeben x:Key ist der Schlüssel, der für die zugrunde liegende IDictionaryverwendet wird. Beispielsweise entspricht eine x:Key, die im Markup für eine Ressource in WPF angewendet wird, dem Wert des key-Parameters von ResourceDictionary.Add, wenn Sie die Ressource einem WPF-ResourceDictionary im Code hinzufügen.

WPF-Verwendungshinweise

Untergeordnete Objekte eines übergeordneten Objekts, das eine IDictionary Implementierung ist, z. B. die WPF-ResourceDictionary, müssen in der Regel ein x:Key-Attribut enthalten, und der Schlüsselwert muss innerhalb dieses Wörterbuchs eindeutig sein. Es gibt zwei wichtige Ausnahmen:

• Einige WPF-Typen deklarieren einen impliziten Schlüssel für die Wörterbuchverwendung. Beispielsweise kann ein Style mit einem TargetTypeoder ein DataTemplate mit einem DataTypein einem ResourceDictionary sein und den impliziten Schlüssel verwenden.

• WPF unterstützt ein zusammengeführtes Ressourcenwörterbuchkonzept. Schlüssel können zwischen den zusammengeführten Wörterbüchern gemeinsam verwendet werden, und auf das Verhalten des freigegebenen Schlüssels kann mithilfe von FindResourcezugegriffen werden. Weitere Informationen finden Sie unter zusammengeführten Ressourcenwörterbücher.

In der gesamten WPF-XAML-Implementierung und dem Anwendungsmodell wird die Eindeutigkeit der Schlüssel nicht vom XAML-Markupcompiler überprüft. Fehlende oder nicht eindeutige x:Key Werte verursachen stattdessen Ladezeit-XAML-Parserfehler. Die Behandlung von Wörterbüchern für WPF in Visual Studio kann jedoch häufig solche Fehler in der Entwurfsphase notieren.

Beachten Sie, dass in der angezeigten Syntax das ResourceDictionary-Objekt implizit darin besteht, wie der WPF-XAML-Prozessor eine Auflistung erzeugt, um eine Resources Auflistung aufzufüllen. Ein ResourceDictionary wird in der Regel nicht explizit als Element im Markup bereitgestellt, obwohl es in manchen Fällen möglich sein kann, wenn es um Klarheit (es wäre ein Sammlungsobjektelement zwischen dem Resources-Eigenschaftselement und den Elementen innerhalb dieses Wörterbuchs). Informationen dazu, warum ein Auflistungsobjekt fast immer ein implizites Element im Markup ist, finden Sie unter XAML-Syntax im Detail.

In der WPF-XAML-Implementierung wird die Behandlung von Ressourcenwörterbuchschlüsseln durch die abstrakte klasse ResourceKey definiert. Der WPF-XAML-Prozessor erzeugt jedoch unterschiedliche zugrunde liegende Erweiterungstypen für Schlüssel basierend auf ihren Verwendungen. Beispielsweise wird der Schlüssel für eine DataTemplate oder eine abgeleitete Klasse separat behandelt und erzeugt ein eindeutiges DataTemplateKey-Objekt.

Schlüssel und Namen verwenden unterschiedliche Direktiven und Sprachelemente (x:Key im Vergleich zu x:Name) in der grundlegenden XAML-Definition. Schlüssel und Namen werden auch in verschiedenen Situationen von der WPF-Definition und Anwendung dieser Konzepte verwendet. Ausführliche Informationen finden Sie unter WPF XAML NameScopes.

Wie bereits erwähnt, kann der Wert eines Schlüssels über eine Markuperweiterung bereitgestellt werden und kann nicht als ein Zeichenfolgenwert sein. Ein Beispiel für ein WPF-Szenario ist, dass der Wert von x:Key ein ComponentResourceKey-sein kann. Bestimmte Steuerelemente machen einen Stilschlüssel dieses Typs für eine benutzerdefinierte Formatvorlage verfügbar, die einen Teil des Erscheinungsbilds und Verhaltens dieses Steuerelements beeinflusst, ohne die Formatvorlage vollständig zu ersetzen. Ein Beispiel für einen solchen Schlüssel ist ButtonStyleKey.

Das Feature "Zusammengeführtes WPF-Wörterbuch" führt zusätzliche Überlegungen zur Eindeutigkeit und zum Verhalten von Schlüsseln für das Nachschlageverhalten ein. Weitere Informationen finden Sie unter zusammengeführten Ressourcenwörterbücher.

XAML 2009

XAML 2009 entspannt die Einschränkung, die x:Key immer in Attributform bereitgestellt werden.

In WPF können Sie XAML 2009-Features verwenden, jedoch nur für XAML, die nicht markupkompiliert ist. Markupkompiliertes XAML für WPF und die BAML-Form von XAML unterstützen derzeit nicht die XAML 2009-Schlüsselwörter und -Features.

Unter XAML 2009 können Sie x:Key Elemente mithilfe der folgenden Verwendung angeben:

XAML-Elementverwendung (nur XAML 2009)

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

XAML-Werte

• Der Container/übergeordnete Container für diese Art der Verwendung wird hier nicht angezeigt. object wird erwartet, dass es sich um ein untergeordnetes Element eines Objektelements handelt, das eine spezielle Wörterbuchimplementierung darstellt. keyObject wird erwartet, dass es sich um eine Objektinstanz (oder einen Wert eines Werttyps) handelt, die als Schlüssel für diese spezielle Wörterbuchimplementierung geeignet ist.

• WPF implementiert keine Wörterbücher, die diese Verwendung erfordern. Objektschlüssel sind allgemeinere Features der XAML-Sprache, die möglicherweise für bestimmte Benutzerwörterbuchszenarien nützlich sind, in denen das Erstellen des Wörterbuchs in XAML wünschenswert ist. Für WPF-Features wie implizite Stile, die nicht Zeichenfolgenschlüssel für Ressourcen verwenden, sind andere Techniken zum Einrichten oder Angeben der Schlüssel vorhanden, sodass die Verwendung eines Objektschlüssels nicht erforderlich ist.

• keyObject kann auch eine Markuperweiterungsverwendung im Objektelementformular und nicht eine direkte Objektinstanz sein.

Silverlight-Verwendungshinweise

x:Key für Silverlight wird separat dokumentiert. Weitere Informationen finden Sie unter XAML-Namespace (x:) Language Features (Silverlight).

Siehe auch

• Übersicht über XAML-Ressourcen (WPF .NET)
• Ressourcen im Code (WPF .NET)
• StaticResource-Markuperweiterung