The XmlTextReader class

.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

Commonly Needed Methods of the XmlTextReader Class

XmlNodeType Values Returned by the NodeType Property

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.