System.Xml.XmlTextReader Class

public class XmlTextReader : XmlReader

Base Types

Object
  XmlReader
    XmlTextReader

Assembly

System.Xml

Library

XML

Summary

Represents a reader that provides fast, non-cached, forward-only access to XML data.

Description

This class provides forward-only, read-only access to a character stream of XML data. This class enforces the rules of well-formed XML but does not perform data validation.

This class implements the XmlReader class and conforms to the W3C Extensible Markup Language (XML) 1.0 and the Namespaces in XML recommendations.

A given set of XML data is modeled as a tree of nodes. The different types of nodes are specified in the XmlNodeType enumeration. The current node refers to the node on which the reader is positioned. The reader is advanced using any of the "read" or "moveto" methods. The following table lists the node properties exposed for the current node.

Property	Description
AttributeCount	The number of attributes on the node.
BaseUri	The base URI of the node.
Depth	The depth of the node in the tree.
HasAttributes	Whether the node has attributes. (Inherited from XmlReader)
HasValue	Whether the node can have a text value.
IsDefault	Whether an Attribute node was generated from the default value defined in the DTD or schema.
IsEmptyElement	Whether an Element node is empty.
LocalName	The local name of the node.
Name	The qualified name of the node, equal to Prefix :LocalName .
NamespaceUri	The URI defining the namespace associated with the node.
NodeType	The XmlNodeType of the node.
Prefix	A shorthand reference to the namespace associated with the node.
QuoteChar	The quotation mark character used to enclose the value of an attribute.
Value	The text value of the node.
XmlLang	The xml:lang scope within which the node resides.

This class does not expand default attributes or resolve general entities. Any general entities encountered are returned as a single empty EntityReference node.

This class checks that a Document Type Definition (DTD) is well-formed, but does not validate using the DTD.

To read strongly typed data, use the XmlConvert class.

This class throws a XmlException on XML parse errors. After an exception is thrown, the state of the reader is not predictable. For example, the reported node type can be different than the actual node type of the current node.

Attributes

DefaultMemberAttribute("Item")

See Also

System.Xml Namespace

Members

XmlTextReader Constructors

XmlTextReader(System.String) Constructor
XmlTextReader(System.String, System.Xml.XmlNodeType, System.Xml.XmlParserContext) Constructor
XmlTextReader(System.String, System.Xml.XmlNameTable) Constructor
XmlTextReader(System.IO.Stream, System.Xml.XmlNodeType, System.Xml.XmlParserContext) Constructor
XmlTextReader() Constructor
XmlTextReader(System.Xml.XmlNameTable) Constructor
XmlTextReader(System.IO.Stream) Constructor
XmlTextReader(System.String, System.IO.Stream) Constructor
XmlTextReader(System.IO.Stream, System.Xml.XmlNameTable) Constructor
XmlTextReader(System.String, System.IO.Stream, System.Xml.XmlNameTable) Constructor
XmlTextReader(System.IO.TextReader) Constructor
XmlTextReader(System.String, System.IO.TextReader) Constructor
XmlTextReader(System.IO.TextReader, System.Xml.XmlNameTable) Constructor
XmlTextReader(System.String, System.IO.TextReader, System.Xml.XmlNameTable) Constructor

XmlTextReader Methods

XmlTextReader.Close Method
XmlTextReader.GetAttribute(System.String) Method
XmlTextReader.GetAttribute(System.String, System.String) Method
XmlTextReader.GetAttribute(int) Method
XmlTextReader.GetRemainder Method
XmlTextReader.LookupNamespace Method
XmlTextReader.MoveToAttribute(int) Method
XmlTextReader.MoveToAttribute(System.String, System.String) Method
XmlTextReader.MoveToAttribute(System.String) Method
XmlTextReader.MoveToElement Method
XmlTextReader.MoveToFirstAttribute Method
XmlTextReader.MoveToNextAttribute Method
XmlTextReader.Read Method
XmlTextReader.ReadAttributeValue Method
XmlTextReader.ReadBase64 Method
XmlTextReader.ReadBinHex Method
XmlTextReader.ReadChars Method
XmlTextReader.ReadInnerXml Method
XmlTextReader.ReadOuterXml Method
XmlTextReader.ReadString Method
XmlTextReader.ResetState Method
XmlTextReader.ResolveEntity Method

XmlTextReader Properties

