x:Name-Anweisungx:Name Directive

Identifiziert XAML-definierte Elemente in einem XAML-Namescope eindeutig.Uniquely identifies XAML-defined elements in a XAML namescope. XAML-Namescopes und ihre Eindeutigkeits Modelle können auf instanziierte Objekte angewendet werden, wenn Frameworks APIs bereitstellen oder Verhalten implementieren, die zur Laufzeit auf das von XAML erstellte Objekt Diagramm zugreifen.XAML namescopes and their uniqueness models can be applied to the instantiated objects, when frameworks provide APIs or implement behaviors that access the XAML-created object graph at run time.

Verwendung von XAML-AttributenXAML Attribute Usage

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

XAML-WerteXAML Values

XAMLNameValue Eine Zeichenfolge, die den Einschränkungen der XamlName-Grammatikentspricht.A string that conforms to the restrictions of the XamlName Grammar.

HinweiseRemarks

Nachdem x:Name auf das Unterstützungs Programmiermodell eines Frameworks angewendet wurde, entspricht der Name der Variablen, die einen Objekt Verweis oder eine-Instanz enthält, wie von einem Konstruktor zurückgegeben.After x:Name is applied to a framework's backing programming model, the name is equivalent to the variable that holds an object reference or an instance as returned by a constructor.

Der Wert einer x:Name direktivenverwendung muss innerhalb eines XAML-Namescope eindeutig sein.The value of an x:Name directive usage must be unique within a XAML namescope. Standardmäßig wird der primäre XAML-Namescope bei Verwendung durch .NET Framework XAML-Dienste-API im XAML-Stamm Element einer einzelnen XAML-Produktion definiert und umfasst die Elemente, die in dieser XAML-Produktion enthalten sind.By default when used by .NET Framework XAML Services API, the primary XAML namescope is defined at the XAML root element of a single XAML production, and encompasses the elements that are contained in that XAML production. Zusätzliche diskrete XAML-Namescopes, die möglicherweise in einer einzelnen XAML-Produktion auftreten, können von Frameworks definiert werden, um bestimmte Szenarien zu adressieren.Additional discrete XAML namescopes that might occur within a single XAML production can be defined by frameworks to address specific scenarios. In WPF werden z. b. neue XAML-Namescopes von jeder Vorlage definiert und erstellt, die auch in der XAML-Produktion definiert ist.For example, in WPF, new XAML namescopes are defined and created by any template that is also defined on that XAML production. Weitere Informationen zu XAML-Namescopes (für WPF geschrieben, aber für viele XAML-Namescope-Konzepte relevant) finden Sie unter WPF-XAML-Namescopes.For more information about XAML namescopes (written for WPF but relevant for many XAML namescope concepts), see WPF XAML Namescopes.

Im Allgemeinen sollten x:Name in Situationen, in denen auch x:Keyverwendet wird, nicht angewendet werden.In general, x:Name should not be applied in situations that also use x:Key. XAML-Implementierungen von bestimmten vorhandenen Frameworks haben Ersetzungs Konzepte zwischen x:Key und x:Nameeingeführt, dies ist jedoch nicht empfehlenswert.XAML implementations by specific existing frameworks have introduced substitution concepts between x:Key and x:Name, but that is not a recommended practice. .NET Framework XAML-Dienste unterstützen diese Ersetzungs Konzepte nicht, wenn Name-/Schlüsselinformationen wie INameScope oder DictionaryKeyPropertyAttributebehandelt werden..NET Framework XAML Services does not support such substitution concepts when handling name/key information such as INameScope or DictionaryKeyPropertyAttribute.

Regeln für die Durchführung von x:Name sowie die Erzwingung der namens Eindeutigkeit werden potenziell durch spezifische implementierende Frameworks definiert.Rules for permittance of x:Name as well as the name uniqueness enforcement are potentially defined by specific implementing frameworks. Um jedoch mit .NET Framework XAML-Diensten verwendbar zu sein, sollten die frameworkdefinitionen der XAML-Namescope-Eindeutigkeit mit der Definition der INameScope Informationen in dieser Dokumentation konsistent sein und dieselben Regeln wie die Informationen verwenden, auf die die Informationen angewendet werden.However, to be usable with .NET Framework XAML Services, the framework definitions of XAML namescope uniqueness should be consistent with the definition of INameScope information in this documentation, and should use the same rules regarding where the information is applied. Beispielsweise dividiert die Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF)-Implementierung verschiedene Markup Elemente in separate NameScope Bereiche, z. b. Ressourcen Wörterbücher, die logische Struktur, die von der XAML-Datei auf Seitenebene, Vorlagen und anderen verzögerten Inhalt erstellt wird, und erzwingt dann die Eindeutigkeit des XAML-namens innerhalb jedes dieser XAML-Namescopes.For example, the Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) implementation divides various markup elements into separate NameScope ranges, such as resource dictionaries, the logical tree created by the page-level XAML, templates, and other deferred content, and then enforces XAML name uniqueness within each of those XAML namescopes.

