This method enables reading of very large streams of text embedded in an XML document in a streaming fashion, that is, a small number of characters at a time instead of allocating a single string for the whole value. This method can be called on any node that has a value (XmlReader.HasValue is true), however actual streaming of the node value only occurs when called on a text, white space and significant white space nodes. Other node type values are cached, including attributes and CDATA nodes.

This method returns only the content of the XmlReader.Value property and does not move the System.Xml.XmlReader.

This method reads the specified number of characters (count) of the node value into a character buffer (buffer) at a specified offset (index) and returns the number of characters written to the buffer. It returns the 0 when it has reached the end of the value. It cannot be restarted to read through the value again.

In between calls to XmlReader.ReadValueChunk(Char[], int, int) the System.Xml.XmlReader properties do no change except for the XmlReader.Value property. When the XmlReader.Value property is accessed it may either return a partial value (with characters not yet returned by XmlReader.ReadValueChunk(Char[], int, int)) or a full value depending on the implementation. All the System.Xml.XmlReader implementations in the System.Xml namespace return a partial value for the XmlReader.Value property implementation.

Any Read method can be called in between calls to XmlReader.ReadValueChunk(Char[], int, int). If this occurs, the System.Xml.XmlReader moves to the next System.Xml.XmlNodeType in the stream and any characters not yet returned are skipped.

There may be a case when XmlReader.ReadValueChunk(Char[], int, int) returns less than the requested number of characters. For example, if you had a 200-character long value with a surrogate pair at positions 127 and 128 and you called XmlReader.ReadValueChunk(Char[], int, int) with a 128-character buffer, the method call would return 127 characters instead of the requested 128. The surrogate pair would then be returned in the next XmlReader.ReadValueChunk(Char[], int, int) call. In this case, XmlReader.ReadValueChunk(Char[], int, int) did not return the requested 128 characters because doing so would have resulted in an incomplete surrogate pair at the end of the buffer.

For the asynchronous version of this method, see XmlReader.ReadValueChunkAsync(Char[], int, int).

Namespace: System.Xml
Assembly: System.Xml (in System.Xml.dll)
Assembly Versions: 2.0.0.0, 4.0.0.0
Since: .NET 2.0