- .NET Overview
- The System.XML Assembly
- The XmlTextReader Class
- The XmlValidatingReader Class
- The XmlTextWriter Class
- The XmlDocument Class
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
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 Table 13.1 and Table 13.2.
Table 13.1 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 |
Returns True if 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 node with any namespace prefix |
|
NodeType |
Returns the type of the current node as an XmlNodeType (see Table 13.3) |
|
Value |
Returns the value of the current node |
Table 13.2 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 position of the attribute, with the first attribute being 0, or a string specifying the name of the attribute. |
|
IsStartElement() |
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 to the 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. |
Table 13.3 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:
Create an instance of the class, passing the name of the XML file to process as an argument to the class constructor.
Create a loop that executes the Read() method repeatedly until it returns False, which means that the end of the file has been reached.
In the loop, determine the type of the current node.
Based on the node type, either ignore the node or retrieve node data as needed.
Listing 13.1 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.
Figure 13.1 shows the output when this script is used to process Listing1506.xml, an XML file that is presented in Chapter 15. Though not visible in the figure, the data (attribute and element values) are displayed in blue while the remainder of the document is in black.
){kind=link}
Figure 13.1 An XML file displayed in Internet Explorer by the script in Listing 13.1
Listing 13.1 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>