XmlReader.ReadSubtree Método

Definição

Namespace:

System.Xml

Assembly:

System.Xml.ReaderWriter.dll

Assembly:

System.Xml.dll

Assembly:

netstandard.dll

Retorna uma nova instância XmlReader que pode ser usada para ler o nó atual e todos os seus descendentes.

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. Uma chamada ao método Read() posiciona o novo leitor no nó que era atual antes da chamada ao método ReadSubtree().

Exceções

InvalidOperationException

O leitor de XML não está posicionado em um elemento quando esse método é chamado.

- ou -

Um método XmlReader foi chamado antes do término de uma operação assíncrona anterior. Nesse caso, InvalidOperationException será gerado com a mensagem “Uma operação assíncrona já está em andamento”.

Exemplos

O exemplo a seguir mostra como usar o método ReadSubtree.

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:

<?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. Quando toda a subconsulta tiver sido lida, as chamadas para o Read método retornarão false. Quando o novo leitor XML é fechado, o leitor original é posicionado no EndElement nó da sub-árvore. Portanto, se você chamou o ReadSubtree método na marca inicial do elemento de livro, depois que a sub-árvore tiver sido lida e o novo leitor XML tiver sido fechado, o leitor XML original será posicionado na marca final do elemento do livro.

Você não deve executar qualquer operações no leitor original até que o novo leitor seja fechado. Esta ação não é suportada e pode levar ao comportamento imprevisível.

Observação

O ReadSubtree método não se destina à criação de cópias dos dados XML com os quais você pode trabalhar independentemente. Ele foi projetado para criar um limite em torno de um elemento XML. Isso é útil se você quiser passar dados para outro componente para processamento e quiser limitar a quantidade de dados que o componente pode acessar. Quando você passa um leitor XML retornado pelo ReadSubtree método para outro aplicativo, o aplicativo pode acessar somente esse elemento XML, não o documento XML inteiro.