Export (0) Print
Expand All
Expand Minimize
0 out of 1 rated this helpful - Rate this topic

XmlReader.ReadSubtree Method

Returns a new XmlReader instance that can be used to read the current node, and all its descendants.

Namespace:  System.Xml
Assembly:  System.Xml (in System.Xml.dll)
public virtual XmlReader ReadSubtree()

Return Value

Type: System.Xml.XmlReader
A new XML reader instance set to ReadState.Initial. Calling the Read method positions the new reader on the node that was current before the call to the ReadSubtree method.
ExceptionCondition
InvalidOperationException

The XML reader isn't positioned on an element when this method is called.

InvalidOperationException

An XmlReader method was called before a previous asynchronous operation finished. In this case, InvalidOperationException is thrown with the message “An asynchronous operation is already in progress.”

ReadSubtree can be called only on element nodes. When the entire sub-tree has been read, calls to the Read method returns false. When the new XML reader has been closed, the original reader is positioned on the EndElement node of the sub-tree. Thus, if you called the ReadSubtree method on the start tag of the book element, after the sub-tree has been read and the new XML reader has been closed, the original XML reader is positioned on the end tag of the book element.

You should not perform any operations on the original reader until the new reader has been closed. This action is not supported and can result in unpredictable behavior.

NoteNote

The ReadSubtree method isn't intended for creating copies of the XML data that you can work with independently. It's designed to create a boundary around an XML element. This is useful if you want to pass data to another component for processing and you wish to limit how much of your data the component can access. When you pass an XML reader returned by the ReadSubtree method to another application, the application can access only that XML element, not the entire XML document.

The following example shows how to use the ReadSubtree method.

XmlReaderSettings settings = new XmlReaderSettings();
settings.IgnoreWhitespace = true;
using (XmlReader reader = XmlReader.Create("books.xml", settings)) {

  // Position the reader on the second book node
  reader.ReadToFollowing("Book");
  reader.Skip();

  // Create another reader that contains just the second book node.
  XmlReader inner = reader.ReadSubtree();

  inner.ReadToDescendant("Title");
  Console.WriteLine(inner.Name);

  // Do additional processing on the inner reader. After you  
  // are done, call Close on the inner reader and  
  // continue processing using the original reader.
  inner.Close(); 

}

Use the following XML data to run the examples in this topic:

<?xml version="1.0" encoding="utf-8" ?>
<Books>
  <Book>
    <Title>A Brief History of Time</Title>
  </Book>
  <Book>
    <Title>Principle Of Relativity</Title>
  </Book>
  <Book>
    <Title>Victory of Reason</Title>
  </Book>
  <Book>
    <Title>The Unicorn that did not Fail</Title>
  </Book>
  <Book>
    <Title>Rational Ontology</Title>
  </Book>
  <Book>
    <Title>The Meaning of Pizza</Title>
  </Book>
</Books>

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone 8, Silverlight 8.1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.