System.Xml.XPath.XPathExpression Class

Assembly: System.Xml.dll
Namespace: System.Xml.XPath
Summary
Encapsulates a compiled XPath expression. This class is returned as a result of a call to XPathNavigator.Compile and is used by the XPathNavigator.Select, XPathNavigator.Evaluate and XPathNavigator.Matches methods.
C# Syntax:
public abstract class XPathExpression
See also:
System.Xml.XPath Namespace

System.Xml.XPath.XPathExpression Member List:

Public Properties
Expression Read-only

Gets a string representation of the XPathExpression. When overridden in a derived class, gets a string representation of the XPathExpression.
ReturnType Read-only

Gets the result type of the XPathExpression as defined by the W3C XPath specification.
Public Methods
AddSort Overloaded:
AddSort(object expr, IComparer comparer)

 Sorts the nodes selected by the XPathExpression, according to the IComparer interface.
AddSort Overloaded:
AddSort(object expr, XmlSortOrder order, XmlCaseOrder caseOrder, string lang, XmlDataType dataType)

 Sorts the nodes selected by the XPathExpression according to the supplied parameters.
Clone Clones the XPathExpression.
Equals
(inherited from System.Object)		 See base class member description: System.Object.Equals

Derived from System.Object, the primary base class for all objects.
GetHashCode
(inherited from System.Object)		 See base class member description: System.Object.GetHashCode

Derived from System.Object, the primary base class for all objects.
GetType
(inherited from System.Object)		 See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
SetContext Specifies the XmlNamespaceManager to use for resolving namespaces.
ToString
(inherited from System.Object)		 See base class member description: System.Object.ToString

Derived from System.Object, the primary base class for all objects.
Protected Methods
Finalize
(inherited from System.Object)		 See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
MemberwiseClone
(inherited from System.Object)		 See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:

System.Xml.XPath.XPathExpression Member Details

Property: Expression (read-only)
Summary
Gets a string representation of the XPathExpression.
C# Syntax:
public abstract string Expression {get;}
Remarks
This could be used for diagnostic purposes or as input to another expression.

Return to top

Property: ReturnType (read-only)
Summary
Gets the result type of the XPathExpression as defined by the W3C XPath specification.
C# Syntax:
public abstract XPathResultType ReturnType {get;}
Example
The following example shows how to use the XPath return type to determine how to process the XPath expression.
 XPathDocument doc = new XPathDocument("books.xml");
 XPathNavigator nav = doc.CreateNavigator();

 XPathExpression expr1 = nav.Compile(".//price/text()*10"); // Returns a number.
 XPathExpression expr2 = nav.Compile("bookstore/book/price"); // Returns a nodeset.

 Evaluate(expr1, nav);
 Evaluate(expr2, nav);

 }

 public static void Evaluate(XPathExpression expr, XPathNavigator nav){
 
 switch(expr.ReturnType)
 {
 case XPathResultType.Number:
     Console.WriteLine(nav.Evaluate(expr));
     break;
 
 case XPathResultType.NodeSet:
     XPathNodeIterator i = nav.Select(expr);
     while (i.MoveNext()){
        Console.WriteLine(i.Current.ToString());
     }
     break;    
 
 case XPathResultType.Boolean:
     if ((bool)nav.Evaluate(expr))
        Console.WriteLine("True!");
     break;
 
 case XPathResultType.String:
     Console.WriteLine(nav.Evaluate(expr));
     break;
 
 }

 }
See also:
XPathNavigator.Evaluate

Return to top

Overloaded Method: AddSort(
   object expr,
   IComparer comparer
)
Summary
Sorts the nodes selected by the XPathExpression, according to the IComparer interface.
C# Syntax:
public abstract void AddSort(
   object expr,
   IComparer comparer
);
Parameters:

expr

An expression representing the sort key. This can be a string or an XPathExpression object. The result of this expression is converted to a string, according to the XPath specification, for comparison. In an XSLT stylesheet, if xsl:sort is used, but no select expression is specified, then string(.) is used by default. An expression representing the sort key. This can be a string or an XPathExpression object. The result of this expression is converted to a string, according to the XPath specification, for comparison. In an XSLT stylesheet, if xsl:sort is used, but no select expression is specified, then string(.) is used by default.

comparer

A class derived from the IComparer interface to use for the data type comparison.

Exceptions
Exception Type Condition
XPathException The XPathExpression or sort key includes a prefix and either an XmlNamepsaceManager is not provided, or the prefix cannot be found in the supplied XmlNamepsaceManager.
Remarks
This method enables users to sort objects by their data type rather than by string or number. The IComparer interface provides an implementation of the IComparer.Compare method that supports sorting on user defined classes.

In the following example, the books are sorted by ISBN number, where isbn is an object that implements the IComparer interface.

              XPathExpression expr = nav.Compile("bookstore/book");
              ISBN isbn = new ISBN();
              expr.AddSort("@ISBN", (IComparer)isbn);

