Note: The series assumes that you are familiar with the basics of XML. If you are new to XML, read one of the many fine tutorials on the subject first and then return to this document.
XmlTextWriter BasicsThe XmlTextWriter class supports a non-cached, forward-only means of writing W3C-standard XML data to a file. As a result, it is typically used in cases where the application needs to generate an entire XML file from start to finish. If your application needs dynamic access to specific parts of a file, you will need to use the XmlDocument class (which a future article will cover). Also, the XmlTextWriter class performs no validation on the data being written. Therefore, it is up to the programmer to ensure that any data passed to the XmlTextWriter class is well formed, or standard, XML.
Generating an XML FileYou take the following four basic steps to generate a properly formed XML file with the XmlTextWriter class:
- Instantiate an XmlTextWriter object.
- Write the XML declaration node.
- Write the data.
- Close the file and perform clean-up.
Instantiate an XmlTextWriter ObjectThe XmlTextWriter constructor has three distinct versions:
XmlTextWriter(TextWriter* textWriter); XmlTextWriter(Stream* inputStream, Encoding* encoding); XmlTextWriter(String* fileName, Encoding* encoding);
The first two constructors are useful in situations where you already have a stream object associated with a file. The third constructor allows the code to specify the file name. With this constructor, you must ensure that the file exists and handle any file-level exceptions that the XmlTextWriter throws if it encounters problems with the specified file.
Write the XML Declaration NodeYou write the XML declaration node with the XmlTextWriter::WriteStartDocument method. It is the first line you see in (well-formed) XML files. This node includes such information as the XML version and encoding method used. Here's an example of that node:
<?xml version="1.0" encoding="UTF-8" ?>
Some files do not include this node, but the W3C standards dictate its inclusion. Therefore, you should create a declaration node if your file will be used by other applications or shared with other users who expect standard XML data.
The WriteStartDocument method has only two overloads:
WriteStartDocument(); WriteStartDocument(bool standAlone);
The first version of this method writes the node with only the version attribute (as seen in the previous example), while the second version includes a Boolean value indicating whether you want the standalone attribute explicitly stated and what you want its value to be. Here are a couple of examples of that (where the encoding attribute is based on your locale):
writer->WriteStartDocument(); // produces <?xml version="1.0" encoding="us-ascii"?> writer->WriteStartDocument(true); // produces <?xml version="1.0" encoding="us-ascii" standalone="yes"?> writer->WriteStartDocument(false); // produces <?xml version="1.0" encoding="us-ascii" standalone="no"?>
Write the DataOnce you've written the declaration node, you can write the nodes and attributes that constitute your file's data. There are about a dozen XmlTextWriter methods, so I won't delve into the details of all of them. Rather, I discuss the higher-level process of writing nodes and attributes and give the following examples:
- Starting and ending an element Keeping in mind that the XmlTextWriter is a forward-only writer, you have to write each part of the file as that file will appear. Therefore, if you want to output an element containing an element, an attribute, and a value, then you must make the appropriate calls in that order. To begin that, call the XmlTextWriter::WriteStartElement method. From there, make calls to methods to insert attributes, values, and other elements. Indicate that the element is to be closed via a call to XmlTextWriter::WriteEndElement:
writer->WriteStartElement(S"Article"); // write xml to appear within this element writer->WriteEndElement();
- Writing attributes Within a WriteStartElement/WriteEndElement pair, you can write a given element's attributes. This is done via the XmlTextWriter::WriteAttributeString method. The following snippet writes an attribute called "lang" with a value of "EN" to the element currently being written:
- Writing an element's value There are several different specialized methods for writing the value of the current element. Of these, the most commonly used is the
XmlTextWriter::WriteString method, which writes the specified value to the current element:
writer->WriteString(S"Writing XML Files using the XmlTextWriterClass");
- Writing CDATA If an XML parser will read the data you write, you have to be careful not to break any rules regarding what that data can include. Otherwise, it will confuse the parser. In such cases, specify that the element type is CDATA and write it using the XmlTextWriter::WriteCData method:
- Writing a simple element without attributes or nested elements If you need to write an element containing a value and that element doesn't have any other information associated with it (such as attributes or other nested elements), then you can use the XmlTextWriter::WriteElementString method:
writer->WriteElementString(S"Author", S"Tom Archer");