Article
11/18/2011

XmlReader.ReadSubtree Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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)

Syntax

'Declaration
Public Overridable Function ReadSubtree As XmlReader

public virtual XmlReader ReadSubtree()

Return Value

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

Exceptions

Exception	Condition
InvalidOperationException	The XmlReader is not positioned on an element when this method is called.

Remarks

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 XmlReader has been closed, the original XmlReader will be 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 XmlReader has been closed, the original XmlReader is positioned on the end tag of the book element.

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

Note:
The ReadSubtree method is not intended to create a copy of the XML data that you can work with independently. Rather, it can be used create a boundary around an XML element. This is useful if you need 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 XmlReader returned by the ReadSubtree method to another application, the application can access only that XML element, rather than the entire XML document.

The ReadSubtree method is not intended to create a copy of the XML data that you can work with independently. Rather, it can be used create a boundary around an XML element. This is useful if you need 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 XmlReader returned by the ReadSubtree method to another application, the application can access only that XML element, rather than the entire XML document.

Examples

Dim xmlString As String = _
    "<bookstore>" & _
      "<book genre='novel' ISBN='10-861003-324'>" & _
            "<title>The Handmaid's Tale</title>" & _
            "<price>19.95</price>" & _
        "</book>" & _
        "<book genre='novel' ISBN='1-861001-57-5'>" & _
            "<title>Pride And Prejudice</title>" & _
            "<price>24.95</price>" & _
        "</book>" & _
    "</bookstore>"

' Load the file and ignore all white space.
Dim settings As New XmlReaderSettings()
settings.IgnoreWhitespace = True
Using reader As XmlReader = XmlReader.Create(New StringReader(xmlString), settings)
    ' Position the reader on the second book node
    reader.ReadToFollowing("book")
    reader.Skip()

    ' Create another reader that contains just the second book node.
    Dim inner As XmlReader = reader.ReadSubtree()
    ' Do additional processing on the inner reader. After you 
    ' are done, you can call Close on the inner reader and 
    ' continue processing using the original reader.
End Using


String xmlString =
    @"<bookstore>
  <book genre='novel' ISBN='10-861003-324'>
    <title>The Handmaid's Tale</title>
    <price>19.95</price>
  </book>
  <book genre='novel' ISBN='1-861001-57-5'>
    <title>Pride And Prejudice</title>
    <price>24.95</price>
  </book>
</bookstore>";

// Load the file and ignore all white space.
XmlReaderSettings settings = new XmlReaderSettings();
settings.IgnoreWhitespace = true;
using (XmlReader reader = XmlReader.Create(new StringReader(xmlString), 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();

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

}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.