x:Name Attribute
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Uniquely identifies object elements for access to the instantiated object 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 Silverlight XamlName grammar. See "Silverlight XamlName Grammar" section. |
Silverlight XamlName Grammar
The following is the normative grammar for a string that is used as a Name / x:Name value in Silverlight.
XamlName ::= NameStartChar (NameChar)*
NameStartChar ::= LetterCharacter | '_'
NameChar ::= NameStartChar | DecimalDigit
LetterCharacter ::= ('a'-'z') | ('A'–'Z')
DecimalDigit ::= '0'-'9'
CombiningCharacter::= none
Characters are restricted to the lower ASCII range, and more specifically to Roman alphabet uppercase and lowercase letters, digits, and the underscore (_) character.
The Unicode character range is not supported.
A name cannot begin with a digit. Some tool implementations prepend an underscore (_) to a string if the user supplies a digit as the initial character.
Remarks
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. In Silverlight, using the managed API, the process of creating this field is performed by the MSBuild target steps, which also are responsible for joining the partial classes for a XAML file and its code-behind. This behavior is not necessarily XAML-language specified; it is the particular implementation that Silverlight applies to use x:Name in its programming and application models.
Each defined x:Name must be unique within a XAML namescope. In many common XAML processing scenarios, the root XAML namescope is defined at the root element level and contains all elements under that element in a single XAML page. Additional XAML namescopes are defined by any template also defined on that page, and also potentially by object trees created through XamlReader.Load. For more information about XAML namescope considerations, see XAML Namescopes.
Many common Silverlight XAML scenarios do not require the x:Name attribute. This is because the Name dependency property satisfies this same purpose, by implementing and integrating x:Name functionality as a Silverlight-specific programming model property. However, there are still some common XAML scenarios where code access to an element with no Name property is necessary, most notably in certain animation and storyboard support classes. For example, you should specify x:Name on timelines and transforms created in XAML if you intend to reference them from code later.
Typically, Silverlight application XAML for a user interface is created by using a design tool such as Microsoft Expression Blend. XAML as created by design tool output typically generates x:Name attributes consistently on elements, even in cases where there would be an equivalent Name property available. Also, design tools often autogenerate x:Name values for elements when they are introduced to the design surface. The autogeneration scheme varies depending on which designer you are using, but a typical scheme is to generate a string that starts with the class name that backs the element, followed by an advancing integer.For example, if you introduce the first Button element to the designer, you might see that in the XAML this element has the x:Name attribute value of Button1.
If Name is available as a property on an element, Name and x:Name can be used interchangeably, but an error results if both attributes are specified on the same element.
The Inline class also has an equivalent Name() property, so that you can name and access inline document elements such as Run.
x:Name cannot be set in XAML property element syntax, or in code using SetValue; it can only be set using XAML attribute syntax on elements. Note also that Name generally should not be set as a property in code at run time, although there are some scenarios that are exceptions to that general rule. In typical scenarios, the creation and definition of XAML namescopes is a XAML processor operation. Modifying Name at run time in Silverlight can result in an inconsistent XAML namescope / private field naming alignment. For more information, see Remarks in Name.
See Also