Dependency property identifier field: NameProperty
The most common usage of this property is to specify the Name attribute for an object in the initially loaded XAML markup for a Silverlight-based application.
The string values used for Name have some restrictions, as imposed by the underlying x:Name defined by the XAML specification. Most notably, a Name must start with a letter or the underscore character (_), and it must contain only letters, digits, or underscores. See XamlName Grammar.
This property provides a convenience property to set (or get in code) the XAML-defined x:Name attribute. x:Name is used by XAML processors when an object tree is constructed from the markup. In the Silverlight and WPF implementations of the XAML processor, when you use the default compile build actions for XAML as a Page in a Silverlight project, this results in an object tree where objects can be directly referenced by name in your page-specific code-behind. In most regards, the x:Name attribute and the Name property are equivalent. You can get Name in code to get the value set as x:Name. x:Name and Name are mutually exclusive as XAML attributes; if you attempt to set both x:Name and Name attributes on the same object element in markup, a parser error is thrown.
.gif) Note: |
|---|
Silverlight XAML will permit Name 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 Silverlight XAML. |
Names must be unique within 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. For more information on these concepts, see XAML Namescopes.
Getting a Name string if you are creating objects in code is not common. If you have the appropriate reference in code already, you can just call methods and properties on the object's field reference, which matches the name.
Scenarios for Name
Setting Name 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. This is done by setting the Storyboard..::.TargetName attached property on any Timeline. The value you set here is the string that you assigned as the Name. For more information, see Animation Overview.
Parts of a control template: In order to support the visual state model and control initialization, control authors should specify Name values for the key parts of a templatable control. For more information, see the "Providing the Control Contract " section of Creating a New Control by Creating a ControlTemplate.
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 happens on another nearby UI element. The easiest way to write code for this situation is to use the field reference generated from a Name.
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.
For more information on XAML namescope concepts, see XAML Namescopes.
You cannot use Name as a direct source value for a CLR property binding source. If you have a requirement to display the same string value as Name in UI with binding, you should replicate the same value to the Tag property, which can be used as a property binding source. You also should not use Name as a binding target.
| Note: |
|---|
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. |
FindName
The utility method FindName, which is available from any FrameworkElement, can find objects by Name in the object tree so long as they are in the current XAML namescope. FindName searches the XAML-created object tree in its entirety, although what it is actually searching is the XAML namescope, which does not preserve the tree metaphor and is instead a hashtable of names. The exception is that anything in a template defined as a resource or otherwise in the page's XAML is by necessity in a separate XAML namescope.
Setting Name
Although it is settable in code, setting a Name in code at run time is generally not recommended. This is because setting a name after the object tree is loaded will not create an equivalent field reference. If a field reference already exists because a Name is provided in the initial markup, and you then change the value of Name, the field and the name you need to use to find the object through FindName are now different because the field remains as the markup-defined name. A scenario where setting Name might be appropriate is if you are creating an object in code through a constructor or other method call and want to provide a name for the object to find it (with FindName) once it is added to the main object tree.
Attempting to set Name to a value that already exists in the XAML namescope causes a run-time exception.
ElementName Binding
The value of Name or x:Name is the means by which you identify the source element for an ElementName binding. Name is more commonly used in this case rather than x:Name, because data binding in general can only target dependency properties on FrameworkElement and derived classes. For more information on the ElementName binding technique, see ElementName.