x:Name-Anweisung

Artikel
05/04/2023

Identifiziert XAML-definierte Elemente in einem XAML-Namescope eindeutig. XAML-Namescopes und ihre Eindeutigkeitsmodelle können auf die instanziierten Objekte angewendet werden, wenn Frameworks APIs bereitstellen oder Verhalten implementieren, die zur Laufzeit auf das XAML-erstellte Objektdiagramm zugreifen.

Verwendung von XAML-Attributen

<object x:Name="XAMLNameValue".../>

XAML-Werte

Wert	Beschreibung
`XAMLNameValue`	Eine Zeichenfolge, die den Vorgaben der XamlName-Grammatik entspricht.

Hinweise

Nachdem x:Name auf das zugrunde liegende Programmmodell eines Frameworks angewendet wurde, entspricht der Name der Variable, die einen Objektverweis oder eine Instanz enthält, wie sie von einem Konstruktor zurückgegeben werden.

Der Wert einer x:Name-Direktive darf innerhalb eines XAML-Namescopes nur einmalig vorkommen. Standardmäßig wird das primäre XAML-Namescope bei Verwendung von .NET XAML Services API im XAML-Stammelement einer einzelnen XAML-Produktion definiert und umfasst die Elemente, die in dieser XAML-Produktion enthalten sind. Zusätzliche diskrete XAML-Namescopes, die in einer einzelnen XAML-Produktion vorkommen, können durch Frameworks definiert werden, um bestimmte Zwecke zu erfüllen. In WPF werden beispielsweise neue XAML-Namescopes von jeder Vorlage definiert und erstellt, die auch in dieser XAML-Produktion definiert ist. Weitere Informationen zu XAML-Namescopes (geschrieben für WPF, aber zutreffend auf viele XAML-Namescope-Konzepte), finden Sie unter WPF-XAML-Namescopes.

Im Allgemeinen sollte x:Name nicht in Situationen angewendet werden, wo auch x:Key verwendet wird. XAML-Implementierungen durch bestimmte vorhandene Frameworks bieten Konzepte zum Ersetzen von x:Key und x:Name, aber das ist keine empfohlene Praxis. .NET XAML Services unterstützt keine solchen Substitutionskonzepte beim Behandeln von Namen-/Schlüsselinformationen wie INameScope oder DictionaryKeyPropertyAttribute.

Regeln für die Genehmigung von x:Name sowie die Durchsetzung eindeutiger Namen sind potenziell durch bestimmte Implementierungsframeworks definiert. Um jedoch mit .NET XAML Services nutzbar zu sein, sollten die Frameworkdefinitionen für die Eindeutigkeit von XAML-Namescopes mit der Definition von INameScope-Informationen in dieser Dokumentation übereinstimmen und die gleichen Regeln für die Anwendung der Informationen verwenden. Die Windows Presentation Foundation(WPF)-Implementierung unterteilt beispielsweise verschiedene Markupelemente in separate NameScope-Bereiche, z. B. Ressourcenwörterbücher, die von XAML auf Seitenebene erstellte logische Struktur, Vorlagen und andere verzögerte Inhalte, und erzwingt dann die Eindeutigkeit von XAML-Namen innerhalb der einzelnen XAML-Namescopes.

Für benutzerdefinierte Typen, die .NET XAML Services XAML-Objectwriter verwenden, kann eine Eigenschaft, die x:Name einem Typ zuordnet, eingerichtet oder geändert werden. Sie definieren dieses Verhalten, indem Sie mit dem RuntimeNamePropertyAttribute im Typdefinitionscode auf den Namen der zuzuordnenden Eigenschaft verweisen. RuntimeNamePropertyAttribute ist ein Attribut auf Typebene.

Mit .NET XAML Services kann die Hintergrundlogik für die XAML-Namescope-Unterstützung auf eine frameworkneutrale Weise definiert werden, indem Sie die INameScope-Schnittstelle implementieren.

Hinweise zur WPF-Verwendung

Unter der Standard-Buildkonfiguration für WPF-Anwendungen, die XAML, Teilklassen und CodeBehind verwenden, wird der angegebene x:Name zum Namen eines Felds, das im zugrunde liegenden Code erstellt wird, wenn XAML von einer Markupkompilierungs-Buildaufgabe verarbeitet wird und dieses Feld einen Verweis auf das Objekt enthält. Standardmäßig ist das erstellte Feld intern. Sie können den Feldzugriff ändern, indem Sie das x:FieldModifier-Attribut angeben. In WPF und Silverlight definiert und benennt die Markup-Kompilierung zunächst das Feld in einer partiellen Klasse, aber der Wert ist anfangs leer. Anschließend wird eine generierte Methode namens InitializeComponent aus dem Klassenkonstruktor heraus aufgerufen. InitializeComponent besteht aus FindName-Aufrufen mit allen x:Name-Werten, die im XAML-definierten Teil der partiellen Klasse als Eingabezeichenfolgen vorhanden sind. Die Rückgabewerte werden dann dem Feldverweis mit dem jeweils gleichen Namen zugewiesen, um die Feldwerte mit Objekten zu füllen, die durch XAML-Parsing erstellt wurden. Die Ausführung von InitializeComponent ermöglicht das direkte Verweisen auf den Laufzeitobjektgraph mithilfe des x:Name / Feldnamens, anstatt jedes mal FindName explizit aufzurufen, wenn ein Verweis auf ein XAML-definiertes Objekt benötigt wird.

