July 28, 2014
Gets or sets the identifying name of the object. When a XAML processor creates the object tree from XAML markup, run-time code can refer to the XAML-declared object by this name.
Assembly: System.Windows (in System.Windows.dll)
XMLNS for XAML: Not mapped to an xmlns.
Dependency property identifier field: NameProperty
The most common usage of this property is to specify the attribute for an object in the initially loaded XAML markup for a Windows Phone application.
The string values used for have some restrictions, as imposed by the underlying x:Name defined by the XAML specification. Most notably, a must start with a letter or the underscore character (_), and it must contain only letters, digits, or underscores.
This property provides a convenience property to set or get the Windows Phone-specific equivalent of the XAML language x:Name attribute. x:Name is used by XAML processors when an object tree is constructed from XAML markup. In the XAML processor, when you use the default compile build actions for XAML as a Page in a Windows Phone project, this creates an object tree that generates field references. The field references enable a programming model whereby objects can be directly referenced by name in your page-specific code-behind.
The build actions that preprocess the XAML prior to loading, in order to construct field references (and also add the event wiring) are sometimes referred to in this documentation as markup compilation.
In most ways, the x:Name attribute and the property are equivalent. You can get in code to get the value set as x:Name. x:Name and are mutually exclusive as XAML attributes; if you attempt to set both x:Name and attributes on the same object element in markup, a parser error is thrown.
XAML will permit as an attribute for any DependencyObject, as opposed to any FrameworkElement as a parsing behavior, but this behavior does not extend into the managed code API, and also may not be fully supported by all tools that can consume or produce XAML.
Names must be unique in a XAML namescope. Generally, the XAML namescope is defined by the XAML page, but certain features such as templates or calls to APIs such as Load can define separate XAML namescopes.
should never be localized. is used as a code variable in code-behind. Such code is typically inaccessible to the localizer who might otherwise have access to XAML files that define the UI, although this depends on your deployment model and localization procedures. This is one reason why you should not display any strings that come from in a UI.
Scenarios for Name
Setting in the XAML that defines UI elements supports several major scenarios:
Animation targeting: To apply an animation to an object property, you must target a specific instance. You do that by setting the Storyboard.TargetName attached property on any Timeline. The value that you set here is the string that you assigned as the .
Parts of a control template: In order to support the visual state model and control initialization, control authors should specify values for the key parts of a templatable control.
General run time interaction: For example, code within an event handler might handle an event on an object that provides the change UI, but the change to properties occurs on another nearby UI element. The easiest way to write code for this situation is to use the field reference generated from a .
Names in XAML for XamlReader.Load
You can specify a Name or x:Name on elements that are part of the input for Load. However, any such name created will be in a discrete XAML namescope, which extends only to the root in the XAML input provided. If you call Load and subsequently add the created objects to the main object tree , this consideration will affect how you call FindName, and from what object scope you should call it.
You cannot use as a direct source value for a CLR property binding source. If you have to display the same string value as in UI with binding, you should replicate the same value to the Tag property, which can be used as a property binding source. You should also not use as a binding target.
You can use Name as the source qualifier for an ElementName binding, but that is a different concept than the restriction on using the string value of Name as a direct source.
The utility method FindName, which is available from any FrameworkElement, can find objects by in the object tree as long as they are in the current XAML namescope. FindName searches the XAML-created object tree in its entirety. Technically, what FindName is actually searching is the XAML namescope, which does not preserve the tree metaphor and is instead represented as a hash table of names. FindName cannot find names that are defined in applied templates.
Setting Name in Code
You can set the value of for an object at run time, but there are some important considerations and limitations that you should be aware of.
Changing the value of in code at run time if the object had a previous value set in XAML is generally not recommended. This is because setting a name after the object tree is loaded will not create or change the identifying name of the equivalent field reference. If a field reference already exists because a is provided in the initial markup, and you change the value of , the field and the name that you need to use to find the object through FindName are now different because the field remains as the markup-defined name.
Setting a value for an object that was created in code and therefore never had a XAML-defined Name value is appropriate for certain scenarios. One such scenario is if you want to be able to find either XAML-created or code-created objects in the tree by using FindName as the common utility function. In order to make that scenario work, Windows Phone continues to use and add to the XAML namescope concept at run time. If you are attempting to add new named objects to an existing largely XAML-created object tree, names must be unique, otherwise a duplicate name exception occurs. The duplicate name exception might not occur on the attempt to set , if you set on an object you just instantiated. Until you attempt to add the duplicate-named object to the main object tree, the new object has its own self-contained XAML namescope. It is only at the moment that you connect the object to a larger object tree that the duplicate name in XAML namescope condition can be detected. The exception might occur on the operation that connected objects in the tree, for example on a call to the Add method of a collection that connects to the main object tree. It can be difficult to know which values already exist in the XAML namescope that you will later add the new object to. There is no specific API that reports the full hashtable of existing names in a XAML namescope. If you set values in code extensively, you might need a technique for generating name strings that are unique to your run time usage, or you might need to wrap calls that add newly named objects in a try-catch block to catch the exceptions that could result from a duplicate name.
Note that you can only set at run time for objects that are a FrameworkElement or an Inline. If an object does not have a Name property, and setting the name in XAML would have required using the x:Name attribute rather than Name, there is no run-time API available for setting such an object's run-time name.