---
title: "x:Name Directive"
ms.date: "03/30/2017"
f1_keywords:
- "x:Name"
- "xName"
- "Name"
helpviewer_keywords:
- "x:Name attribute [XAML Services]"
- "XAML [XAML Services], x:Name attribute"
- "Name attribute in XAML [XAML Services]"
ms.assetid: b7e61222-e8cf-48d2-acd0-6df3b7685d48
---
# x:Name Directive
Uniquely identifies XAML-defined elements in a XAML namescope. XAML namescopes and their uniqueness models can be applied to the instantiated objects, when frameworks provide APIs or implement behaviors that access the XAML-created object graph at run time.
## XAML Attribute Usage
```xaml
```
## XAML Values
|||
|-|-|
|`XAMLNameValue`|A string that conforms to the restrictions of the [XamlName Grammar](xamlname-grammar.md).|
## Remarks
After `x:Name` is applied to a framework's backing programming model, the name is equivalent to the variable that holds an object reference or an instance as returned by a constructor.
The value of an `x:Name` directive usage must be unique within a XAML namescope. By default when used by .NET XAML Services API, the primary XAML namescope is defined at the XAML root element of a single XAML production, and encompasses the elements that are contained in that XAML production. Additional discrete XAML namescopes that might occur within a single XAML production can be defined by frameworks to address specific scenarios. For example, in WPF, new XAML namescopes are defined and created by any template that is also defined on that XAML production. For more information about XAML namescopes (written for WPF but relevant for many XAML namescope concepts), see [WPF XAML Namescopes](../framework/wpf/advanced/wpf-xaml-namescopes.md).
In general, `x:Name` should not be applied in situations that also use `x:Key`. XAML implementations by specific existing frameworks have introduced substitution concepts between `x:Key` and `x:Name`, but that is not a recommended practice. .NET XAML Services does not support such substitution concepts when handling name/key information such as or .
Rules for permittance of `x:Name` as well as the name uniqueness enforcement are potentially defined by specific implementing frameworks. However, to be usable with .NET XAML Services, the framework definitions of XAML namescope uniqueness should be consistent with the definition of information in this documentation, and should use the same rules regarding where the information is applied. For example, the [!INCLUDE[TLA#tla_winclient](../includes/tlasharptla-winclient-md.md)] implementation divides various markup elements into separate ranges, such as resource dictionaries, the logical tree created by the page-level XAML, templates, and other deferred content, and then enforces XAML name uniqueness within each of those XAML namescopes.
For custom types that use .NET XAML Services XAML object writers, a property that maps to `x:Name` on a type can be established or changed. You define this behavior by referencing the name of the property to map with the in the type definition code. is a type-level attribute.
Using.NET XAML Services, the backing logic for XAML namescope support can be defined in a framework-neutral way by implementing the interface.
## WPF Usage Notes
Under the standard build configuration for a [!INCLUDE[TLA2#tla_winclient](../includes/tla2sharptla-winclient-md.md)] application that uses XAML, partial classes, and code-behind, the specified `x:Name` becomes the name of a field that is created in the underlying code when [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] is processed by a markup compilation build task, and that field holds a reference to the object. By default, the created field is internal. You can change field access by specifying the [x:FieldModifier attribute](xfieldmodifier-directive.md). In WPF and Silverlight, the sequence is that the markup compile defines and names the field in a partial class, but the value is initially empty. Then, a generated method named `InitializeComponent` is called from within the class constructor. `InitializeComponent` consists of `FindName` calls using each of the `x:Name` values that exist in the XAML-defined part of the partial class as input strings. The return values are then assigned to the like-named field reference to fill the field values with objects that were created from XAML parsing. The execution of `InitializeComponent` make it possible to reference the run time object graph using the `x:Name` / field name directly, rather than having to call `FindName` explicitly any time you need a reference to a XAML-defined object.
For a WPF application that uses the Microsoft Visual Basic targets and includes XAML files with `Page` build action, a separate reference property is created during compilation that adds the `WithEvents` keyword to all elements that have an `x:Name`, to support `Handles` syntax for event handler delegates. This property is always public. For more information, see [Visual Basic and WPF Event Handling](../framework/wpf/advanced/visual-basic-and-wpf-event-handling.md).
`x:Name` is used by the WPF XAML processor to register a name into a XAML namescope at load time, even for cases where the page is not markup-compiled by build actions (for example, loose XAML of a resource dictionary). One reason for this behavior is because the `x:Name` is potentially needed for binding. For details, see [Data Binding Overview](../net/wpf/data/data-binding-overview.md).
As mentioned previously, `x:Name` (or `Name`) should not be applied in situations that also use `x:Key`. The [!INCLUDE[TLA2#tla_winclient](../includes/tla2sharptla-winclient-md.md)] has a special behavior of defining itself as a XAML namescope but returning Not Implemented or null values for APIs as a way to enforce this behavior. If the WPF XAML parser encounters `Name` or `x:Name` in a XAML-defined , the name is not added to any XAML namescope. Attempting to find that name from any XAML namescope and the `FindName` methods will not return valid results.
### x:Name and Name
Many WPF application scenarios can avoid any use of the `x:Name` attribute, because the `Name` dependency property as specified in the default XAML namespace for several of the important base classes such as and satisfies this same purpose. There are still some common XAML and WPF scenarios where code access to an element with no `Name` property at the framework level is important. For example, certain animation and storyboard support classes do not support a `Name` property, but they often need to be referenced in code in order to control the animation. You should specify `x:Name` as an attribute on timelines and transforms that are created in XAML, if you intend to reference them from code later.
If is available as a property on the class, and `x:Name` can be used interchangeably as attributes, but a parse exception will result if both are specified on the same element. If the XAML is markup compiled, the exception will occur on the markup compile, otherwise it occurs on load.
can be set using XAML attribute syntax, and in code using ; note however that setting the property in code does not create the representative field reference within the XAML namescope in most circumstances where the XAML is already loaded. Instead of attempting to set in code, use methods from code, against the appropriate namescope.
can also be set using property element syntax with inner text, but that is uncommon. In contrast, `x:Name` cannot be set in XAML property element syntax, or in code using ; it can only be set using attribute syntax on objects because it is a directive.
## Silverlight Usage Notes
`x:Name` for Silverlight is documented separately. For more information, see [XAML Namespace (x:) Language Features (Silverlight)](https://docs.microsoft.com/previous-versions/windows/silverlight/dotnet-windows-silverlight/cc188995(v=vs.95)).
## See also
-
-
- [Trees in WPF](../framework/wpf/advanced/trees-in-wpf.md)