Metodo XmlTextReader.ReadChars (System.Xml)

Cambia visualizzazione:

ScriptFree

Riferimento a .NET Framework

Metodo XmlTextReader.ReadChars

Legge il contenuto del testo di un elemento in un buffer di caratteri. Il metodo consente di leggere flussi di notevoli dimensioni di testo incorporato richiamandolo in un secondo momento.

Spazio dei nomi: System.Xml
Assembly: System.Xml (in system.xml.dll)

Sintassi

Visual Basic - (Dichiarazione)

Public Function ReadChars ( _
	buffer As Char(), _
	index As Integer, _
	count As Integer _
) As Integer

Visual Basic (Utilizzo)

Dim instance As XmlTextReader
Dim buffer As Char()
Dim index As Integer
Dim count As Integer
Dim returnValue As Integer

returnValue = instance.ReadChars(buffer, index, count)

public int ReadChars (
	char[] buffer,
	int index,
	int count
)

C++

public:
int ReadChars (
	array<wchar_t>^ buffer, 
	int index, 
	int count
)

public int ReadChars (
	char[] buffer, 
	int index, 
	int count
)

JScript

public function ReadChars (
	buffer : char[], 
	index : int, 
	count : int
) : int

Parametri

buffer: Matrice di caratteri che agisce da buffer in cui viene scritto il contenuto testuale.

index: Posizione all'interno del parametro buffer in cui il metodo può iniziare a scrivere il contenuto del testo.

count: Numero di caratteri da scrivere in buffer.

Valore restituito

Numero di caratteri letti. Può essere 0 se il visualizzatore non è posizionato su un elemento o se non esiste ulteriore contenuto di testo da restituire nel contesto corrente.

Eccezioni

Tipo di eccezione	Condizione
ArgumentException	Il valore di count è maggiore dello spazio specificato nel parametro buffer (dimensione del buffer: index).
ArgumentNullException	Il valore buffer è riferimento null (Nothing in Visual Basic).
ArgumentOutOfRangeException	index < 0 o count< 0.

Note

Nota
Nella versione Microsoft .NET Framework versione 2.0 è consigliabile creare istanze di XmlReader utilizzando il metodo System.Xml.XmlReader.Create. In questo modo è possibile sfruttare completamente le nuove funzionalità introdotte in questa versione. Per ulteriori informazioni, vedere Creazione di lettori XML.

Rappresenta il modo più efficace per elaborare flussi di notevoli dimensioni di testo inseriti in un documento XML. Invece di allocare oggetti stringa di notevoli dimensioni, ReadChars restituisce il contenuto testuale un buffer alla volta. Il metodo consente di operare solo su nodi elemento. Con altri tipi di nodi ReadChars restituirà 0.

Nel codice XML riportato di seguito, se il visualizzatore è posizionato sul tag di inizio, ReadChars restituirà test e posizionerà il visualizzatore dopo il tag di fine.

<Item>test</Item>

ReadChars fornisce la seguente funzionalità:

Il metodo consente di operare solo su nodi elemento. Con altri tipi di nodi ReadChars restituirà 0.
Questo metodo restituisce il contenuto effettivo del carattere. Non viene effettuato alcun tentativo di risolvere entità, CDATA o qualsiasi altro tipo di codice rilevato. ReadChars restituisce tutti i dati compresi fra il tag di inizio e il tag di fine, inclusi i tag.
ReadChars ignora il codice XML in formato non corretto. Se ad esempio viene letta la stringa XML <A>1<A>2</A>, ReadChars restituirà 1<A>2</A>. Verrà restituito il codice della coppia di elementi corrispondenti, mentre gli altri verranno ignorati.
Questo metodo non effettua alcuna normalizzazione.
Una volta raggiunta la fine del flusso di caratteri, ReadChars restituirà il valore 0 e il visualizzatore verrà posizionato dopo il tag di fine.
Quando si utilizza ReadChars non sono disponibili metodi per la lettura degli attributi.

Se ad esempio si utilizza il seguente codice XML:

 <thing>
  some text
 </thing>
 <item>
 </item>

