FrameworkElement.Name Property

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. 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 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 occurs on another nearby UI element. The easiest way to write code for this situation is to use the field reference generated from a Name.

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 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 should also 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.

The utility method FindName, which is available from any FrameworkElement, can find objects by Name 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.

You can set the value of Name for an object at run time, but there are some important considerations and limitations that you should be aware of.

Changing the value of Name in code at run time if the object had a previous Name 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 Name is provided in the initial markup, and you change the value of Name, 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 Name 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 Silverlight 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 Name, if you set Name 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 Name 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 Name 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 Name 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.

The value of Name or x:Name is the identifier that you use to identify the source element for an ElementName binding. For more information about the ElementName binding technique, see ElementName or Data Binding.