The XmlTextReader class

Discussion of the properties of the class, with example code.

This Content Component encountered an error


.NET Developer Tip
(Receive this column in your inbox,
click Edit your Profile to subscribe.)

The XmlTextReader class
Peter G. Aitken

The whole reason for Microsoft's .NET framework is to allow the different machines, no matter where they are or who made them, communicate with one another. So it's a good idea, if you're going to be programming for that framework, to understand how one of the universal languages, XML, works in .NET. This tip, excerpted from InformIT, explains one the classes you need for XML, the XMLTextReader Class.


The XmlTextReader class is designed for fast, resource nonintensive access to the contents of an XML file. Unlike the XmlDocument class, the XMLTextReader class does not create a node tree of the entire document in memory. Rather, it processes the XML as a forward-only stream. The entire XML document is never available at the same time (as is the case with the XmlDocument class) -- your code can extract individual items from the XML file as they stream by.

In some ways the XmlTextReader class is similar to the SAX model covered in Chapter 11, and in fact, the .NET programmer would tend to use the XmlTextReader class for the same types of processing that SAX would be used for. There is a major difference between the two models, however. SAX uses a push model in which the XML processor uses events to inform the host program that node data is available, and the program can use the data or not as its needs dictate. The data is pushed from the XML processor to the host, and it can be accepted or ignored. As an analogy, think of a Chinese dim sum restaurant where the available food is brought around on carts and you select what you want.

In contrast, the XmlTextReader class uses a pull model. The host program requests that the XML processor read a node, and then requests data from that node as needed. The host program pulls the data from the processor as it is needed. Pull processing is analogous to a traditional restaurant where you request items from a menu. A pull model has numerous advantages over a push model for XML processing. Perhaps most important is that a push model can easily be built on top of a pull model, while the reverse is not true.

The XmlTextReader class operates by stepping through the nodes of an XML document, one at a time, under the control of the host program. At any given time, there is a current node. For the current node, the host program can determine the type of the node, its attributes (if any), its data, and so on. Once the needed information about the current node has been obtained, the program will step to the next node. In this manner the entire XML file can be processed.

The XmlTextReader class has a large number of public properties and methods. The ones you will need most often are explained in the tables.

Commonly Needed Properties of the XmlTextReader Class

Property Description
AttributeCount Returns the number of attributes of the current node
Depth Returns the depth (nesting level) of the current node.
EOF Returns True if the XML reader is at the end of the file
HasAttributes Returns True if the current node has attributes
HasValue Returne True of the current node can have a value
IsEmptyElement Returns True if the current node is an empty element (for example, <ElementName/>)
Item Returns the value of an attribute
LocalName Returns the name of the current node without any namespace prefix
Name Returns the name of the current name with any namespace prefix
NoteType Returns the type of the current node as an XmlNoteType
Value Returns the value of the current node

Commonly Needed Methods of the XmlTextReader Class

Method Description
Close () Closes the XML file and reinitializes the reader
GetAttribute (att) Gets the value of an attribute. Att is a number specifying the positioin of the attribute, with the first attribute being 0, or a string specifying the name of the attribute
IsStateElement () Returns True if the current node is a start element or an empty element
MoveToAttribute (att) Moves to a specific attribute. Att is a number specifying the position of the attribute, with the first attribute being 0, or a string specifying the name of the attribute
MoveToElement () Moves the current element that contains the current attribute
MoveToFirstAttribute Moves to the first attribute
MoveToNextAttribute Moves to the next attribute
Read () Reads the next node from the XML file. Returns True on success, or False if there are no more nodes to read.

XmlNodeType Values Returned by the NodeType Property

Value Meaning
Attribute An attribute
CDATA A CDATA section
Comment A comment
Document The document node (root element)
DocumentType A DOCTYPE element
Element An element (opening tag)
EndElement The end of an element (closing tag)
EntityReference An entity reference
ProcessingInstruction An XML processing instruction
Text The text content of an element
XmlDeclaration The XML declaration element

The basic steps required to use the XmlTextReader class are as follows:

  1. Create an instance of the class, passing the name of the XML file to process as an argument to the class constructor.
  2. Create a loop that executes the Read() method repeatedly until it returns False, which means that the end of the file has been reached.
  3. In the loop, determine the type of the current node.
  4. Based on the node type, either ignore the node or retrieve node data as needed.

The listing presents an example of using the XmlTextReader class. It is an ASP Web page, with the script components written using the C# language. The script opens an XML file and processes it using the XmlTextReader class. The root element in the file, its child element, and their attributes and data are formatted as HTML and written to the output for display in the browser.

