Tip

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

    Requires Free Membership to View

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

PropertyDescription
AttributeCountReturns the number of attributes of the current node
DepthReturns the depth (nesting level) of the current node.
EOFReturns True if the XML reader is at the end of the file
HasAttributesReturns True if the current node has attributes
HasValueReturne True of the current node can have a value
IsEmptyElementReturns True if the current node is an empty element (for example, <ElementName/>)
ItemReturns the value of an attribute
LocalNameReturns the name of the current node without any namespace prefix
NameReturns the name of the current name with any namespace prefix
NoteTypeReturns the type of the current node as an XmlNoteType
ValueReturns the value of the current node

Commonly Needed Methods of the XmlTextReader Class

MethodDescription
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
MoveToFirstAttributeMoves to the first attribute
MoveToNextAttributeMoves 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

ValueMeaning
AttributeAn attribute
CDATAA CDATA section
CommentA comment
DocumentThe document node (root element)
DocumentTypeA DOCTYPE element
ElementAn element (opening tag)
EndElementThe end of an element (closing tag)
EntityReferenceAn entity reference
ProcessingInstructionAn XML processing instruction
TextThe text content of an element
XmlDeclarationThe 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

There are Comments. Add yours.

 
TIP: Want to include a code block in your comment? Use <pre> or <code> tags around the desired text. Ex: <code>insert code</code>

REGISTER or login:

Forgot Password?
By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy
Sort by: OldestNewest

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:

Disclaimer: Our Tips Exchange is a forum for you to share technical advice and expertise with your peers and to learn from other enterprise IT professionals. TechTarget provides the infrastructure to facilitate this sharing of information. However, we cannot guarantee the accuracy or validity of the material submitted. You agree that your use of the Ask The Expert services and your reliance on any questions, answers, information or other materials received through this Web site is at your own risk.