XmlTextReader.AttributeCount Property
XmlTextReader.BaseURI Property
XmlTextReader.Depth Property
XmlTextReader.EOF Property
XmlTextReader.Encoding Property
XmlTextReader.HasValue Property
XmlTextReader.IsDefault Property
XmlTextReader.IsEmptyElement Property
XmlTextReader.Item(int) Property
XmlTextReader.Item(System.String) Property
XmlTextReader.Item(System.String, System.String) Property
XmlTextReader.LineNumber Property
XmlTextReader.LinePosition Property
XmlTextReader.LocalName Property
XmlTextReader.Name Property
XmlTextReader.NameTable Property
XmlTextReader.NamespaceURI Property
XmlTextReader.Namespaces Property
XmlTextReader.NodeType Property
XmlTextReader.Normalization Property
XmlTextReader.Prefix Property
XmlTextReader.QuoteChar Property
XmlTextReader.ReadState Property
XmlTextReader.Value Property
XmlTextReader.WhitespaceHandling Property
XmlTextReader.XmlLang Property
XmlTextReader.XmlResolver Property
XmlTextReader.XmlSpace Property

Constructs and initializes a new instance of the XmlTextReader class with the specified file.

Parameters

url

A String specifying the URL for the file containing the XML data.

Exceptions

Exception Type	Condition
XmlException	url is null .

Description

This constructor is equivalent to System.Xml.XmlTextReader.XmlTextReader(url, new NameTable()).

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified XML fragment.

Parameters

xmlFragment

A String containing the XML fragment to parse.

fragType

The XmlNodeType of the XML fragment. This also determines what the fragment string can contain. (See table below.)

context

The XmlParserContext in which the xmlFragment is to be parsed, or null .

Exceptions

Exception Type	Condition
ArgumentNullException	xmlFragment is null .
XmlException	fragType is not an Element , Attribute , or Document XmlNodeType.

Description

The following table lists valid values for fragType and how the reader will parse each of the different node types.

XmlNodeType	Fragment Can Contain
Element	Any valid element content (for example, any combination of elements, comments, processing instructions, CDATA sections, text, and entity references).
Attribute	The value of an attribute (the part inside the quotes).
Document	The contents of an entire XML document; document level rules are enforced.

[Note: If the XML fragment is an element or attribute, root level rules for well-formed XML documents are not enforced.

This constructor can handle strings returned from System.Xml.XmlTextReader.ReadInnerXml.

]

This constructor calls System.Xml.XmlTextReader.XmlTextReader(context.NameTable ) or, if context is null , System.Xml.XmlTextReader.XmlTextReader(new NameTable()) to initialize properties of the class. Following this call, if context is not null , the following XmlTextReader properties are set to the specified values.

Property	Value
BaseUri	context.BaseURI or, if context is null , System.String.Empty.
Encoding	context.Encoding or, if context or context.Encoding is null , UTF-8.
XmlLang	If context is not null , context.XmlLang . If context is null , this property is not changed.
XmlSpace	If context is not null , context.XmlSpace . If context is null , this property is not changed.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified file and name table.

Parameters

url

A String specifying the URL for the file containing the XML data to read.

nt

The XmlNameTable to use.

Exceptions

Exception Type	Condition
ArgumentNullException	nt is null .
XmlException	url is null .

Description

This constructor calls XmlTextReader(nt) to initialize properties of the class.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified stream containing an XML fragment.

Parameters

xmlFragment

The Stream containing the XML fragment to parse.

fragType

The XmlNodeType of the XML fragment. This also determines what the fragment string can contain. (See table below.)

context

The XmlParserContext in which the xmlFragment is to be parsed, or null .

Exceptions

Exception Type	Condition
ArgumentNullException	xmlFragment is null .
XmlException	fragType is not an Element , Attribute , or Document XmlNodeType.

Description

The following table lists valid values for fragType.

XmlNodeType	Fragment Can Contain
Element	Any valid element content (for example, any combination of elements, comments, processing instructions, CDATA sections, text, and entity references).
Attribute	The value of an attribute (the part inside the quotes).
Document	The contents of an entire XML document; document level rules are enforced.

[Note: If the XML fragment is an element or attribute, the root level rules for well-formed XML documents are not enforced.

]

This constructor calls XmlTextReader(context.NameTable ) or, if context is null , XmlTextReader(new NameTable()) to initialize properties of the class. Afterwards, the following XmlTextReader properties are set to the specified values.

Property	Value
BaseUri	context.BaseURI or, if context is null , System.String.Empty.
Encoding	context.Encoding or, if context or context.Encoding is null , the encoding corresponding to the byte-order mark at the beginning of the stream or, if no byte-order mark is found, UTF-8.
Namespaces	true .
XmlLang	If context is not null , context.XmlLang . If context is null , this property is not changed.
XmlSpace	If context is not null , context.XmlSpace . If context is null , this property is not changed.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs a new instance of the XmlTextReader class.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified name table.

Parameters

nt

The XmlNameTable to use.

Exceptions

Exception Type	Condition
ArgumentNullException	nt is null .

