Wednesday, October 12, 2011

Creating XML Documents with the XmlTextWriter Class

Introduction


As XML's popularity and use in Web-enabled applications continues to rise, it is becoming more and more important to have a good understanding of how to create, consume, and alter XML documents through .NET. In simplest terms, an XML file is really nothing more than a bulky text file, and prior to .NET, many ASP developers, when needing to generate an XML file on the fly, simply Response.Writed out the content of the XML document.

While Response.Write-ing an XML file works, it is far from ideal for a number of reasons. First, since it composes an XML document with strings, one has to worry about escaping those characters that are illegal in XML. There are a number of illegal characters that cannot appear in the text portion of an XML document. These are <, >, &, ", and '. When generating an XML document as a string, you have to manually search for these illegal characters and escape them. Second, with complex XML documents with many namespaces, attributes, and elements, the code necessary to Response.Write out the document can become cryptic.
Fortunately, the .NET Framework provides a class designed specifically to create XML documents, the System.Xml.XmlTextWriter class. By using this class to create XML documents you don't need to worry about illegal XML characters in the text portion of the XML document, and the end code is much cleaner. In this article we'll look at using the XmlTextWriter class to create XML documents on the fly.

For More Information on XML...
This article assumes the reader has a basic understanding of XML. If you are new to XML, I would encourage you to first read What is XML? and Getting Started with XML before continuing on with this article.


The Basics of the XmlTextWriter Class


The XmlTextWriter class contains a number of methods that are useful for starting and completing an XML document and for adding elements and attributes to the XML document. The most important methods are:
  • WriteStartDocument() - you should call this method to start creating an XML document. This will create the first line in the XML document, specifying that the file is an XML document and its encoding.
  • WriteStartElement(string) - this method creates a new element in the XML document with the name specified by the string input parameter. (You can also specify a namespace as a second, optional string parameter.)
  • WriteElementString(name, text_value) - If you want to create an XML element with nothing but text content (i.e., no nested elements), you can use this method.
  • WriteAttributeString(name, value) - this method writes an attribute name and value to the current element.
  • WriteEndElement() - this method closes off the element created in the WriteStartElement(string) method call.
  • WriteEndDocument() - this method completes the writing of the XML document.
  • Close() - this method closes the underlying stream, writing the contents of the XML document to the specified file location.
To get started using the XmlTextWriter class you need to specify the file and encoding in the class's constructor. The encoding needs to be of the type System.Text.Encoding; some example encoding values are: System.Text.Encoding.ASCII, System.Text.Encoding.Unicode, and System.Text.Encoding.UTF8. Alternatively, you can specify in the constructor that the output of the XmlTextWriter class should be squirted out to a specified Stream.

Creating a Simple XML Document with XmlTextWriter


To demonstrate using the XmlTextWriter class let's create a simple XML document, saving it to a specified file location. This XML document will contain information about the current user visiting the page, and will have this structure: 
<userInfo>
  <browserInfo>    
    <urlReferrer>URL referrer info</urlReferrer>
    <userAgent>User agent referrer info</userAgent>
    <userLanguages>languages info</userLanguages>
  </browserInfo>
  <visitInfo timeVisited="date/time the page was visited">
    <ip>visitor's IP address</ip>
    <rawUrl>raw URL requested</rawUrl>
  </visitInfo>
</userInfo>

(This XML file structure was chosen so that it would illustrate using all of the XmlTextWriter methods discussed in the previous section.)
The code needed to create this XML document through an ASP.NET Web page is shown below: 

<%@ Import Namespace="System.Xml" %>
<%@ Import Namespace="System.Text" %>
<script language="C#" runat="server">
void Page_Load(object sender, EventArgs e)
{
  // Create a new XmlTextWriter instance
  XmlTextWriter writer = new 
       XmlTextWriter(Server.MapPath("userInfo.xml"), Encoding.UTF8);
    
  // start writing!
  writer.WriteStartDocument();
  writer.WriteStartElement("userInfo");
   
    // Creating the <browserInfo> element
    writer.WriteStartElement("browserInfo");
    
    if (Request.UrlReferrer == null)
     writer.WriteElementString("urlReferrer", "none");
   else
     writer.WriteElementString("urlReferrer", 
                      Request.UrlReferrer.PathAndQuery);
    
      writer.WriteElementString("userAgent", Request.UserAgent);
      writer.WriteElementString("userLanguages", 
                       String.Join(", ", Request.UserLanguages));
    writer.WriteEndElement();
   
    // Creating the <visitInfo> element
    writer.WriteStartElement("visitInfo");
      writer.WriteAttributeString("timeVisited", DateTime.Now.ToString());
      writer.WriteElementString("ip", Request.UserHostAddress);
      writer.WriteElementString("rawUrl", Request.RawUrl);
    writer.WriteEndElement();   
   
  writer.WriteEndElement();
  writer.WriteEndDocument();
  writer.Close();    
}

[View a Live Demo!]
First, notice that the System.Xml and System.Text namespaces have been imported. The Page_Load event handler begins by creating a new XmlTextWriter instance, indicating that its content should be saved to the file userInfo.xml and that its encoding should be UTF8 (a translation of 16-bit unicode encoding into 8-bits). Note that for each element with nested elements a WriteStartElement(elementName) method is called, along with a matching WriteEndElement() after the inner content has been renderred. Furthermore, the WriteElementString(elementName, textValue) is used for those elements with just text content.

Emitting XML Content to the Browser Window Directly


The previous example demonstrates how to use the XmlTextWriter class to create an XML document and persist it to a file. While this may be precisely what you are after, oftentimes when creating an XML document in an ASP.NET Web page we want to emit the XML content's to the client requesting the Web page. While this could be done in the previous example by opening the userInfo.xml file after creating it and then Response.Write()ing its contents out, this approach is a bit of a hack. A better approach is to have the results of the XmlTextWriter emitted directly to the output stream. This can be accomplished quite easily, by changing one line of code in the previous code sample. In the XmlTextWriter constructor, rather than specifying a file path, we can specify a Stream. Specifically, we want to specify Response.OutputStream. When doing this you will need to make another small change to the ASP.NET Web page. In the <@ Page ... > directive you need to indicate the page's MIME type as text/xml. If you don't do this, some browsers may think the data being sent is for a standard HTML Web page, and will attempt to format the XML document just as they would an HTML page (which will hide the XML elements and remove all whitespace).
The following code shows an abbreviated version of the previous code sample, with the changes in bold. 

<%@ Page ContentType="text/xml" %>
<%@ Import Namespace="System.Xml" %>
<%@ Import Namespace="System.Text" %>
<script language="C#" runat="server">
void Page_Load(object sender, EventArgs e)
{
  // Create a new XmlTextWriter instance
  XmlTextWriter writer = new 
       XmlTextWriter(Response.OutputStream, Encoding.UTF8);
    
  // start writing!
  ...
}

[View a Live Demo!]
Notice that by viewing the live demo you are shown an XML document (even though you are visiting an ASP.NET Web page). This is the same XML document that, in the previous code sample, was saved to userInfo.xml.

Conclusion


In this article we examined how to create an XML document using the System.Xml.XmlTextWriter class of the .NET Framework. The XmlTextWriter class can persist its generated XML document to a file location or a specified stream, in a number of encodings. Using the XmlTextWriter class has many advantages over building up an XML document one string at a time. The main ones being more legible code and not needing to worry about escaping illegal XML characters.