Writing Other Nodes

In most cases your XML will consist of only elements and attributes, but there are situations where you may need to add comments, CDATA, or other uncommon nodes to your XML document.

Writing Comments

Let's first look at writing comments. Comments can appear anywhere in the document after the prolog (everything before the root element) and even in the epilog (everything after the root element). Although the W3C XML specification states that a comment may appear anywhere in the document, even before the prolog, this is not true for documents created by the XmlTextWriter . Attempting to write a comment before writing an XML declaration will result in an InvalidOperationException . Listing 10.33 demonstrates how to add a comment to an XML document.

Listing 10.33

 C# public static void Main() {   XmlTextWriter writer =     new XmlTextWriter("xmlconvert.xml", Encoding.UTF8);   writer.Formatting = Formatting.Indented;   writer.Indentation = 2;   // We can't write a comment here!!!   writer.WriteStartDocument(true);   writer.WriteComment("After prolog, before root");   writer.WriteStartElement("root");   writer.WriteComment("Inside root element");   writer.WriteEndElement();   writer.WriteComment("After the root element");   writer.Close(); } VB sub  Main()   Dim writer As     New XmlTextWriter("xmlconvert.xml", Encoding.UTF8)   writer.Formatting = Formatting.Indented   writer.Indentation = 2   ' We can't write a comment here!!!   writer.WriteStartDocument(true)   writer.WriteComment("After prolog, before root")   writer.WriteStartElement("root")   writer.WriteComment("Inside root element")   writer.WriteEndElement()   writer.WriteComment("After the root element")   writer.Close() End Sub Output <?xml version="1.0" encoding="utf-8" standalone="yes"?> <!--After prolog, before root--> <root>   <!--Inside root element--> </root> <!--After the root element--> 

Listing 10.33 is fairly simple. Each call to WriteComment accepts a string parameter. The resulting comment takes the form <!-- string --> . An ArgumentException will be thrown if the string parameter will result in the comment's ending in ---> or if the string contains a double hyphen ( -- ).

Comments can be very useful. They can improve the readability of the XML document and improve the organization of your documents. That said, comments are primarily for humans . They do very little to help XML processors and will increase the size of your document. So, if speed and size are important to you, use comments sparingly.

Writing CDATA Sections

CDATA sections are used to escape blocks of text containing characters that would otherwise be recognized as markup. Left angle brackets and ampersands need not and cannot be avoided by using their character entity counterparts. Also, CDATA sections cannot be nested. CDATA sections take on the form <!CDATA[ string ]]> . The only text within a CDATA section that is recognized as markup is the CDATA section end tag, ]]> . Therefore, attempting to write a string that contains ]]> will raise an InvalidOperationException .

CDATA sections can appear anywhere character data may be used. This does not include the prolog or the epilog, only inside the root element where character data may appear.

CDATA is useful when text is produced from an external source and you want your document to include this data without parsing and without breaking the well- formedness of your document. Listing 10.34 demonstrates how to write a CDATA section by using the WriteCData method.

Listing 10.34

 C# public static void Main() {   XmlTextWriter writer =     new XmlTextWriter("xmlconvert.xml", Encoding.UTF8);   writer.Formatting = Formatting.Indented;   writer.Indentation = 2;   // We can't write a CDATA section in the prolog!!!   writer.WriteStartDocument(true);   writer.WriteStartElement("root");   writer.WriteCData("Inside root element");   writer.WriteEndElement();   // We can't write a CDATA section in the epilog!!!   writer.Close(); } VB sub Main()   Dim writer =     New XmlTextWriter("xmlconvert.xml", Encoding.UTF8)   writer.Formatting = Formatting.Indented   writer.Indentation = 2   ' We can't write a CDATA section in the prolog!!!   writer.WriteStartDocument(True)   writer.WriteStartElement("root")   writer.WriteCData("Inside root element")   writer.WriteEndElement()   ' We can't write a CDATA section in the epilog!!!   writer.Close() End Sub