| 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.