XmlReader.ReadSubtree XmlReader.ReadSubtree XmlReader.ReadSubtree XmlReader.ReadSubtree Method

定義

現在のノードおよびそのすべての子孫ノードを読み取るために使用できる、新しい XmlReader インスタンスを返します。Returns a new XmlReader instance that can be used to read the current node, and all its descendants.

public:
 virtual System::Xml::XmlReader ^ ReadSubtree();
public virtual System.Xml.XmlReader ReadSubtree ();
abstract member ReadSubtree : unit -> System.Xml.XmlReader
override this.ReadSubtree : unit -> System.Xml.XmlReader
Public Overridable Function ReadSubtree () As XmlReader

戻り値

Initial に設定された新しい XML リーダーのインスタンス。A new XML reader instance set to Initial. Read() メソッドを呼び出すと、ReadSubtree() メソッドを呼び出す前に処理対象だったノードに新しいリーダーが配置されます。Calling the Read() method positions the new reader on the node that was current before the call to the ReadSubtree() method.

例外

このメソッドを呼び出すときに XML リーダーが要素に配置されていません。The XML reader isn't positioned on an element when this method is called.

- または --or-

先行の非同期操作が完了する前に、XmlReader メソッドが呼び出されました。An XmlReader method was called before a previous asynchronous operation finished. この場合、「非同期操作が既に実行されています」というメッセージと共に InvalidOperationException がスローされます。In this case, InvalidOperationException is thrown with the message "An asynchronous operation is already in progress."

ReadSubtree メソッドを使用する方法の例を次に示します。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(); 

}
Dim settings As New XmlReaderSettings()
settings.IgnoreWhitespace = True
Using reader As XmlReader = 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.
  Dim inner As XmlReader = 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()

End Using

このトピックの例を実行するには、次の XML データを使用します。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>  
  

注釈

ReadSubtree要素ノードでのみ呼び出すことができます。ReadSubtree can be called only on element nodes. サブツリー全体が読み込まれると、メソッドのRead呼び出しはを返しfalseます。When the entire sub-tree has been read, calls to the Read method returns false. 新しい XML リーダーが閉じられると、元のリーダーはサブツリーのEndElementノードに配置されます。When the new XML reader has been closed, the original reader is positioned on the EndElement node of the sub-tree. したがって、book 要素のReadSubtree開始タグに対してメソッドを呼び出した場合、サブツリーが読み取られ、新しい xml リーダーが閉じられると、元の xml リーダーは book 要素の終了タグに配置されます。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.

注意

メソッドReadSubtreeは、個別に操作できる XML データのコピーを作成するためのものではありません。The ReadSubtree method isn't intended for creating copies of the XML data that you can work with independently. XML 要素の周囲に境界線を作成するように設計されています。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. ReadSubtreeメソッドによって返された xml リーダーを別のアプリケーションに渡すと、アプリケーションは xml ドキュメント全体ではなく、その xml 要素にのみアクセスできます。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.

適用対象