Für WPF-Anwendungen, die Microsoft Visual Basic-Ziele verwenden und XAML-Dateien mit der Page-Buildaktion enthalten, wird während der Kompilierung eine separate Verweiseigenschaft erstellt, die das Schlüsselwort WithEvents zu allen Elementen hinzufügt, die ein x:Name haben, um Handles-Syntax für Ereignishandlerdelegate zu unterstützen. Diese Eigenschaft ist immer öffentlich. Weitere Informationen finden Sie unter Visual Basic- und WPF-Ereignisbehandlung.

x:Name wird vom WPF-XAML-Prozessor verwendet, um einen Namen beim Laden in einem XAML-Namescope zu registrieren, auch wenn keine Markup-Kompilierung der Seite durch Buildaktionen geschieht (z. B. loses XAML in einem Ressourcenwörterbuch). Ein Grund für dieses Verhalten ist, dass möglicherweise x:Name für die ElementName-Bindung erforderlich ist. Weitere Informationen finden Sie unter Übersicht über die Datenbindung.

Wie bereits erwähnt, sollte x:Name (oder Name) nicht angewendet werden, wenn auch x:Key verwendet wird. Um dies zu erzwingen, verfügen WPF-ResourceDictionarys über ein spezielles Verhalten, durch das sie sich selbst als XAML-Namescope definieren, aber für INameScope-APIs die Werte „Not Implemented (nicht implementiert) oder NULL zurückgeben. Wenn der WPF-XAML-Parser Name oder x:Name in einem XAML-definierten ResourceDictionary vorfindet, wird der Name zu keinem XAML-Namenscope hinzugefügt. Der Versuch, diesen Namen aus einem beliebigen XAML-Namenscope zu finden, etwa mit den FindName-Methoden, gibt keine gültigen Ergebnisse zurück.

x:Name und Name

In vielen WPF-Anwendungsszenarien ist die Verwendung des x:Name-Attributs unnötig, da die Abhängigkeitseigenschaft Name, die im Standard-XAML-Namespace mehrerer wichtiger Basisklassen wie FrameworkElement und FrameworkContentElementangegeben wird, denselben Zweck erfüllt. Es gibt immer noch einige gängige XAML- und WPF-Szenarien, in denen der Codezugriff auf ein Element ohne Name-Eigenschaft auf Frameworkebene wichtig ist. Beispielsweise unterstützen bestimmte Animations- und Storyboard-Unterstützungsklassen keine Name-Eigenschaft, es muss aber häufig im Code darauf verwiesen werden, um die Animation zu steuern. Sie sollten x:Name als Attribut für Zeitachsen und Transformationen angeben, die in XAML erstellt werden, wenn Sie sie später von Code aus darauf verweisen möchten.

Wenn Name als Eigenschaft einer Klasse verfügbar ist, können Name und x:Name austauschbar als Attribute verwendet werden. Werden allerdings beide für dasselbe Element angegeben, führt dies zu einer Parsingausnahme. Wenn das XAML markup-kompiliert wird, tritt die Ausnahme bei der Markupkompilierung auf, andernfalls tritt er beim Laden auf.

Name kann mithilfe der XAML-Attributsyntax und im Code mithilfe von SetValue festgelegt werden. Beachten Sie jedoch, dass in den meisten Umständen, in denen XAML bereits geladen ist, das Festlegen der Name-Eigenschaft im Code nicht den repräsentativen Feldverweis innerhalb des XAML-Namescopes erstellt. Anstatt zu versuchen, Name im Code festzulegen, verwenden Sie NameScope-Methoden aus Code für das entsprechende Namescope.

Name Kann auch mithilfe der Eigenschaftselementsyntax mit innerem Text festgelegt werden, aber das ist unüblich. Im Gegensatz dazu kann x:Name in der XAML-Eigenschaftselementsyntax oder in Code mit SetValue nicht festgelegt werden; sie kann nur mithilfe von Attributsyntax auf Objekten festgelegt werden, da es sich um eine Anweisung handelt.

Silverlight-Verwendungshinweise

x:Name für Silverlight wird separat dokumentiert. Weitere Informationen finden Sie unter Sprachfeatures des XAML-Namespace (x:) (Silverlight).

Freigeben über