Bei benutzerdefinierten Typen, die XAML-objektwriter .NET Framework XAML-Dienste verwenden, kann eine Eigenschaft, die x:Name für einen Typ zugeordnet ist, eingerichtet oder geändert werden.For custom types that use .NET Framework XAML Services XAML object writers, a property that maps to x:Name on a type can be established or changed. Sie definieren dieses Verhalten, indem Sie auf den Namen der Eigenschaft verweisen, die dem RuntimeNamePropertyAttribute im typdefinitions Code zugeordnet werden soll.You define this behavior by referencing the name of the property to map with the RuntimeNamePropertyAttribute in the type definition code. RuntimeNamePropertyAttribute ist ein Attribut auf Typebene.RuntimeNamePropertyAttribute is a type-level attribute.

Using.NET Framework-XAML-Dienste, die Unterstützungs Logik für die Unterstützung von XAML-Namescope kann auf eine frameworkneutrale Weise definiert werden, indem die INameScope-Schnittstelle implementiert wird.Using.NET Framework XAML Services, the backing logic for XAML namescope support can be defined in a framework-neutral way by implementing the INameScope interface.

Hinweise zur WPF-VerwendungWPF Usage Notes

Unter der Standardbuildkonfiguration für eine WPFWPF Anwendung, die XAML, partielle Klassen und Code Behind verwendet, wird der angegebene x:Name der Name eines Felds, das im zugrunde liegenden Code erstellt wird, wenn XAMLXAML von einer Markup Kompilierungs Aufgabe erstellt wird, und dieses Feld enthält einen Verweis auf das Objekt.Under the standard build configuration for a WPFWPF application that uses XAML, partial classes, and code-behind, the specified x:Name becomes the name of a field that is created in the underlying code when XAMLXAML is processed by a markup compilation build task, and that field holds a reference to the object. Standardmäßig ist das erstellte Feld intern.By default, the created field is internal. Sie können den Feld Zugriff ändern, indem Sie das x:FieldModifier-Attributangeben.You can change field access by specifying the x:FieldModifier attribute. In WPF und Silverlight besteht die Sequenz darin, dass die Markup Kompilierung das Feld in einer partiellen Klasse definiert und benennt, der Wert jedoch anfänglich leer ist.In WPF and Silverlight, the sequence is that the markup compile defines and names the field in a partial class, but the value is initially empty. Anschließend wird eine generierte Methode namens "InitializeComponent" innerhalb des Klassenkonstruktors aufgerufen.Then, a generated method named InitializeComponent is called from within the class constructor. InitializeComponent besteht aus FindName aufrufen, die jeden der x:Name Werte verwenden, die im XAML-definierten Teil der partiellen Klasse als Eingabe Zeichenfolgen vorhanden sind.InitializeComponent consists of FindName calls using each of the x:Name values that exist in the XAML-defined part of the partial class as input strings. Die Rückgabewerte werden dann dem like-benannten Feldverweis zugewiesen, um die Feldwerte mit Objekten auszufüllen, die aus der XAML-Verarbeitung erstellt wurden.The return values are then assigned to the like-named field reference to fill the field values with objects that were created from XAML parsing. Durch die Ausführung von InitializeComponent können Sie auf das Laufzeitobjekt Diagramm direkt mithilfe des x:Name/Feldnamens verweisen, anstatt FindName explizit aufrufen zu müssen, wenn Sie einen Verweis auf ein XAML-definiertes Objekt benötigen.The execution of InitializeComponent make it possible to reference the run time object graph using the x:Name / field name directly, rather than having to call FindName explicitly any time you need a reference to a XAML-defined object.

Für eine WPF-Anwendung, die die Microsoft Visual Basic-Ziele verwendet und XAML-Dateien mit Page Build-Aktion enthält, wird während der Kompilierung eine separate Verweis Eigenschaft erstellt, die das WithEvents-Schlüsselwort allen Elementen mit x:Namehinzufügt, um Handles Syntax für Ereignishandlerdelegaten zu unterstützen.For a WPF application that uses the Microsoft Visual Basic targets and includes XAML files with Page build action, a separate reference property is created during compilation that adds the WithEvents keyword to all elements that have an x:Name, to support Handles syntax for event handler delegates. Diese Eigenschaft ist immer öffentlich.This property is always public. Weitere Informationen finden Sie unter Visual Basic- und WPF-Ereignisbehandlung.For more information, see Visual Basic and WPF Event Handling.

x:Name wird vom WPF-XAML-Prozessor zum Registrieren eines Namens bei einem XAML-Namescope zur Ladezeit verwendet. Dies gilt auch für Fälle, in denen die Seite nicht durch Buildaktionen (z. b. lose XAML eines Ressourcen Wörterbuchs) von Markup kompiliert wird.x:Name is used by the WPF XAML processor to register a name into a XAML namescope at load time, even for cases where the page is not markup-compiled by build actions (for example, loose XAML of a resource dictionary). Ein Grund für dieses Verhalten ist, dass die x:Name für ElementName Bindung potenziell benötigt wird.One reason for this behavior is because the x:Name is potentially needed for ElementName binding. Weitere Informationen finden Sie unter Übersicht über die Datenbindung.For details, see Data Binding Overview.

