<xsl:key> Element

MSXML 5.0 SDK

Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - XSLT Reference

<xsl:key> Element

The <xsl:key> element declares a named key—that is, a name-value pair assigned to a specified element in an XML document. The key is used with the key() function in XPath expressions to help you access the assigned elements in a complex XML document efficiently.

<xsl:key
  name = QName
  match = Pattern
  use = Expression>
</xsl:key>

Attributes

name
Specifies the name of the key.
match
Specifies the pattern that identifies a node that holds this key.
use
Specifies what is to be used as the value of the key. The key value can be one of the following: an attribute, a child element, or the content of the matched element.

Element Information

Number of occurrences Unlimited
Parent elements xsl:stylesheet
Child elements (No child elements)

Remarks

You can use keys as generalized IDs for referencing elements in an XML document. To do this, first use <xsl:key> to declare a key for a node. Then call the key() function to retrieve the node, supplying the name and value of the key as the function arguments,. For more information, see the example below.

Multiple keys can be declared on a node. This provides multiple ways to query a node.

When you work with relatively large XML documents, a key is often a fast wayto query elements. This is because it essentially indexes the locations of the desired nodes ahead of time. However, when <xsl:key> elements are compiled, the XSLT processor will not create such indexes unless a key() function is called against the keys. This ensures that the time-intensive indexing operation is performed only when it is necessary.

In a stylesheet, <xsl:key> elements are top-level elements, and cannot appear within a template. To avoid circular references, you cannot use parameter or variable references as part of an <xsl:key> match.

Example

The following topic provides an example of the <xsl:key> element.