Description

The XmlTextReader public constructors call this constructor to initialize the following XmlTextReader properties to the specified values. Derived classes can call this constructor to incorporate this behavior.

Property	Value
Namespaces	true
NameTable	nt
Normalization	false
ReadState	System.Xml.ReadState.Initial
WhitespaceHandling	System.Xml.WhitespaceHandling.All
XmlLang	System.String.Empty
XmlSpace	System.Xml.XmlSpace.None
XmlResolver	new XmlUrlResolver()

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified stream.

Parameters

input

The Stream containing the XML data to read.

Exceptions

Exception Type	Condition
ArgumentNullException	input is null .

Description

This constructor is equivalent to System.Xml.XmlTextReader.XmlTextReader(System.String.Empty, input, new NameTable()).

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified URL and stream.

Parameters

url

A String specifying the URL to use for resolving external resources.

input

The Stream containing the XML data to read.

Exceptions

Exception Type	Condition
ArgumentNullException	input is null .

Description

This constructor is equivalent to System.Xml.XmlTextReader.XmlTextReader(url, input, new NameTable()).

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified stream and name table.

Parameters

input

The Stream containing the XML data to read.

nt

The XmlNameTable to use.

Exceptions

Exception Type	Condition
ArgumentNullException	input or nt is null .

Description

This constructor is equivalent to System.Xml.XmlTextReader.XmlTextReader(System.String.Empty, input, nt).

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified URL, stream, and name table.

Parameters

url

A String specifying the URL to use for resolving external resources.

input

The Stream containing the XML data to read.

nt

The XmlNameTable to use.

Exceptions

Exception Type	Condition
ArgumentNullException	input or nt is null .

Description

This constructor calls System.Xml.XmlTextReader.XmlTextReader(nt) to initialize properties of the class.

System.Xml.XmlTextReader.Encoding is set to the encoding corresponding to the byte-order mark at the beginning of the stream or, if no byte-order mark is found, UTF-8.

System.Xml.XmlTextReader.BaseURI is set to url or, if url is null , to System.String.Empty.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified TextReader.

Parameters

input

A TextReader, set to the correct encoding, containing the XML data to read.

Description

This constructor is equivalent to System.Xml.XmlTextReader.XmlTextReader(System.String.Empty, input, new NameTable()).

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified URL and TextReader.

Parameters

url

A String specifying the URL to use for resolving external resources.

input

A TextReader, set to the correct encoding, containing the XML data to read.

Description

This constructor is equivalent to System.Xml.XmlTextReader.XmlTextReader(url, input, new NameTable()).

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified TextReader, and name table.

Parameters

input

A TextReader, set to the correct encoding, containing the XML data to read.

nt

The XmlNameTable to use.

Exceptions

Exception Type	Condition
ArgumentNullException	nt is null .

Description

This constructor is equivalent to System.Xml.XmlTextReader.XmlTextReader(System.String.Empty, input, nt).

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Constructs and initializes a new instance of the XmlTextReader class with the specified URL, TextReader, and name table.

Parameters

url

A String specifying the URL to use for resolving external resources.

input

A TextReader, set to the correct encoding, containing the XML data to read.

nt

The XmlNameTable to use.

Exceptions

Exception Type	Condition
ArgumentNullException	nt is null .

Description

If input is null , a XmlException is thrown when the System.Xml.XmlTextReader.Read method is called.

This constructor calls System.Xml.XmlTextReader.XmlTextReader(nt) to initialize properties of the class.

System.Xml.XmlTextReader.BaseURI is set to url or, if url is null , to System.String.Empty.

