XmlTextReader.ReadChars Method (Char[], Int32, Int32)


The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Reads the text contents of an element into a character buffer. This method is designed to read large streams of embedded text by calling it successively.

Namespace:   System.Xml
Assembly:  System.Xml (in System.Xml.dll)

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


Type: System.Char[]

The array of characters that serves as the buffer to which the text contents are written.

Type: System.Int32

The position within buffer where the method can begin writing text contents.

Type: System.Int32

The number of characters to write into buffer.

Return Value

Type: System.Int32

The number of characters read. This can be 0 if the reader is not positioned on an element or if there is no more text content to return in the current context.

Exception Condition

count is greater than the space specified in the buffer (buffer size - index).


The buffer value is null.


index< 0 or count< 0.


Starting with the .NET Framework 2.0, we recommend that you create XmlReader instances by using the XmlReader.Create method to take advantage of new functionality.

This is the most efficient way to process very large streams of text embedded in an XML document. Rather than allocating large string objects, ReadChars returns text content a buffer at a time. This method is designed to work only on element nodes. Other node types cause ReadChars to return 0.

In the following XML, if the reader is positioned on the start tag, ReadChars returns test and positions the reader after the end tag.


ReadChars has the following functionality:

  • This method is designed to work on element nodes only. Other node types cause ReadChars to return 0.

  • This method returns the actual character content. There is no attempt to resolve entities, CDATA, or any other markup encountered. ReadChars returns everything between the start tag and the end tag, including markup.

  • ReadChars ignores XML markup that is not well-formed. For example, when reading the following XML string <A>1<A>2</A>, ReadChars returns 1<A>2</A>. (It returns markup from the matching element pair and ignores others.)

  • This method does not do any normalization.

  • When ReadChars has reached the end of the character stream, it returns the value 0 and the reader is positioned after the end tag.

  • Attribute read methods are not available while using ReadChars.

For example, using the following XML:

 some text

The reader is positioned on the <item> element at the end of the while loop.

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.

The following example reads in XML using ReadChars.

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

    finally {
      if (reader!=null)

} // End class

The example uses the items.xml file as input.

<?xml version="1.0"?>
<!-- This is a sample XML document -->
<!DOCTYPE Items [<!ENTITY number "123">]>
  <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.-->

.NET Framework
Available since 1.1
Return to top