Share via


x:Key Attribute

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Uniquely identifies elements that are created and referenced as resources, and which exist within a ResourceDictionary.

XAML Attribute Usage

<object.Resources>
  <object x:Key="stringKeyValue".../>
</object.Resources>

XAML Attribute Usage (Custom IDictionary)

<customIDictionary>
  <object x:Key="stringKeyValue".../>
</customIDictionary>

XAML Values

stringKeyValue

A true string used as a key, which must conform to the XamlName grammar. See "Silverlight XamlName Grammar" section.

customIDictionary

Object element for a custom IDictionary implementation marks. See "Custom IDictionaries" section.

Silverlight XamlName Grammar

The following is the normative grammar for a string that is used as a key in Silverlight.

XamlName ::= NameStartChar (NameChar)*
NameStartChar ::= LetterCharacter | '_'
NameChar ::= NameStartChar | DecimalDigit
LetterCharacter ::= ('a'-'z') | ('A'–'Z')
DecimalDigit ::= '0'-'9'
CombiningCharacter::= none
  • Characters are restricted to the lower ASCII range, and more specifically to Roman alphabet uppercase and lowercase letters, digits, and the underscore (_) character.

  • The Unicode character range is not supported.

  • A name cannot begin with a digit. Some tool implementations prepend an underscore (_) to a string if the user supplies a digit as the initial character.

Remarks

Child elements of a ResourceDictionary generally include an x:Key attribute that specifies a unique key value within that dictionary. Key uniqueness is enforced at load time by the Silverlight XAML processor. Non-unique x:Key values will result in parser exceptions/errors. If requested by StaticResource, any nonresolved key will also result in parser errors/exceptions.

x:Key and x:Name are not identical concepts. x:Key is used exclusively in resource dictionaries. x:Name is used for all areas of XAML. A FindName call using a key value will not retrieve a keyed resource. However, Silverlight 5 can use an x:Name (or Name) attribute as the substitute resource key for a resource item if no x:Key exists on the item. This feature exists as a legacy support mechanism for how storyboard resources were originally specified in Silverlight 1.0 XAML syntax.

Note that in the syntax shown, the ResourceDictionary object is implicit in how the XAML processor produces a collection to populate a Resources collection.

The code equivalent of specifying x:Key is any operation that uses a key with the underlying ResourceDictionary. For instance, an x:Key applied in markup for a resource is equivalent to the value of the key parameter of Add when you add the resource to a ResourceDictionary. (x:Key is a XAML language feature, and is not exclusively intended for ResourceDictionary or similar constructs, but that is the prominent application of x:Key in the Silverlight XAML implementation).

Custom IDictionaries

If targeting Silverlight 4 or later, the Silverlight XAML processor supports x:Key as an attribute on any element that defines the content of a custom IDictionary implementation. If targeting Silverlight 3, x:Key is only supported within a ResourceDictionary.

A custom IDictionary implementation is useful for scenarios where you use an IDictionary as a binding source that does not carry the overhead or application model implications of ResourceDictionary, or as a general source for your own resource retrieval or refactoring techniques.

In the XAML syntax shown, the assumption is that the custom IDictionary type supports its indexer as its content property. Otherwise, the indexer property would have to be declared explicitly as a property element.

See Also

Other Resources