FrameworkElement.Name Property
Microsoft Silverlight will reach end of support after October 2021. Learn more.
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.
Namespace: System.Windows
Assembly: System.Windows (in System.Windows.dll)
Syntax
'Declaration
Public Property Name As String
public string Name { get; set; }
<frameworkElement Name="xamlNameString"/>
Property Value
Type: System.String
The name of the object, which must be a string that is valid in the XamlName Grammar. The default is an empty string.
Remarks
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 the Silverlight-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 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 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.
.gif "Note") Note: |
|---|
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 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.
| 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 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. For more information about these concepts, see XAML Namescopes.
.gif "Important note") Important Note: |
|---|
Name should never be localized. Name 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 Name in a UI. |
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. 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.
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 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. |
FindName
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.
Setting Name in Code
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.
ElementName Binding
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.
Version Information
Silverlight
Supported in: 5, 4, 3
Silverlight for Windows Phone
Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0
Platforms
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.
See Also
Reference
InlineName()