Presents your 
XML E-NEWSLETTER for April 30, 2003

<------------------------------------------->

UNDERSTAND XML FORMATTING OPTIONS IN .NET

The Microsoft XML parser included in the .NET environment offers many
useful features for formatting your documents. You can use these features
to change the behavior of the XML writer used to create new XML documents.
You can also alter the way the parser renders white space and
indentions, as well as the document's character encoding and attribute 
quoting.

SAMPLE DOC

Throughout this article, we'll reference the sample VB.NET code in
LISTING A, which creates a simple XML document:

Listing A
xmlWriter = New XmlTextWriter(filename, Nothing)
xmlWriter.WriteStartElement("Order")

xmlWriter.WriteStartElement("Item")
xmlWriter.WriteAttributeString("id", "1")
xmlWriter.WriteElementString("SKU", "998123")
xmlWriter.WriteElementString("Description", "Super Widget")
xmlWriter.WriteElementString("Quantity", "100")
xmlWriter.WriteEndElement()

xmlWriter.WriteStartElement("Item")
xmlWriter.WriteAttributeString("id", "2")
xmlWriter.WriteElementString("SKU", "81312")
xmlWriter.WriteElementString("Description", "Turbo Flangellator")
xmlWriter.WriteElementString("Quantity", "50")
xmlWriter.WriteEndElement()

xmlWriter.WriteEndElement()
xmlWriter.Close()

This code requires you to specify a filename, which is obtained from a
SaveFileDialog component or simply hard-coded. The output of this code 
is shown in LISTING B.

Listing B: sample.xml
<Order><Item id="1"><SKU>998123</SKU><Description>Super
Widget</Description><Quantity>100</Quantity></Item><Item
id="2"><SKU>81312</SKU><Description>Turbo
Flangellator</Description><Quantity>50</Quantity></Item></Order>

INDENTING

There are three settings you can use to change the way your documents
are indented. To start with, we'll use the XmlTextWriter class. This class
contains a set of properties called Formatting, Indentation, and IndentChar.

Use the Formatting property to set the indentation of the XML document
or to determine whether it will be indented. The parser will automatically
embed indents into your XML document to make it easier to view in
text-oriented viewers.

The Indentation property sets the number of spaces that make up an
indent. The default setting is two spaces.

The IndentChar property allows you to modify the character used to fill
the indent. This is a space character by default, but it could be any
character you specify. Of course, characters that aren't white spaces will
invalidate your XML document, but may be useful for debugging or some
other process.

Let's apply these properties to our sample code above, as shown in
LISTING C. We specify that the output document should be indented (unlike the
sample in LISTING B); that the indentation should be four spaces; and
that the indentation character should be a space.

Listing C
xmlWriter = New XmlTextWriter(filename, Nothing)

xmlWriter.Formatting = Formatting.Indented
xmlWriter.Indentation = 4
xmlWriter.IndentChar = " "c

xmlWriter.WriteStartElement("Order")

xmlWriter.WriteStartElement("Item")
xmlWriter.WriteAttributeString("id", "1")
xmlWriter.WriteElementString("SKU", "998123")
xmlWriter.WriteElementString("Description", "Super Widget")
xmlWriter.WriteElementString("Quantity", "100")
xmlWriter.WriteEndElement()

xmlWriter.WriteStartElement("Item")
xmlWriter.WriteAttributeString("id", "2")
xmlWriter.WriteElementString("SKU", "81312")
xmlWriter.WriteElementString("Description", "Turbo Flangellator")
xmlWriter.WriteElementString("Quantity", "50")
xmlWriter.WriteEndElement()

xmlWriter.WriteEndElement()
xmlWriter.Close()

The results are shown in LISTING D:

Listing D: sample2.xml
<Order>
    <Item id="1">
        <SKU>998123</SKU>
        <Description>Super Widget</Description>
        <Quantity>100</Quantity>
    </Item>
    <Item id="2">
        <SKU>81312</SKU>
        <Description>Turbo Flangellator</Description>
        <Quantity>50</Quantity>
    </Item>
</Order>

QUOTING

In addition to indent formatting, you can also change the way that
attributes are quoted. The QuoteChar property allows you to manipulate the
character used to surround attribute entries. The default value is a double
quote, but you may want to change this to a single quote. The QuoteChar
property lets you choose a quotation character; however, as with the
IndentChar property, it's possible to specify values for the quotation
character that invalidate your XML document.

ENCODING

You can also modify the encoding used in your output document. This is
not a setting you change via a property. Instead, you specify the encoding
in the constructor for the XmlTextWriter class. You can set the encoding
to any value available from System.Text.Encoding. The available values are:

* System.Text.Encoding.ASCII
* System.Text.Encoding.BigEndianUnicode
* System.Text.Encoding.Default
* System.Text.Encoding.Unicode
* System.Text.Encoding.UTF7
* System.Text.Encoding.UTF8

In most instances, you will want to use the System.Text.Encoding.Default
setting. However, you may wish to specify a different setting, depending
on where the document is being sent.

Brian Schaffner is an associate director for Fujitsu Consulting. He provides
architecture, design, and development support for Fujitsu's Technology
Consulting practice.

----------------------------------------