Share via


x:Name Attribute

Uniquely identifies object elements for purpose of access to the instantiated element from code-behind or general code. Once applied to a backing programming model, x:Name can be considered equivalent to the variable holding an object reference, as returned by a constructor.

XAML Attribute Usage

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

XAML Values

XAMLNameValue

A string that conforms to the restrictions of the XamlName Grammar.

Remarks

Under the standard build configuration for a WPF application project 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 XAML is processed, and that field holds a reference to the object.

By default, the created field is internal. You can change field access by specifying the x:FieldModifier attribute.

For an application that uses the Microsoft Visual Basic .NET targets and includes XAML files, 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. This property is always public. For details, see Visual Basic and WPF Event Handling.

x:Name must be unique within a name scope. In most common XAML cases, the primary namescope is defined by those elements contained in a single XAML page. Additional discrete namescopes are defined by any template also defined on that page. For more information about namescope considerations, see WPF XAML Namescopes.

x:Name is used by a XAML processor to register a name into a namescope, even for cases where the page is not compiled (for instance, loose XAML). This is because the x:Name is potentially needed for ElementName binding. For details, see Data Binding Overview.

x:Name cannot be applied in certain scopes in WPF programming. For instance, items in a ResourceDictionary cannot have names, because ResourceDictionary has a special behavior of defining itself as a XAML namescope but returning Not Implemented for the key INameScope APIs.

Rules for permittance of x:Name as well as the uniqueness scoping are defined by the underlying Windows Presentation Foundation (WPF) framework implementation that divides various markup elements into separate NameScope ranges, such as resource dictionaries, the logical tree created by the page-level XAML, templates, etc.

Some WPF framework-level applications might be able to avoid any use of the x:Name attribute, because the Name dependency property as specified within the WPF namespace for several of the important base classes such as FrameworkElement/FrameworkContentElement satisfies this same purpose. There are still some common XAML and framework scenarios where code access to an element with no Name property is necessary, most notably in certain animation and storyboard support classes. For instance, you should specify x:Name on timelines and transforms created in XAML, if you intend to reference them from code.

If Name is available as a property on the class, Name and x:Name can be used interchangeably as attributes, but an error will result if both are specified on the same element.

For custom elements, the property (can be either a CLR property or dependency property) that maps to x:Name on any given object can be established or changed by designating that property with the RuntimeNamePropertyAttribute in the property declaration code.

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 namescope in some circumstances. Rather than attempting to set Name in code, use NameScope methods from code, against the appropriate namescope.

Name can also be set using XAML property element syntax with inner text, but that is uncommon. x:Name cannot be set in XAML property element syntax, or in code using SetValue; it can only be set using attribute syntax on elements.

See Also

Concepts

Trees in WPF

Reference

Name

Name