Microsoft KB Archive/313828

= INFO: Roadmap for Executing XPath Queries in .NET Applications =

Article ID: 313828

Article Last Modified on 8/12/2005

-

APPLIES TO


 * Microsoft .NET Framework 1.0
 * Microsoft .NET Framework 1.1

-



This article was previously published under Q313828



CONTENTS

 * SUMMARY
 * Overview
 * QuickStart Tutorials
 * Programmatically Execute XPath Queries in the .NET Framework
 * Use the XmlDocument Class to Execute XPath Queries
 * More Information About the System.Xml.XPath Namespace
 * Microsoft Knowledge Base Articles
 * Guidelines
 * Troubleshooting
 * REFERENCES



SUMMARY
This article provides a roadmap to introduce the .NET Framework namespaces and classes that you can use to programmatically execute XML Path Language (XPath) queries against Extensible Markup Language (XML) documents and streams in .NET applications. Roadmap articles provide links to useful information, including online documentation, Microsoft Knowledge Base articles, and Microsoft white papers, to help you learn about a Microsoft product or technology.

This article is not an XPath tutorial. This article assumes that you are familiar with the XPath query language and standards.

back to the top

Overview
The XPath query language is commonly used in XML-based applications to query the contents of an XML document. XPath queries are commonly used in Extensible Stylesheets Language Transformations (XSLT) to locate and to apply XSLT templates to specific nodes in an XML document.

XPath queries are also commonly used to locate and to process nodes programmatically in an XML document that match a specified criteria. This article focuses on the programmatic execution of XPath queries in the .NET Framework.

back to the top

QuickStart Tutorials
For more information about how to query with the XPathNavigator and the XpathExpression classes, see the following Microsoft QuickStart tutorials:

How Do I...Navigate XML with the XPathNavigator?

http://samples.gotdotnet.com/quickstart/howto/doc/xml/navigatexmldocument.aspx

How Do I...Query XML with an XPath expression?

http://samples.gotdotnet.com/quickstart/howto/doc/xml/queryxmldocumentxpath.aspx

How Do I...Use an XPathExpression class?

http://samples.gotdotnet.com/quickstart/howto/doc/xml/xpathexpression.aspx

back to the top

Programmatically Execute XPath Queries in the .NET Framework
The .NET Framework includes the following options to programmatically execute XPath queries in the .NET Framework:
 * Use the SelectNodes and the SelectSingleNode methods of the .NET Framework core XML Document Object Model (DOM) parser (which the XmlDocument class implements in the System.Xml namespace). The SelectNodes and the SelectSingleNode methods are extensions of the World Wide Web Consortium (W3C) XML Document Object Model (DOM).
 * Use classes that are optimized for XPath or XSLT processing in the System.Xml.XPath namespace.

back to the top

Use the XmlDocument Class to Execute XPath Queries
The XmlDocument class (which is implemented in the System.Xml namespace) implements the .NET Framework core XML DOM parser. The XML DOM parser complies with the W3C DOM Level 1.0 specifications. Microsoft recommends that you use this parser as the .NET Framework XML parser when you must insert, modify, or delete nodes in an XML document.

The XmlDocument class implements the SelectNodes and the SelectSingleNode methods. You can use these methods to specify and to execute XPath queries against XML data that is loaded into the DOM. For additional information about how to use these methods and to see a relevant code sample), click the article number below to view the article in the Microsoft Knowledge Base:

317018 HOW TO: Use the System.Xml.XmlDocument Class to Execute XPath Queries in Visual Basic .NET

When you execute XPath queries against XML documents or streams that define and use custom namespaces, you must use a System.Xml.XmlNamespaceManager object to provide the required namespace resolution and scope management support. Microsoft Knowledge Base article Q316913 describes how to use an XmlNamespaceManager object to specify namespaces when you execute the SelectNodes method of the XmlDocument class. The same principle applies when you use the SelectSingleNode method. For additional information, click the article number below to view the article in the Microsoft Knowledge Base:

316913 HOW TO: Specify Namespaces When You Use an XmlDocument to Execute XPath Queries in Visual Basic .NET

back to the top

More Information About the System.Xml.XPath Namespace
The System.Xml.XPath namespace contains the .NET Framework XPath parser and evaluation engine. System.Xml.XPath supports the W3C XML Path Language (XPath) Version 1.0 Recommendation.