The script defines a class called DisplayXmlFile that does all of the work. This class contains one public method, ReadDoc(), that is passed the name of the XML file to be processed and returns the HTML to be displayed in the document. It also contains two private methods: ProcessXml(), which performs the actual processing of the XML file, and Spaces(), which is a utility function to provide indentation to format the output.

The script also contains a procedure named Page_Load(). This is an event procedure that is called automatically when the browser first loads the page. Code in this procedure creates an instance of the DisplayXml class, and then calls its ReadDoc() method, passing the name of the XML file to be processed. The HTML returned by this method is displayed by assigning it to the InnerHTML property of a <div> element in the page.

Listing: Using the XmlTextReader Class to Read Data from an XML File

<%@ Import Namespace="System.Xml" %>
<script language="C#" runat=server>
 public class DisplayXmlFile
 // This is the class that reads and processes the XML file.
 {
  StringBuilder result = new StringBuilder();
  public string ReadDoc(String XmlFileName) {
   XmlTextReader xmlReader = null;
 try {
   // Create an instance of the XMLTextReader.
   xmlReader = new XmlTextReader(XmlFileName);
   // Process the XML file.
   ProcessXml(xmlReader);
   }
 catch (Exception e){
   result.Append("The following error occurred: " + 
      e.ToString());
   }    
    finally 
   {
   if (xmlReader != null)
   xmlReader.Close();
   }
    return result.ToString();
  }
 private void ProcessXml(XmlTextReader xmlReader) {
  // This method reads the XML file and generates the output HTML.
  while (xmlReader.Read()) {
  // Process a start of element node.
  if (xmlReader.NodeType == XmlNodeType.Element) {
   result.Append(spaces(xmlReader.Depth*3));
   result.Append("<" + xmlReader.Name);
   if (xmlReader.AttributeCount > 0) {
    while (xmlReader.MoveToNextAttribute()) {
     result.Append(" " + xmlReader.LocalName + 
      "=<font color=#0000ff>" + xmlReader.Value +
      "</font> ");
    }
   }
    result.Append("><br>");
  // Process an end of element node.
  } else if (xmlReader.NodeType == XmlNodeType.EndElement) {
    result.Append(spaces(xmlReader.Depth*3));
    result.Append("</" + xmlReader.Name + "><br>");
  // Process a text node.
  } else if (xmlReader.NodeType == XmlNodeType.Text) {
    if (xmlReader.Value.Length != 0) {
     result.Append(spaces(xmlReader.Depth*3));
     result.Append("<font color=#0000ff>" + xmlReader.Value + 
       "<br></font>");
  }
  }
 }
 }

private string spaces(int n) {
// Returns the specified number of non-breaking
// spaces ( ).
  string s = "";
  for (int i=0; i < n; i++) { 
  s += " ";
 }
  return s;
 }
} //End DisplayXmlFile Class
private void Page_Load(Object sender, EventArgs e){
  // Create a class instance.
  DisplayXmlFile DisplayXmlFileDemo = new DisplayXmlFile();
  // Add the HTML generated by the class to the HTML document.
  show.InnerHtml = DisplayXmlFileDemo.ReadDoc(Server.MapPath("list1506.xml"));
}
</script>
<html>
<head>
</head>
<body>
 <font size="4">Using the XmlTextReader Class</font><p>
 <div id="show" runat="server"/>
</body>
</html>

To read the article from which this tip is excerpted, click over to InformIT. You have to register there, but the registration is free.

For More Information:

  • Looking for free research? Browse our comprehensive White Papers section by topic, author or keyword.
  • Are you tired of technospeak? The Web Services Advisor column uses plain talk without the hype.
  • For insightful opinion and commentary from today's industry leaders, read our Guest Commentary columns.
  • Hey Codeheads! Start benefiting from other time-saving XML Developer Tips and .NET Developer Tips.
  • Visit our huge Best Web Links for Web Services collection for the freshest editor-selected resources.
  • Choking on the alphabet soup of industry acronyms? Visit our helpful Glossary for the latest lingo.
  • Visit Ask the Experts for answers to your Web services, SOAP, WSDL, XML, .NET, Java and EAI questions.
  • Discuss this issue, voice your opinion or just talk with your peers in the SearchWebServices Discussion Forums.

This was first published in February 2003

Dig deeper on Microsoft .NET Web services

Pro+

Features

Enjoy the benefits of Pro+ membership, learn more and join.

0 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

-ADS BY GOOGLE

SearchSoftwareQuality

SearchCloudApplications

SearchAWS

TheServerSide

SearchWinDevelopment

Close