Skip to main content
 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Gets or sets the identifying name of the element. The name provides a reference so that code-behind, such as event handler code, can refer to a markup element after it is constructed during processing by a XAML processor.

Namespace:   System.Windows
Assembly:  PresentationFramework (in PresentationFramework.dll)

[LocalizabilityAttribute(LocalizationCategory.NeverLocalize)]
public string Name { get; set; }
public:
[LocalizabilityAttribute(LocalizationCategory::NeverLocalize)]
property String^ Name {
	virtual String^ get() sealed;
	virtual void set(String^ value) sealed;
}
[<LocalizabilityAttribute(LocalizationCategory.NeverLocalize)>]
abstract Name : string with get, set
[<LocalizabilityAttribute(LocalizationCategory.NeverLocalize)>]
override Name : string with get, set
<LocalizabilityAttribute(LocalizationCategory.NeverLocalize)>
Public Property Name As String

Property Value

Type:

The name of the element. The default is an empty string.

Implements

The most common usage of this property is to specify a XAML element name as an attribute in markup.

This property essentially provides a WPF framework-level convenience property to set the XAML  x:Name Directive.

Names must be unique within a namescope. For more information, see WPF XAML Namescopes.

Getting a if you are creating elements in code is not common. If you have the appropriate reference in code already, you can just call methods and properties on the element reference and will not generally need the . An exception to this is if the string has some overloaded meaning, for instance if it is useful to display that name in UI. Setting a from code-behind if the original was set from markup is also not recommended, and changing the property after loading the XAML will not change the original object reference. The object references are created only when the underlying namescopes are explicitly created during parsing. You must specifically call RegisterName to make an effective change to the property of an already loaded element.

One notable case where setting from code is important is when registering names for elements that storyboards will run against, so that they can be referenced at run time. Before you can register a name, might also need to instantiate and assign a NameScope instance. See the Example section, or Storyboards Overview.

Setting from code has limited applications, but getting an element by is more common. One particular scenario is if your application supports a navigation model where pages reload into the application, and the run time code is not necessarily code-behind defined for that page. The utility method FindName, which is available from any FrameworkElement, can find any element by in the logical tree for that element, searching the tree recursively as necessary. Or you can use the FindLogicalNode static method of LogicalTreeHelper, which also takes a string as an argument.

Typically used root elements ( Window, Page for example) implement the interface INameScope. Implementations of this interface are expected to enforce that names be unambiguous within their scope. The root elements that define this interface also define the namescope behavior boundaries for all the related APIs.

The property also serves as an identifier for other processes. For instance, the WPF automation model will use as the AutomationId for clients and providers.

The string values used for have some restrictions, as imposed by the underlying x:Name Directive defined by the XAML specification. Most notably, a must start with a letter or the underscore character (_), and must contain only letters, digits, or underscores. For more information, see WPF XAML Namescopes.

is one of the very few dependency properties that cannot be animated ( is true in metadata), because the name itself is vital for targeting an animation. Data binding a is technically possible, but is an extremely uncommon scenario because a data-bound cannot serve the main intended purpose of the property: to provide an identifier connection point for code-behind.

Identifier field

NameProperty

Metadata properties set to true

The following example sets the property in code, and then registers the name into the newly created NameScope by calling RegisterName. The technique illustrated here is a requirement for animating with storyboards, because storyboards require targeting by the , and cannot be targeted by object reference.

//  
// Create a Rectangle
//
Rectangle myRectangle = new Rectangle();
myRectangle.Width = 200;
myRectangle.Height = 200;
myRectangle.Name = "myRectangle";
this.RegisterName(myRectangle.Name, myRectangle); 
'  
' Create a Rectangle
'
Dim myRectangle As New Rectangle()
myRectangle.Width = 200
myRectangle.Height = 200
myRectangle.Name = "myRectangle"
Me.RegisterName(myRectangle.Name, myRectangle)
.NET Framework
Available since 3.0
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Return to top