System.Xml.XPath also contains the following classes, which are optimized to programmatically execute XPath queries and to navigate the generated resultsets:
 * XPathDocument: This class provides a high performance, read-only cache to process XML documents or streams, optimally for XSLT processing and the XPath data model. XPathDocument uses a DOM-based parsing model, in which XPathDocument loads the source XML into an in-memory tree structure. XPathDocument does not implement the interfaces that are required to insert, modify, or delete nodes in an XML document or stream.
 * XPathNavigator: This class is based on the XPath data model. XPathNavigator provides the methods that are required to execute XPath queries against XML data that is loaded into an XPathDocument object. To create an instance of XPathNavigator, use the CreateNavigator method of an XPathDocument object.

You can also use XPathNavigator to compile XPath query expressions that are frequently executed and to generate a System.Xml.XPath.XPathExpression object that encapsulates the compiled query.
 * XPathNodeIterator: This class provides a forward-only, read-only iterator to navigate the resultset that is generated by an XPath query that is executed when you use an XPathNavigator object. To create an instance of XPathNodeIterator, execute the Select method of the XPathNavigator object, where the Select method is the method that you use to execute a specified XPath query.
 * XPathExpression: This class encapsulates a compiled XPath query expression. A compiled XPath expression is an XPath expression whose syntax has been verified to comply with the W3C XPath Query Language specification. Every XPath query expression must be compiled before it is executed. XPathExpression is commonly used to supply a frequently used, precompiled XPath query expression in a call to the Select method of an XPathNavigator object. To create an instance of XPathExpression, execute the Compile method of an XPathNavigator object.
 * XPathException: This class is the .NET Framework exception that is thrown when an error occurs while processing an XPath query expression. To raise XPathException, execute the Select and Compile methods of the XPathNavigator class.

back to the top

Microsoft Knowledge Base Articles
For additional information about how to execute XPath queries by using the classes of the System.Xml.XPath namespace and to see relevant code samples, click the article number below to view the article in the Microsoft Knowledge Base:

317069 HOW TO: Execute XPath Queries by Using the System.Xml.XPath Classes

When you use the classes of the System.Xml.XPath namespace to execute XPath queries against XML documents or streams that define and use custom XML namespaces, you must use a System.Xml.XmlNamespaceManager object to provide the required namespace resolution and scope management support. For additional information about how to use the System.Xml.XmlNamespaceManager object, click the article number below to view the article in the Microsoft Knowledge Base:

308062 HOW TO: Specify Fully Qualified Element Names in XPath Queries by Using Visual Basic .NET

If you write error handling code to catch an XPathException exception when you execute the Select and the Compile methods of the XPathNavigator object, you can more easily identify problems that are caused specifically by the XPath expressions that you use in your code. For additional information about how to write code to catch an XPathException exception, click the article number below to view the article in the Microsoft Knowledge Base:

317108 HOW TO: Use the XPathException Class in Visual Basic .NET

The XPathExpression object exposes the AddSort method, which you can use to sort the results of an XPath query on a specified XML element or attribute. For additional information about how to use this method and to see a relevant code sample, click the article number below to view the article in the Microsoft Knowledge Base:

317084 HOW TO: Use the AddSort Method of the XPathExpression Object in Visual Basic .NET

When you use a string to specify the sort key expression parameter in a call to the AddSort method of the System.Xml.XPath.XPathExpression object, the XML data is not sorted.

316656 BUG: Data Not Sorted When You Use Namespace Prefix in String Passed to XPathExpression.AddSort

back to the top

Guidelines

 * The classes in the System.Xml.XPath namespace are optimized for the XPath data model and XSLT processing. Use these classes instead of the XmlDocument class if you only programmatically execute XPath queries against an XML document or stream. You must use the XmlDocument class to programmatically insert, update, or delete nodes in the XML document or stream and to execute XPath queries against the XML document or stream.
 * Use the Compile method of the XPathNavigator object to generate an XPathExpression object for an XPath query expression that is executed repeatedly. You can then use the generated XPathExpression object in the remaining executions of the query expression.
 * Write error handling code to catch the XPathException exception when you execute the Select and the Compile methods of the XPathNavigator object. This .NET Framework exception class provides detailed information about any XPath query syntax errors that you may experience when you compile a specified query expression.

back to the top

Troubleshooting
If you experience problems or if you have questions, you can refer to the MSDN newsgroups where you can share your experiences with your peers. You can also use the Microsoft Knowledge Base where you can search for articles about specific issues or contact Microsoft Product Support Services.

MSDN Newsgroups

http://msdn.microsoft.com/newsgroups/

Searching the Knowledge Base

http://support.microsoft.com/search

Microsoft Product Support Services

http://support.microsoft.com

back to the top

