XmlReader.ReadSubtree Méthode

Définition

Espace de noms:

System.Xml

Assembly:

System.Xml.ReaderWriter.dll

Source:

XmlReader.cs

Retourne une nouvelle instance de XmlReader qui permet de lire le nœud actuel, ainsi que tous ses 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

Retours

XmlReader

Nouvelle instance du lecteur XML définie sur Initial. L’appel de la méthode Read() place le nouveau lecteur sur le nœud qui était actuel avant l’appel à la méthode ReadSubtree().

Exceptions

InvalidOperationException

Le lecteur XML n’est pas placé sur un élément quand cette méthode est appelée.

- ou -

Une méthode XmlReader a été appelée avant la fin d’une opération asynchrone précédente. Dans ce cas, l’exception InvalidOperationException est levée avec le message « Une opération asynchrone est déjà en cours ».

Exemples

L'exemple suivant illustre l'utilisation de la méthode 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

Utilisez les données XML suivantes pour exécuter les exemples de cette rubrique :

<?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>

Remarques

ReadSubtree peut être appelé uniquement sur les nœuds d’élément. Lorsque l’ensemble de la sous-arborescence a été lu, les appels à la Read méthode retournent false. Lorsque le nouveau lecteur XML a été fermé, le lecteur d’origine est positionné sur le EndElement nœud de la sous-arborescence. Par conséquent, si vous avez appelé la ReadSubtree méthode sur la balise de début de l’élément book, une fois que la sous-arborescence a été lue et que le nouveau lecteur XML a été fermé, le lecteur XML d’origine est positionné sur la balise de fin de l’élément book.

Vous ne devez pas effectuer d'opérations sur le lecteur original avant la fermeture du nouveau lecteur. Cette action n'est pas prise en charge et peut provoquer un comportement imprévisible.

Notes

La ReadSubtree méthode n’est pas destinée à créer des copies des données XML que vous pouvez utiliser indépendamment. Il est conçu pour créer une limite autour d’un élément XML. Cela est utile si vous souhaitez transmettre des données à un autre composant à des fins de traitement et que vous souhaitez limiter la quantité de données à laquelle le composant peut accéder. Lorsque vous transmettez un lecteur XML retourné par la ReadSubtree méthode à une autre application, l’application peut accéder uniquement à cet élément XML, pas à l’intégralité du document XML.