The order in which the sorts are added provides the sort key order.

If the XPathExpression or the sort key requires namespace resolution, you must use the XPathExpression.SetContext method to provide an XmlNamespaceManager for namespace resolution.



Note If the XPathExpression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the SetContext method and provide an XmlNamespaceManager containing a prefix and namespace URI to handle the default namespace.

Return to top

Overloaded Method: AddSort(
   object expr,
   XmlSortOrder order,
   XmlCaseOrder caseOrder,
   string lang,
   XmlDataType dataType
)
Summary
Sorts the nodes selected by the XPathExpression according to the supplied parameters.
C# Syntax:
public abstract void AddSort(
   object expr,
   XmlSortOrder order,
   XmlCaseOrder caseOrder,
   string lang,
   XmlDataType dataType
);
Parameters:

expr

An expression representing the sort key. This can be a string or an XPathExpression object. The result of this expression is converted to a string, according to the XPath specification, for comparison. In an XSLT stylesheet, if xsl:sort is used, but no select expression is specified, then string(.) is used by default. An expression representing the sort key. This can be a string or an XPathExpression object. The result of this expression is converted to a string, according to the XPath specification, for comparison. In an XSLT stylesheet, if xsl:sort is used, but no select expression is specified, then string(.) is used by default.

order

A XmlSortOrder value indicating the sort order.

caseOrder

A XmlCaseOrder value indicating how to sort upper/lower case letters. This is language dependent, providing a lang parameter is supplied.

lang

The language to use for comparison. Uses the CultureInfo class that can be passed to the String.Compare method for the language types, for example, "us-en" for US English. If an empty string is specified, the system environment is used to determine the CultureInfo. The language to use for comparison. Uses the CultureInfo class that can be passed to the String.Compare method for the language types, for example, "us-en" for US English. If an empty string is specified, the system environment is used to determine the CultureInfo.

dataType

XmlDataType indicating sort order for data type.

Exceptions
Exception Type Condition
XPathException The XPathExpression or sort key includes a prefix and either an XmlNamepsaceManager is not provided, or the prefix cannot be found in the supplied XmlNamepsaceManager.
Remarks
The order in which the sorts are added provides the sort key order.

If you had the following XML 

              <bookstore>
               <book>
               <price>19.95</price>
               </book>
               ///more books
              </bookstore>

The following C# code processes the nodes in reverse document order and sorts the book prices numerically.

              XPathExpression expr = nav.Compile("bookstore/book/price");
              expr.AddSort("text()", XmlSortOrder.Descending, XmlCaseOrder.None, "", XmlDataType.Number);

If the XPathExpression or the sort key requires namespace resolution, you must use the XPathExpression.SetContext method to provide an XmlNamespaceManager for namespace resolution.



Note If the XPathExpression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the SetContext method and provide an XmlNamespaceManager containing a prefix and namespace URI to handle the default namespace.

For example, if you had the following XML: 

              <bookstore xmlns="http://www.lucernepublishing.com">
               <book>
               <title>Pride And Prejudice</title>
               </book>
              </bookstore>

The following C# code selects all book nodes: 

              XmlNamespaceManager nsmgr = new XmlNamespaceManager(nav.NameTable);
              nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com");
              XPathExpression expr;
              expr = nav.Compile("//ab:book");
              expr.SetContext(nsmgr);
              XPathNodeIterator iterator = nav.Select(expr);
Example
The following example selects all books authored by Jane Austen and sorts them by title.
using System;
using System.IO;
using System.Xml;
using System.Xml.XPath;

public class Sample
{
  public static void Main()
  {

      XPathDocument doc = new XPathDocument("booksort.xml");
      XPathNavigator nav = doc.CreateNavigator();

      //Select all books by Jane Austen.
      XPathExpression expr; 
      expr = nav.Compile("descendant::book[author/last-name='Austen']");

      //Sort the selected books by title.
      expr.AddSort("title", XmlSortOrder.Ascending, XmlCaseOrder.None, "", XmlDataType.Text);

      //Display the selection.
      XPathNodeIterator iterator = nav.Select(expr);
      while (iterator.MoveNext()){
        XPathNavigator nav2 = iterator.Current.Clone();
        nav2.MoveToFirstChild();
        Console.WriteLine("Book title:  {0}", nav2.Value);
      }
   }

}

The sample uses the following input file:

booksort.xml


