The XmlTextReader.ReadState property provides read-only access to the current state of the XmlTextReader. Upon creation, the XmlTextReader has a state of Initial. The state changes to Interactive once read operations are performed. The XmlTextReader will maintain an Interactive state until the end of the input file is reached or an error occurs. The ReadState property returns one of the following values from the System.Xml.ReadState enumeration, listed in Table 11-4.

If a source stream contains more than one XML document, the ResetState method must be used to reinitialize the XmlTextReader prior to parsing the second and subsequent documents; the ResetState method sets the ReadState property to ReadState.Initialized.

The XmlTextReader has a number of properties that control the way XML files are parsed. Table 11-5 summarizes these properties.

The Namespaces property must be set before the first read operation (when the ReadState property is ReadState.Initial), or an InvalidOperationException will be thrown; the other properties can be set at any time while the XmlTextReader is not in a ReadState.Closed state and will affect future read operations.

As the XmlTextReader reads a node, it identifies the node type. Each node type is assigned a value from the System.Xml.XmlNodeType enumeration. The XmlTextReader.NodeType property returns the type of the current node.

The node types include those defined in the W3C "DOM Level 1 Core" specification and five nonstandard extension types added by Microsoft. Node type values that can be returned by XmlTextReader.NodeType include the following—those that are not defined in DOM are italicized: Attribute, CDATA, Comment, DocumentType, Element, EndElement, EntityReference, None, ProcessingInstructions, SignificantWhitespace, Text, Whitespace, and XmlDeclaration. The additional node types defined by Microsoft are summarized in Table 11-6.

The Name and LocalName properties of the XmlTextReader return names of the current node. The Name property returns the qualified node name, including any namespace prefix. The LocalName property returns the node name with any namespace prefix stripped off. The name returned by the Name and LocalName properties depends on the current node type, summarized by the following list:

The XmlTextReader.Prefix property returns the namespace prefix of the current node, or String.Empty if it doesn’t have one.

The XmlTextReader.Value property returns the text value of the current node. The value of a node depends on the node type and is summarized in the following list:

The XmlTextReader.HasValue property returns true if the current node is a type that returns a value; otherwise, it returns false.

Other information about the current node available through XmlTextReader properties is summarized in Table 11-7.

Operations that change the location of the cursor are collectively referred to as read operations. All read operations move the cursor relative to the current node. Note that while attributes are nodes, they are not returned as part of the normal node stream and never become the current node using the read operations discussed in this section; accessing attribute nodes is covered in the following section.

The simplest cursor operation is the XmlTextReader.Read method, which attempts to move the cursor to the next node in the XML source and returns true if successful. If there are no further nodes, Read returns false. The following code fragment visits every node in an XmlTextReader and displays the node name on the console:

XmlTextReader rdr = new XmlTextReader("MyXmlFile.xml");
while (rdr.Read()) {
    System.Console.WriteLine("Inspecting node : {0}", rdr.Name);
}

Using the Read method is the simplest way to process the nodes in an XML document but is often not the desired behavior because all nodes, including noncontent and EndElement nodes, are returned.

The MoveToContent method determines whether the current node is a content node. Content nodes include the following node types: Text, CDATA, Element, EndElement, EntityReference, and EndEntity. If the current node is a noncontent node, the cursor skips over all nodes until it reaches a content node or the end of the XML source. The MoveToContent method returns the XmlNodeType of the new current node (XmlNodeType.None if the end of the input is reached).

The Skip method causes the cursor to be moved to the next sibling of the current node; all child nodes will be ignored. For nodes with no children, the Skip method is equivalent to calling Read.

The IsStartElement method calls MoveToContent and returns true if the current node is a start tag or an empty element. Overloaded versions of the IsStartElement method support the provision of a name or local name and a namespace URI; if names are specified, the method will return true if the new current node name matches the specified name. The following code fragment demonstrates the use of IsStartElement to display the name of each element start tag:

XmlTextReader rdr = new XmlTextReader("MyXmlFile.xml");
while (rdr.Read()) {
    if (rdr.IsStartElement()) {
        System.Console.WriteLine("Inspecting node : {0}", rdr.Name);
    }
}

The ReadStartElement method calls IsStartElement followed by the Read method; if the result of the initial call to IsStartElement is false, an XmlException is thrown. ReadStartElement provides the same set of overloads as IsStartElement, allowing an element name to be specified.

The ReadEndElement method checks that the current node is an end tag and then advances the cursor to the next node; an XmlException is thrown if the current node is not an end tag.

The XmlTextReader also includes a number of methods to return content from the current node and its descendants; these are summarized in Table 11-8.

The attribute values of the current node can be accessed through the XmlTextReader class using both methods and indexers; the attribute is specified either by name or by index position. A URI can be specified for attributes contained in a namespace. The members used to access attribute values are summarized in Table 11-9.

The XmlTextReader class provides support for accessing attributes as independent nodes, allowing attribute information to be accessed using the XmlTextReader class properties described earlier in this section.

If the current node has attributes, the XmlTextReader.MoveToFirstAttribute method returns true and moves the cursor to the first attribute of the current node; the first attribute becomes the current node. If the current node has no attributes, the method returns false and the cursor remains unmoved.

Once the cursor is positioned on an attribute node, calling MoveToNextAttribute will move it to the next attribute node. If another attribute exists, the method will return true; otherwise, the method returns false and the position of the cursor remains unchanged. If the current node is not an attribute, but a node with attributes, the MoveToNextAttribute method has the same effect as MoveToFirstAttribute.

The MoveToAttribute method provides three overloads for moving the cursor directly to a specific attribute node. These overloads are summarized in Table 11-10.

The MoveToElement method moves the cursor back to the node containing the attributes.

The following example demonstrates attribute access using both direct and node access. The example class parses an XML file loaded from the http://localhost/test.xml URL and determines whether any element type node contains an attribute named att1. If the att1 attribute is present, the program displays its value on the console; otherwise, the program displays a list of all attributes and values of the current element.

XML Input (assumed to be located at http://localhost/test.xml):

<?xml version='1.0'?>
<root>
    <node1 att1='abc' att2='def'/>
    <node2 att2='ghi' att3='jkl' att4='mno'/>
    <node3 att1='uvw' att2='xyz'/>
</root>

Example code:

using System;
using System.Xml;

public class xmltest {

    public static void Main () {

        String myFile = "http://localhost/test.xml";
        XmlTextReader rdr = new XmlTextReader(myFile);

        while (rdr.Read()) {
            if (rdr.NodeType == XmlNodeType.Element) {
                Console.WriteLine("Inspecting node : {0}",rdr.Name);


                if (rdr["att1"] != null){
                    Console.WriteLine("	att1 =  {0}",rdr["att1"]);
                } else {
                    while(rdr.MoveToNextAttribute()) {
                        Console.WriteLine("	{0} = {1}",
                            rdr.Name, rdr.Value);
                    }
                    rdr.MoveToElement();
                }
            }
        }
    }
}

Output:

Inspecting node : root
Inspecting node : node1
        att1 =  abc
Inspecting node : node2
        att2 = ghi
        att3 = jkl
        att4 = mno
Inspecting node : node3
        att1 =  uvw