[Note: To pass a user defined string that represents full, well-formed XML data, create a StringReader with the string and pass the StringReader to this constructor.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

This method releases any resources allocated by the current instance, changes the System.Xml.XmlTextReader.ReadState to System.Xml.ReadState.Closed, and calls the Close method of any underlying Stream or TextReader instance.

[Note: This method overrides System.Xml.XmlReader.Close.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

name

A String specifying the qualified name of the attribute.

Return Value

A String containing the value of the specified attribute, or null if the attribute is not found. If name is null , null is returned.

Description

This method does not move the reader.

[Note: If the reader is positioned on a DocumentType node, this method can be used to get the PUBLIC and SYSTEM literals.

This method overrides System.Xml.XmlReader.GetAttribute(System.String).

]

Example

See the System.Xml.XmlTextReader.GetAttribute(System.Int32)(String , String ) method for an example using all three overloads of this method.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

localName

A String specifying the local name of the attribute.

namespaceURI

A String specifying the namespace URI of the attribute.

Return Value

A String containing the value of the specified attribute, or null if the attribute is not found. If localname is null , null is returned.

Description

If namespaceURI is null , the local namespace is searched for localName.

This method does not move the reader.

[Note: This method overrides System.Xml.XmlReader.GetAttribute(System.String).

]

Example

This example writes the value of the attributes from the following XML fragment to the console:

<test xmlns:dt="urn:datatypes" dt:type="int"/>

The second attribute value is retrieved using all three overloads of this method.

using System;
using System.Xml;

public class Reader {

  public static void Main() {

    string xmlFragment = @"<test xmlns:dt=""urn:datatypes""
                            dt:type=""int""/>";

    NameTable nameTable = new NameTable();
    XmlNamespaceManager xmlNsMan = new 
         XmlNamespaceManager(nameTable);
    XmlParserContext xmlPContext = new
         XmlParserContext(null, xmlNsMan,
                          null, XmlSpace.None);
    XmlTextReader xmlTReader = new
         XmlTextReader(xmlFragment,XmlNodeType.Element,
                       xmlPContext);

    xmlTReader.Read();
    Console.WriteLine( "{0}", xmlTReader.GetAttribute(0) );

    string str1 = xmlTReader.GetAttribute(1);
    string str2 = xmlTReader.GetAttribute("dt:type");
    string str3 = xmlTReader.GetAttribute("type",
                                          "urn:datatypes");
    Console.WriteLine("{0} - {1} - {2}",
                      str1, str2, str3);
  }
}
   

The output is

urn:datatypes

int - int - int

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

i

A Int32 specifying the zero-based index of the attribute relative to the containing element.

Return Value

A String containing the value of the specified attribute.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	i is less than 0, or greater than or equal to the System.Xml.XmlTextReader.AttributeCount of the containing element.[Note: System.Xml.XmlTextReader.AttributeCount returns zero for all node types except Attribute , DocumentType , Element , and XmlDeclaration . Therefore, this exception is thrown if the reader is not positioned on one of these node types.]

Description

This method does not move the reader.

[Note: This method overrides System.Xml.XmlReader.GetAttribute(System.String). ]

Example

See the System.Xml.XmlTextReader.GetAttribute(System.Int32)(String , String ) method for an example using all three overloads of this method.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

The StringReader attached to the XML.

Description

This method calls the System.Xml.XmlTextReader.Close method, and then resets the System.Xml.XmlTextReader.ReadState to System.Xml.ReadState.EndOfFile.

[Note: Because XmlTextReader performs a buffered read operation, it must be able to return the remainder of the unused buffer so that no data is lost. For example, this allows protocols (such as multi-part MIME) to package XML in the same stream.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

prefix

A String specifying the prefix whose namespace URI is to be resolved. To return the default namespace, specify System.String.Empty.

Return Value

A String containing the namespace URI to which the prefix maps. If System.Xml.XmlTextReader.Namespaces is false , prefix is not in System.Xml.XmlTextReader.NameTable, or no matching namespace is found, null is returned.

Exceptions

Exception Type	Condition
ArgumentNullException	The System.Xml.XmlTextReader.Namespaces property of the current instance is true and prefix is null .

Description

[Note: In the following XML, if the reader is positioned on the href attribute, the prefix "a" is resolved by calling System.Xml.XmlTextReader.LookupNamespace(System.String)("a"). The returned string is "urn:456".

<root xmlns:a="urn:456">

<item>

<ref href="a:b"/>

</item>

</root>

This method overrides System.Xml.XmlReader.LookupNamespace(System.String).

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

i

A Int32 specifying the zero-based index of the attribute relative to the containing element.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	i is less than 0 or greater than or equal to the System.Xml.XmlTextReader.AttributeCount of the containing element.[Note: System.Xml.XmlTextReader.AttributeCount returns zero for all node types except Attribute , DocumentType , Element , and XmlDeclaration . Therefore, this exception is thrown if the reader is not positioned on one of these node types.]

Description

After calling this method, the System.Xml.XmlTextReader.Name, System.Xml.XmlTextReader.NamespaceURI, and System.Xml.XmlTextReader.Prefix properties reflect the properties of the new attribute.

[Note: This method overrides System.Xml.XmlReader.MoveToAttribute(System.String).

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

localName

A String specifying the local name of the attribute.

namespaceURI

A String specifying the namespace URI of the attribute.

Return Value

A Boolean where true indicates the attribute was found. If localname is null , or the attribute was not found, false is returned and the position of the reader does not change.

Description

If namespaceURI is null , the local namespace is searched for localName.

After calling this method, the System.Xml.XmlTextReader.Name, System.Xml.XmlTextReader.NamespaceURI, and System.Xml.XmlTextReader.Prefix properties reflect the properties of the new attribute.

[Note: This method overrides System.Xml.XmlReader.MoveToAttribute(System.String).

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

name

A String specifying the qualified name of the attribute.

Return Value

A Boolean where true indicates the attribute was found. If name is null , or the attribute was not found, false is returned and the position of the reader does not change.

Description

After calling this method, the System.Xml.XmlTextReader.Name, System.Xml.XmlTextReader.NamespaceURI, and System.Xml.XmlTextReader.Prefix properties reflect the properties of the new attribute.

[Note: This method overrides System.Xml.XmlReader.MoveToAttribute(System.String).

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the reader was moved; false indicates the reader was not positioned on an Attribute node and therefore was not moved.

Description

[Note: The DocumentType , Element , and XmlDeclaration node types can contain attributes.

This method overrides System.Xml.XmlReader.MoveToElement.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the current node contains at least one attribute; otherwise, false .

Description

If System.Xml.XmlTextReader.AttributeCount is non-zero, the reader moves to the first attribute; otherwise, the position of the reader does not change.

[Note: This method overrides System.Xml.XmlReader.MoveToFirstAttribute.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the reader moved to the next attribute; false if there were no more attributes.

Description

If the current node is an element node, this method is equivalent to System.Xml.XmlTextReader.MoveToFirstAttribute.

[Note: This method overrides System.Xml.XmlReader.MoveToNextAttribute.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the node was read successfully, and false indicates there were no more nodes to read.

Exceptions

Exception Type	Condition
XmlException	An error occurred while parsing the XML.

Description

[Note: When a reader is first created and initialized, there is no information available. Calling this method is required to read the first node.

This method overrides System.Xml.XmlReader.Read.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the attribute value was parsed, and false indicates the reader was not positioned on an attribute node or all the attribute values have been read.

Description

The XmlTextReader class does not expand general entities; any encountered are returned as a single empty EntityReference node (System.Xml.XmlTextReader.Value is System.String.Empty).

[Note: Use this method after calling System.Xml.XmlTextReader.MoveToAttribute(System.String) to read through the text or entity reference nodes that make up the attribute value. The System.Xml.XmlTextReader.Depth of the attribute value nodes is one plus the depth of the attribute node. When general entity references are stepped into or out of, the System.Xml.XmlTextReader.Depth is incremented of decremented by one, respectively.

This method overrides System.Xml.XmlReader.ReadAttributeValue.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

array

A Byte array to store the content.

offset

A Int32 specifying the zero-based index into array where the method should begin to write.

len

A Int32 specifying the number of bytes to write.

Return Value

A Int32 containing the number of bytes written to array, or zero if the current instance is not positioned on an element.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
ArgumentOutOfRangeException	offset < 0, or len < 0. - or - len > array.Length - offset.
XmlException	The Base64 sequence is not valid.

Description

[Note: This method can be called successively to read large streams of embedded text.

Base64 encoding represents byte sequences in a text form comprised of the 65 US-ASCII characters (A-Z, a-z, 0-9, +, /, =) where each character encodes 6 bits of the binary data.

For more information on Base64 encoding, see RFC 2045 (http://www.ietf.org/rfc/2045).

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

array

A Byte array to store the content.

offset

A Int32 specifying the zero-based index into array where the method should begin to write.

len

A Int32 specifying the number of bytes to write.

Return Value

A Int32 containing the number of bytes written to array, or zero if the current instance is not positioned on an element.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null .
ArgumentOutOfRangeException	offset < 0, or len < 0. -or- len > array.Length - offset.
XmlException	The BinHex sequence is not valid.

Description

[Note: This method can be called successively to read large streams of embedded text.

For information on BinHex encoding, see RFC 1741 (http://www.ietf.org/rfc/rfc1741).

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

buffer

A Char array to store the content.

index

A Int32 specifying the zero-based index into buffer where the method should begin to write.

count

A Int32 specifying the number of characters to read and store in buffer.

Return Value

A Int32 containing the number of characters written to buffer, or zero if the current instance is not positioned on an element.

Exceptions

Exception Type	Condition
ArgumentException	count > buffer.Length - index.
ArgumentNullException	buffer is null .
ArgumentOutOfRangeException	index < 0, or count < 0.

Description

If the end of the character stream in the element is reached before the specified number of characters is read, the return value will be less than count.

This method has the following functionality:

• It is designed to work on element nodes only; it returns zero for other node types.
• It returns the actual character content including markup. There is no attempt to resolve entities, CDATA, or any other markup encountered.
• It ignores XML markup that is not well-formed. For example, when reading the following XML string &lt;A>1<A>2</A>, 1<A>2</A> is returned. (It returns markup from the matching element pair and ignores others.)
• It does not do any normalization.
• When it has reached the end of the character stream, the reader is positioned after the end tag.
• Attribute read methods are not available.

[Note: Using this method is the most efficient way to process very large streams of text embedded in an XML document. Rather than allocating large string objects, this method returns text content a buffer at a time.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the XML content, or System.String.Empty if the current node is neither an element nor attribute, or has no child nodes.

Exceptions

Exception Type	Condition
XmlException	The XML was not well-formed, or an error occurred while parsing the XML.

Description

The current node and corresponding end node are not returned.

If the current node is an element, after the call to this method, the reader is positioned after the corresponding end element.

If the current node is an attribute, the position of the reader is not changed.

[Note: If the reader is positioned on a XmlNodeType other than Element or Attribute , calling this method is equivalent to calling the System.Xml.XmlTextReader.Read method.

A comparison between calling the System.Xml.XmlTextReader.ReadInnerXml and System.Xml.XmlTextReader.ReadOuterXml methods on a XML fragment is shown below.

Assume the reader is positioned on <book1 in the following XML fragment.

<books>
   <book1 id="123" cost="39.95">
      Title1
      <page1/>
   </book1>
</books>

Calling System.Xml.XmlTextReader.ReadInnerXml returns

Title1

<page1/>

Calling System.Xml.XmlTextReader.ReadOuterXml returns

<book1 id="123" cost="39.95">
   Title1
   <page1/>
</book1>

After either method returns, the reader is positioned on </books>.

Assume the reader is positioned on id in the previous XML fragment.

Calling System.Xml.XmlTextReader.ReadInnerXml returns

123

Calling System.Xml.XmlTextReader.ReadOuterXml returns

id="123"

After either method returns, the reader is still positioned on id.

This method overrides System.Xml.XmlReader.ReadInnerXml.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the XML content, or System.String.Empty if the current node is neither an element nor attribute.

Exceptions

Exception Type	Condition
XmlException	The XML was not well-formed, or an error occurred while parsing the XML.

Description

The current node and corresponding end node are returned.

If the current node is an element, after the call to this method, the reader is positioned after the corresponding end element.

If the current node is an attribute, the position of the reader is not changed.

[Note: If the reader is positioned on a XmlNodeType other than Element or Attribute , calling this method is equivalent to calling the System.Xml.XmlTextReader.Read method.

For a comparison between this method and the System.Xml.XmlTextReader.ReadInnerXml method, see System.Xml.XmlTextReader.ReadInnerXml.

This method overrides System.Xml.XmlReader.ReadOuterXml.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the contents of the Element or Text node, or System.String.Empty if the reader is positioned on any other type of node.

Exceptions

Exception Type	Condition
InvalidOperationException	An invalid operation was attempted.
XmlException	An error occurred while parsing the XML.

Description

If positioned on an Element node, this method concatenates all Text , SignificantWhitespace , Whitespace , and CDATA node types, and returns the concatenated data as the element content. If none of these node types exist, System.String.Empty is returned. Concatenation stops when any markup is encountered, which can occur in a mixed content model or when an element end tag is read.

If positioned on an element Text node, this method performs the same concatenation from the Text node to the element end tag. If the reader is positioned on an attribute Text node, this method has the same functionality as if the reader were position on the element start tag.

[Note: This method overrides System.Xml.XmlReader.ReadString.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

System.Xml.XmlTextReader Class, System.Xml Namespace

[Note: XmlTextReader does not support entity resolution.

This method overrides System.Xml.XmlReader.ResolveEntity.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Int32 containing the number of attributes on the current node, or zero if the current node does not support attributes.

Description

This property is read-only.

[Note: This property is relevant to the DocumentType , Element , and XmlDeclaration node types of the XmlNodeType enumeration. Other node types do not have attributes.

This property overrides System.Xml.XmlReader.AttributeCount.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

System.Xml.XmlTextReader Class, System.Xml Namespace

A Int32 containing the depth of the current node in the XML document.

Description

This property is read-only.

[Note: This property overrides System.Xml.XmlReader.Depth.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the reader is positioned at the end of the stream; otherwise, false .

Description

This property is read-only.

[Note: This property overrides System.Xml.XmlReader.EOF.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

If the System.Xml.XmlTextReader.ReadState is System.Xml.ReadState.Interactive, a Encoding; otherwise null .

Description

This property is read-only.

If no encoding attribute exists, this property defaults to UTF-8.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the node on which the reader is currently positioned can have an associated text value; otherwise, false .

Description

This property is read-only.

The following members of the XmlNodeType enumeration can have an associated value: Attribute , CDATA , Comment , DocumentType , ProcessingInstruction , SignificantWhitespace , Text , Whitespace , and XmlDeclaration .

[Note: This property overrides System.Xml.XmlReader.HasValue.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

This property always returns the Boolean value false .

Description

This property is read-only.

This property applies only to attribute nodes.

[Note: XmlTextReader does not expand default attributes.

This property overrides System.Xml.XmlReader.IsDefault.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the current node is an element (System.Xml.XmlTextReader.NodeType equals System.Xml.XmlNodeType.Element) that ends with "/>"; otherwise, false .

Description

This property is read-only.

A System.Xml.XmlNodeType.EndElement node is not generated for empty elements.

[Note: This property determines the difference between the following:

<item bar="123"/> (IsEmptyElement is true ).

<item bar="123"> (IsEmptyElement is false ).

This property overrides System.Xml.XmlReader.IsEmptyElement.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

i

A Int32 specifying the zero-based index of the attribute relative to the containing element.

Property Value

A String containing the value of the attribute.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	i is less than 0 or greater than or equal to the System.Xml.XmlTextReader.AttributeCount of the containing element.[Note: System.Xml.XmlTextReader.AttributeCount returns zero for all node types except Attribute , DocumentType , Element , and XmlDeclaration . Therefore, this exception is thrown if the reader is not positioned on one of these node types.]

Description

This property is read-only.

This property does not move the reader.

[Note: This property overrides the XmlReader indexer.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

name

A String specifying the qualified name of the attribute.

Property Value

A String containing the value of the specified attribute, or null if the attribute is not found.

Description

This property is read-only.

This property does not move the reader.

[Note: If the reader is positioned on a DocumentType node, this method can be used to get the PUBLIC and SYSTEM literals.

This property overrides the XmlReader indexer.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

name

A String specifying the local name of the attribute.

namespaceURI

A String specifying the namespace URI of the attribute.

Property Value

A String containing the value of the specified attribute, or null if the attribute is not found.

Description

This property is read-only.

This property does not move the reader.

[Note: This property overrides the XmlReader indexer.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Int32 containing the current line number.

Description

This property is read-only.

The constructors initialize this property to one.

[Note: This property is most commonly used for error reporting, but can be called at any time.

The start of a document is indicated when this property is 1 and the System.Xml.XmlTextReader.LinePosition property is 1.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Int32 containing the current line position.

Description

This property is read-only.

The constructors initialize this property to one, which indicates the first character of text in a line.

[Note: For example, <root>, contains the character 'r' at System.Xml.XmlTextReader.LinePosition equal to 2 and the character '>' at System.Xml.XmlTextReader.LinePosition equal to 6.

This property is most commonly used for error reporting, but can be called at any time.

The start of a document is indicated when this property is 1 and the System.Xml.XmlTextReader.LineNumber property is 1.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the local name of the current node or, for node types that do not have a name (like Text , Comment , and so on), System.String.Empty.

Description

This property is read-only.

The local name is equivalent to System.Xml.XmlTextReader.Name with System.Xml.XmlTextReader.Prefix and the ':' character removed. For example, System.Xml.XmlTextReader.LocalName is "book" for the element <bk:book>.

[Note: This property overrides System.Xml.XmlReader.LocalName.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the qualified name of the current node or, for node types that do not have a name (like Text , Comment , and so on), System.String.Empty.

Description

This property is read-only.

The name returned is dependent on the System.Xml.XmlTextReader.NodeType of the node. The following node types return the listed values. All other node types return an empty string.

Node Type	Name
Attribute	The name of the attribute.
DocumentType	The document type name.
Element	The tag name.
EntityReference	The name of the entity referenced.
ProcessingInstruction	The target of the processing instruction.
XmlDeclaration	The literal string "xml".

[Note: The qualified name is equivalent to the System.Xml.XmlTextReader.LocalName prefixed with System.Xml.XmlTextReader.Prefix and the ':' character. For example, System.Xml.XmlTextReader.Name is "bk:book" for the element <bk:book>.

This property overrides System.Xml.XmlReader.Name.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

The XmlNameTable used by the current instance.

Description

This property is read-only.

The XmlTextReader class stores element and attribute names, prefixes, and namespaces as individual String objects when a document is read.

A qualified name is stored as a unique String instance and separated into its prefix and local name parts, which are also stored as unique strings instances. For example, <somePrefix:someElement>, is stored as three strings, "somePrefix:someElement", "somePrefix", and "someElement".

[Note: This property overrides System.Xml.XmlReader.NameTable.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the namespace URI of the current node or, if no namespace URI is associated with the current node, System.String.Empty.

Description

This property is read-only.

This property is relevant to Element and Attribute nodes only.

[Note: Namespaces conform to the W3C "Namespaces in XML" recommendation, REC-xml-names-19990114.

This property overrides System.Xml.XmlReader.NamespaceURI.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates the reader supports namespaces; otherwise, false . The default is true .

Exceptions

Exception Type	Condition
InvalidOperationException	When attempting to set the property, the System.Xml.XmlTextReader.ReadState was not System.Xml.ReadState.Initial.

Description

This property determines whether the reader supports the XML Namespaces specification (http://www.w3.org/TR/REC-xml-names). If this property is false , namespaces are ignored and the reader allows names to contain multiple colon characters.

If an attempt is made to set this property after a read operation has occurred, a InvalidOperationException is thrown.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Gets the XmlNodeType of the current node.

Property Value

One of the members of the XmlNodeType enumeration representing the type of the current node.

Description

This property is read-only.

This property does not return the following XmlNodeType types: Document , DocumentFragment , Entity , EndEntity , or Notation .

[Note: This property overrides System.Xml.XmlReader.NodeType.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Boolean where true indicates to normalize; otherwise, false . The default is false .

Exceptions

Exception Type	Condition
InvalidOperationException	When attempting to set the property, the current instance has been closed.

Description

This property can be changed at any time before the current instance has been closed and takes affect on the next read operation.

If System.Xml.XmlTextReader.Normalization is set to false , this also disables character range checking for numeric entities. As a result, character entities, such as " &#0", are allowed.

[Note: See "Attribute-Value Normalization" in the W3C XML 1.0 recommendation, REC-xml-19980210.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the namespace prefix associated with the current node.

Description

This property is read-only.

[Note: A namespace prefix is used as a reference for a namespace URI and is defined in an element declaration. For example, <someElement xmlns:bk='someURL'>, defines a prefix name "bk".

This property overrides System.Xml.XmlReader.Prefix.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A Char specifying the quotation mark character (" or ') used to enclose the value of an attribute.

Description

This property is read-only.

This property applies only to an Attribute node.

[Note: This property overrides System.Xml.XmlReader.QuoteChar.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

One of the members of the ReadState enumeration.

Description

This property is read-only.

[Note: This property overrides System.Xml.XmlReader.ReadState.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the text value of the current node.

Description

This property is read-only.

The value returned depends on the System.Xml.XmlTextReader.NodeType. The following table lists node types that have a value to return. All other node types return System.String.Empty.

Node Type	Value
Attribute	The value of the attribute.
CDATA	The content of the CDATA section.
Comment	The content of the comment.
DocumentType	The internal subset.
ProcessingInstruction	The entire content, excluding the target.
SignificantWhitespace	The white space in the scope of xml:space = "preserve".
Text	The content of the text node.
Whitespace	The white space between markup.
XmlDeclaration	The content of the declaration.

[Note: This property overrides System.Xml.XmlReader.Value.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

One of the members of the WhitespaceHandling enumeration. The default is System.Xml.WhitespaceHandling.All (returns both significant and insignificant white space).

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The value to be set is not one of the members of the WhitespaceHandling enumeration.
InvalidOperationException	When setting the property, the System.Xml.XmlTextReader.ReadState is System.Xml.ReadState.Closed.

Description

This property can be changed at any time before the current instance is closed and takes affect on the next read operation.

[Note: Because an instance of the XmlTextReader class does not have DTD information available to it, SignificantWhitespace nodes are only returned within the xml:space="preserve" scope.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

A String containing the current xml:lang scope.

Description

This property is read-only.

[Note: This property represents the xml:lang scope within which the current node resides. For example, the following is an XML fragment with xml:lang set to US English:

<root xml:lang="en-us">

&lt;name>Fred</name>

</root>

When the reader is positioned on the name element, this property returns "en-us".

The returned string is also in the System.Xml.XmlTextReader.NameTable for the reader.

This property overrides System.Xml.XmlReader.XmlLang.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

Sets the XmlResolver used for resolving DTD references.

Property Value

The XmlResolver to use for resolving DTD references.

If this property is set to null , any external DTD or entities encountered by the reader are not resolved.

Description

This property is write-only.

The XmlResolver is used to resolve the location of the file loaded into the reader and also to resolve DTD references. For example, if the XML included the DOCTYPE declaration, <!DOCTYPE book SYSTEM book.dtd>, the reader resolves this external file and ensures that the DTD is well-formed. XmlTextReader does not use the DTD for validation.

This property can be changed at any time and takes affect on the next read operation.

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace

One of the members of the XmlSpace enumeration. If no xml:space scope exists, this property defaults to System.Xml.XmlSpace.None.

Description

This property is read-only.

[Note: The XmlTextReader class has no DTD information available; therefore, SignificantWhitespace nodes are only returned when inside the scope of xml:space = "preserve".

This property overrides System.Xml.XmlReader.XmlSpace.

]

See Also

System.Xml.XmlTextReader Class, System.Xml Namespace