XmlReader.ReadSubtree Método

Definição

Retorna uma nova instância XmlReader que pode ser usada para ler o nó atual e todos os seus descendentes.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

Retornos

XmlReader

Uma nova instância de leitor XML definida como Initial.A new XML reader instance set to Initial. Uma chamada ao método Read() posiciona o novo leitor no nó que era atual antes da chamada ao método ReadSubtree().Calling the Read() method positions the new reader on the node that was current before the call to the ReadSubtree() method.

Exceções

O leitor de XML não está posicionado em um elemento quando esse método é chamado.The XML reader isn't positioned on an element when this method is called.

- ou --or-

Um método XmlReader foi chamado antes do término de uma operação assíncrona anterior.An XmlReader method was called before a previous asynchronous operation finished. Nesse caso, InvalidOperationException será gerado com a mensagem “Uma operação assíncrona já está em andamento”.In this case, InvalidOperationException is thrown with the message "An asynchronous operation is already in progress."

Exemplos

O exemplo a seguir mostra como usar o método 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

Use os seguintes dados XML para executar os exemplos neste tópico: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>  

Comentários

ReadSubtree pode ser chamado somente em nós de elemento.ReadSubtree can be called only on element nodes. Quando a subárvore inteira tiver sido lida, as chamadas para o Read método retornarão false .When the entire sub-tree has been read, calls to the Read method returns false. Quando o novo leitor de XML tiver sido fechado, o leitor original será posicionado no EndElement nó da subárvore.When the new XML reader has been closed, the original reader is positioned on the EndElement node of the sub-tree. Portanto, se você chamou o ReadSubtree método na marca de início do elemento de livro, depois que a subárvore tiver sido lida e o novo leitor de XML tiver sido fechado, o leitor XML original será posicionado na marca de fim do elemento de livro.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.

Você não deve executar qualquer operações no leitor original até que o novo leitor seja fechado.You should not perform any operations on the original reader until the new reader has been closed. Esta ação não é suportada e pode levar ao comportamento imprevisível.This action is not supported and can result in unpredictable behavior.

Observação

O ReadSubtree método não se destina a criar cópias dos dados XML com os quais você pode trabalhar de forma independente.The ReadSubtree method isn't intended for creating copies of the XML data that you can work with independently. Ele foi projetado para criar um limite em um elemento XML.It's designed to create a boundary around an XML element. Isso é útil se você deseja passar dados para outro componente para processamento e deseja limitar a quantidade de dados que o componente pode acessar.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. Quando você passa um leitor XML retornado pelo ReadSubtree método para outro aplicativo, o aplicativo pode acessar apenas esse elemento XML, não o documento XML inteiro.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.

Aplica-se a