XmlReader.ReadSubtree Metoda

Definicja

Zwraca nowe wystąpienie XmlReader, za pomocą którego można odczytać bieżący węzeł oraz wszystkie jego obiekty podrzędne.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

Zwraca

Nowe wystąpienie czytnika XML ustawione na Initial.A new XML reader instance set to Initial. Wywołanie metody Read() powoduje umieszczenie nowego czytnika w węźle, który był bieżący przed wywołaniem metody ReadSubtree().Calling the Read() method positions the new reader on the node that was current before the call to the ReadSubtree() method.

Wyjątki

Czytnik XML nie jest umieszczany w elemencie, gdy ta metoda jest wywoływana.The XML reader isn't positioned on an element when this method is called.

lub-or-

Metoda XmlReader została wywołana przed ukończeniem poprzedniej operacji asynchronicznej.An XmlReader method was called before a previous asynchronous operation finished. W takim przypadku InvalidOperationException jest generowany z komunikatem "asynchroniczna operacja jest już w toku".In this case, InvalidOperationException is thrown with the message "An asynchronous operation is already in progress."

Przykłady

Poniższy przykład pokazuje, jak używać metody 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

Użyj następujących danych XML, aby uruchomić przykłady w tym temacie: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>  
  

Uwagi

ReadSubtree można wywołać tylko w węzłach elementów.ReadSubtree can be called only on element nodes. Gdy odczytano całe drzewo podrzędne, wywołania metody Read zwracają false.When the entire sub-tree has been read, calls to the Read method returns false. Gdy nowy czytelnik XML został zamknięty, oryginalny czytnik zostanie umieszczony w węźle EndElement poddrzewa.When the new XML reader has been closed, the original reader is positioned on the EndElement node of the sub-tree. W związku z tym, jeśli wywołano metodę ReadSubtree w tagu początkowym elementu Book, po odczytaniu poddrzewa, a nowy czytelnik XML został zamknięty, oryginalny czytelnik XML zostanie umieszczony na tagu końcowym elementu książki.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.

Nie należy wykonywać żadnych operacji na oryginalnym czytniku do momentu zamknięcia nowego czytnika.You should not perform any operations on the original reader until the new reader has been closed. Ta akcja nie jest obsługiwana i może spowodować nieprzewidywalne zachowanie.This action is not supported and can result in unpredictable behavior.

Uwaga

Metoda ReadSubtree nie jest przeznaczona do tworzenia kopii danych XML, z którymi można korzystać niezależnie.The ReadSubtree method isn't intended for creating copies of the XML data that you can work with independently. Zaprojektowano w celu utworzenia granicy wokół elementu XML.It's designed to create a boundary around an XML element. Jest to przydatne, jeśli chcesz przekazać dane do innego składnika do przetwarzania i chcesz ograniczyć ilość danych, do których składnik może uzyskać dostęp.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. Po przejściu czytnika XML zwróconego przez metodę ReadSubtree do innej aplikacji, aplikacja może uzyskać dostęp tylko do tego elementu XML, a nie całego dokumentu 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.

Dotyczy