Wie bereits erwähnt, sollten x:Name (oder Name) in Situationen, in denen auch x:Keyverwendet wird, nicht angewendet werden.As mentioned previously, x:Name (or Name) should not be applied in situations that also use x:Key. Der WPFWPF ResourceDictionary weist ein besonderes Verhalten auf, sich selbst als XAML-Namescope zu definieren, jedoch nicht implementierte oder NULL-Werte für INameScope APIs zurückzugeben, um dieses Verhalten zu erzwingen.The WPFWPF ResourceDictionary has a special behavior of defining itself as a XAML namescope but returning Not Implemented or null values for INameScope APIs as a way to enforce this behavior. Wenn der WPF-XAML-Parser auf Name oder x:Name in einem XAML-definierten ResourceDictionarystößt, wird der Name keinem XAML-Namescope hinzugefügt.If the WPF XAML parser encounters Name or x:Name in a XAML-defined ResourceDictionary, the name is not added to any XAML namescope. Wenn Sie versuchen, diesen Namen aus einem XAML-Namescope und den FindName-Methoden zu finden, werden keine gültigen Ergebnisse zurückgegeben.Attempting to find that name from any XAML namescope and the FindName methods will not return valid results.

x:Name und Namex:Name and Name

Viele WPF-Anwendungsszenarien können die Verwendung des x:Name-Attributs vermeiden, da die Name-Abhängigkeits Eigenschaft, wie im XAML-Standard Namespace für mehrere der wichtigen Basisklassen wie FrameworkElement und FrameworkContentElement angegeben, denselben Zweck erfüllt.Many WPF application scenarios can avoid any use of the x:Name attribute, because the Name dependency property as specified in the default XAML namespace for several of the important base classes such as FrameworkElement and FrameworkContentElement satisfies this same purpose. Es gibt noch einige gängige XAML-und WPF-Szenarien, in denen der Code Zugriff auf ein Element ohne Name-Eigenschaft auf Frameworkebene wichtig ist.There are still some common XAML and WPF scenarios where code access to an element with no Name property at the framework level is important. Beispielsweise unterstützen bestimmte Animations-und Storyboard-Unterstützungs Klassen keine Name-Eigenschaft, aber Sie müssen häufig im Code darauf verweisen, um die Animation zu steuern.For example, certain animation and storyboard support classes do not support a Name property, but they often need to be referenced in code in order to control the animation. Sie sollten x:Name als Attribut für Zeitachsen und Transformationen angeben, die in XAML erstellt werden, wenn Sie auf diese später aus Code verweisen möchten.You should specify x:Name as an attribute on timelines and transforms that are created in XAML, if you intend to reference them from code later.

Wenn Name als Eigenschaft für die Klasse verfügbar ist, können Name und x:Name austauschbar als Attribute verwendet werden, aber eine Analyse Ausnahme ergibt sich, wenn beide für das gleiche Element angegeben werden.If Name is available as a property on the class, Name and x:Name can be used interchangeably as attributes, but a parse exception will result if both are specified on the same element. Wenn die XAML-Datei Markup kompiliert ist, tritt die Ausnahme bei der Markup Kompilierung auf; andernfalls tritt sie bei der Auslastung auf.If the XAML is markup compiled, the exception will occur on the markup compile, otherwise it occurs on load.

Name können mithilfe der XAML-Attribut Syntax und in Code, der SetValueverwendet, festgelegt werden. Beachten Sie jedoch, dass das Festlegen der Name-Eigenschaft im Code nicht den repräsentativen Feldverweis innerhalb des XAML-Namescope in den meisten Fällen erstellt, in denen der XAML-Code bereits geladen wurde.Name can be set using XAML attribute syntax, and in code using SetValue; note however that setting the Name property in code does not create the representative field reference within the XAML namescope in most circumstances where the XAML is already loaded. Anstatt zu versuchen, Name im Code festzulegen, verwenden Sie NameScope Methoden aus Code für den entsprechenden Namescope.Instead of attempting to set Name in code, use NameScope methods from code, against the appropriate namescope.

Name können auch mithilfe der Eigenschafts Element Syntax mit innerem Text festgelegt werden, dies ist jedoch nicht üblich.Name can also be set using property element syntax with inner text, but that is uncommon. Im Gegensatz dazu können x:Name in der XAML-Eigenschafts Element Syntax oder in Code, der SetValueverwendet, nicht festgelegt werden. Sie kann nur mithilfe der Attribut Syntax für Objekte festgelegt werden, da Sie eine-Direktive ist.In contrast, x:Name cannot be set in XAML property element syntax, or in code using SetValue; it can only be set using attribute syntax on objects because it is a directive.

Silverlight-VerwendungshinweiseSilverlight Usage Notes

x:Name für Silverlight wird separat dokumentiert.x:Name for Silverlight is documented separately. Weitere Informationen finden Sie unter XAML-Namespace (x:). Sprach Features (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

Siehe auchSee also