Il visualizzatore viene posizionato sull'elemento <item> alla fine del ciclo while.

 if (XmlNodeType.Element == reader.NodeType && "thing" == reader.Name)
 {
  while(0 != reader.ReadChars(buffer, 0, 1)
  {
  // Do something.
  // Attribute values are not available at this point.
  }
 }

Esempio

Nell'esempio seguente viene letto il codice XML tramite ReadChars.

Visual Basic

Imports System
Imports System.Xml

' Reads an XML document using ReadChars
Public Class Sample
    Private Const filename As String = "items.xml"
    
    Public Shared Sub Main()
        Dim reader As XmlTextReader = Nothing
        
        Try
            ' Declare variables used by ReadChars
            Dim buffer() As Char
            Dim iCnt As Integer = 0
            Dim charbuffersize As Integer
            
            ' Load the reader with the data file.  Ignore white space.
            reader = New XmlTextReader(filename)
            reader.WhitespaceHandling = WhitespaceHandling.None
            
            ' Set variables used by ReadChars.
            charbuffersize = 10
            buffer = New Char(charbuffersize) {}
            
            ' Parse the file.  Read the element content  
            ' using the ReadChars method.
            reader.MoveToContent()
            iCnt = reader.ReadChars(buffer,0,charbuffersize)
            while (iCnt > 0)
              ' Print out chars read and the buffer contents.
              Console.WriteLine("  Chars read to buffer:" & iCnt)
              Console.WriteLine("  Buffer: [{0}]", New String(buffer, 0, iCnt))
              ' Clear the buffer.
              Array.Clear(buffer, 0, charbuffersize)
              iCnt = reader.ReadChars(buffer,0,charbuffersize)
           end while

        Finally
            If Not (reader Is Nothing) Then
                reader.Close()
            End If
        End Try
    End Sub 
End Class

using System;
using System.Xml;

// Reads an XML document using ReadChars

public class Sample {

  private const String filename = "items.xml";

  public static void Main() {
  
    XmlTextReader reader = null;

    try {
          
      // Declare variables used by ReadChars
      Char []buffer;
      int iCnt = 0;
      int charbuffersize;
     
      // Load the reader with the data file.  Ignore white space.
      reader = new XmlTextReader(filename);
      reader.WhitespaceHandling = WhitespaceHandling.None;

      // Set variables used by ReadChars.
      charbuffersize = 10;
      buffer = new Char[charbuffersize];

      // Parse the file.  Read the element content
      // using the ReadChars method.
      reader.MoveToContent();
      while ( (iCnt = reader.ReadChars(buffer,0,charbuffersize)) > 0 ) {
        // Print out chars read and the buffer contents.
        Console.WriteLine ("  Chars read to buffer:" + iCnt);
        Console.WriteLine ("  Buffer: [{0}]", new String(buffer,0,iCnt));
        // Clear the buffer.
        Array.Clear(buffer,0,charbuffersize);
      }
       
    }
    finally {
      if (reader!=null)
        reader.Close();
    }
  }

} // End class

C++

#using <System.Xml.dll>

using namespace System;
using namespace System::Xml;

// Reads an XML document using ReadChars
int main()
{
   XmlTextReader^ reader = nullptr;
   String^ filename = "items.xml";
   try
   {
      
      // Declare variables used by ReadChars
      array<Char>^buffer;
      int iCnt = 0;
      int charbuffersize;
      
      // Load the reader with the data file.  Ignore white space.
      reader = gcnew XmlTextReader( filename );
      reader->WhitespaceHandling = WhitespaceHandling::None;
      
      // Set variables used by ReadChars.
      charbuffersize = 10;
      buffer = gcnew array<Char>(charbuffersize);
      
      // Parse the file.  Read the element content
      // using the ReadChars method.
      reader->MoveToContent();
      while ( (iCnt = reader->ReadChars( buffer, 0, charbuffersize )) > 0 )
      {
         
         // Print out chars read and the buffer contents.
         Console::WriteLine( "  Chars read to buffer:{0}", iCnt );
         Console::WriteLine( "  Buffer: [{0}]", gcnew String( buffer,0,iCnt ) );
         
         // Clear the buffer.
         Array::Clear( buffer, 0, charbuffersize );
      }
   }
   finally
   {
      if ( reader != nullptr )
            reader->Close();
   }

}

import System.*;
import System.Xml.*;

// Reads an XML document using ReadChars
public class Sample
{
    private static String fileName = "items.xml";

    public static void main(String[] args)
    {
        XmlTextReader reader = null;
        try {
            // Declare variables used by ReadChars
            char buffer[];
            int iCnt = 0;
            int charBufferSize;

            // Load the reader with the data file.Ignore white space.
            reader = new XmlTextReader(fileName);
            reader.set_WhitespaceHandling(WhitespaceHandling.None);

            // Set variables used by ReadChars.
            charBufferSize = 10;
            buffer = new char[charBufferSize];

            // Parse the file.  Read the element content
            // using the ReadChars method.
            reader.MoveToContent();
            while(((iCnt = reader.ReadChars(buffer, 0,charBufferSize)) > 0)) {
                // Print out chars read and the buffer contents.
                Console.WriteLine(("  Chars read to buffer:" + iCnt));
                Console.WriteLine("Buffer: [{0}]",
                    new String(buffer, 0, iCnt));
                // Clear the buffer.
                Array.Clear(buffer, 0, charBufferSize);
            }
        } 
        finally {
            if (reader != null) {
                reader.Close();
            }
        }
    } //main
} // End class Sample

Nell'esempio viene utilizzato il file items.xml come input.


<?xml version="1.0"?>
<!-- This is a sample XML document -->
<!DOCTYPE Items [<!ENTITY number "123">]>
<Items>
  <Item>Test with an entity: &number;</Item>
  <Item>test with a child element <more/> stuff</Item>
  <Item>test with a CDATA section <![CDATA[<456>]]> def</Item>
  <Item>Test with an char entity: &#65;</Item>
  <!-- Fourteen chars in this element.-->
  <Item>1234567890ABCD</Item>
</Items>

Piattaforme

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile per Pocket PC, Windows Mobile per Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

.NET Framework non supporta tutte le versioni di ciascuna piattaforma. Per un elenco delle versioni supportate, vedere Requisiti di sistema.

Informazioni sulla versione

.NET Framework

Supportato in: 2.0 1.1 1.0

.NET Compact Framework

Supportato in: 2.0 1.0

Vedere anche

Riferimenti

Classe XmlTextReader
Membri XmlTextReader
Spazio dei nomi System.Xml
ReadBase64
ReadBinHex

Altre risorse

Lettura di XML con XmlReader