<?xml version="1.0"?>
<!-- a fragment of a book store inventory database -->
<bookstore xmlns:bk="urn:samples">
  <book genre="novel" publicationdate="1997" bk:ISBN="1-861001-57-8">
    <title>Pride And Prejudice</title>
    <author>
      <first-name>Jane</first-name>
      <last-name>Austen</last-name>
    </author>
    <price>24.95</price>
  </book>
  <book genre="novel" publicationdate="1992" bk:ISBN="1-861002-30-1">
    <title>The Handmaid's Tale</title>
    <author>
      <first-name>Margaret</first-name>
      <last-name>Atwood</last-name>
    </author>
    <price>29.95</price>
  </book>
  <book genre="novel" publicationdate="1991" bk:ISBN="1-861001-57-6">
    <title>Emma</title>
    <author>
      <first-name>Jane</first-name>
      <last-name>Austen</last-name>
    </author>
    <price>19.95</price>
  </book>
  <book genre="novel" publicationdate="1982" bk:ISBN="1-861001-45-3">
    <title>Sense and Sensibility</title>
    <author>
      <first-name>Jane</first-name>
      <last-name>Austen</last-name>
    </author>
    <price>19.95</price>
  </book>
</bookstore>

Return to top

Method: Clone()
Summary
Clones the XPathExpression.
C# Syntax:
public abstract XPathExpression Clone();
Return Value:
A new XPathExpression object.

Return to top

Method: Equals(
   object obj
)
Inherited
See base class member description: System.Object.Equals
C# Syntax:
public virtual bool Equals(
   object obj
);

For more information on members inherited from System.Object click on the link above.

Return to top

Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~XPathExpression();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: GetHashCode()
Inherited
See base class member description: System.Object.GetHashCode
C# Syntax:
public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: SetContext(
   XmlNamespaceManager nsManager
)
Summary
Specifies the XmlNamespaceManager to use for resolving namespaces.
C# Syntax:
public abstract void SetContext(
   XmlNamespaceManager nsManager
);
Parameters:

nsManager

The XmlNamespaceManager object used for resolving namespaces.

Exceptions
Exception Type Condition
XPathException The nsManager is not derived from XmlNamespaceManager.
Remarks
Namespace resolution is supported using the XmlNamespaceManager which stores prefix and namespace URI mappings. If the XPathExpression requires namespace resolution, the prefix and namespace URI pair must be added to the XmlNamespaceManager, and the SetContext method must be called to specify the XmlNamespaceManager to use for namespace resolution.

Note If the XPathExpression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the SetContext method and provide an XmlNamespaceManager containing a prefix and namespace URI to handle the default namespace. For example, if you had the following XML: 
              <bookstore xmlns="http://www.lucernepublishing.com">
               <book>
               <title>Pride And Prejudice</title>
               </book>
              </bookstore>
The following C# code selects all book nodes: 
              XmlNamespaceManager nsmgr = new XmlNamespaceManager(nav.NameTable);
              nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com");
              XPathExpression expr;
              expr = nav.Compile("//ab:book");
              expr.SetContext(nsmgr);
              XPathNodeIterator iterator = nav.Select(expr);
Example
The following example displays all the ISBN attributes.
using System;
using System.IO;
using System.Xml;
using System.Xml.XPath;

public class Sample
{
  public static void Main()
  {

      XPathDocument doc = new XPathDocument("booksort.xml");
      XPathNavigator nav = doc.CreateNavigator();

      //Select all ISBN attributes.
      XPathExpression expr; 
      expr = nav.Compile("/bookstore/book/@bk:ISBN");
 
      XmlNamespaceManager nsmgr = new XmlNamespaceManager(nav.NameTable);
      nsmgr.AddNamespace("bk", "urn:samples");
      expr.SetContext(nsmgr);

      //Display the selection.
      XPathNodeIterator iterator = nav.Select(expr);
      while (iterator.MoveNext()){
        Console.WriteLine(iterator.Current.ToString());
      }
   }

}

The sample uses the following input file:

booksort.xml


<?xml version="1.0"?>
<!-- a fragment of a book store inventory database -->
<bookstore xmlns:bk="urn:samples">
  <book genre="novel" publicationdate="1997" bk:ISBN="1-861001-57-8">
    <title>Pride And Prejudice</title>
    <author>
      <first-name>Jane</first-name>
      <last-name>Austen</last-name>
    </author>
    <price>24.95</price>
  </book>
  <book genre="novel" publicationdate="1992" bk:ISBN="1-861002-30-1">
    <title>The Handmaid's Tale</title>
    <author>
      <first-name>Margaret</first-name>
      <last-name>Atwood</last-name>
    </author>
    <price>29.95</price>
  </book>
  <book genre="novel" publicationdate="1991" bk:ISBN="1-861001-57-6">
    <title>Emma</title>
    <author>
      <first-name>Jane</first-name>
      <last-name>Austen</last-name>
    </author>
    <price>19.95</price>
  </book>
  <book genre="novel" publicationdate="1982" bk:ISBN="1-861001-45-3">
    <title>Sense and Sensibility</title>
    <author>
      <first-name>Jane</first-name>
      <last-name>Austen</last-name>
    </author>
    <price>19.95</price>
  </book>
</bookstore>
See also:
XmlNamespaceManager

Return to top

Method: ToString()
Inherited
See base class member description: System.Object.ToString
C# Syntax:
public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.