AxDa.EnhancedXmlWriter 1.0.1

Enhanced XML Writer for .NET

Enhanced XML Writer for .NET provides high-performance, low-allocating, and standards-compliant capabilities for serializing a Microsoft LINQ to XML document object tree to XML text.

XML has been widely adopted as a way to format data in many contexts. For example, you can find XML on the Web, in configuration files, in Microsoft Office Word files, and in databases.

Enhanced XML Writer for .NET is an up-to-date, redesigned approach to serializing LINQ to XML document trees. It provides powerful serialization options and empowers developers to create standards-compliant XML from LINQ to XML trees.

XmlWriter overview

Enhanced XML Writer for .NET is a highly efficient implementation, providing high-performance, low-allocating, and standards-compliant capabilities for serializing a Microsoft LINQ to XML document object tree to XML text.

The most important advantage of Enhanced XML Writer for .NET is its strict compliance to XML standards, mending the flaws and inaccuracies the Microsoft XmlWriter suffers from, particularly in regard to white-space preserved content. You should use the Enhanced XML Writer whenever you want to serialize business critical XML data.

The AxDa.EnhancedXmlWriter.XmlWriter object comes with a single method: Write(), and WriteAsync() for asynchronous write operations. The Write() and WriteAsync() methods will serialize the LINQ to XML object tree either to a Stream or a StringBuilder object.

XmlWriterOptions overview

Another advantage of Enhanced XML Writer for .NET is the ability to provide formatting conventions to particular XML tags. You can, for example, apply default white-space preserve behavior to an XML tag. It then will automatically be serialized as if xml:space="preserve" would have been specified in the XML source for that particular tag. This is particularly powerful when serializing HTML, where the pre tag is by default rendered with white-space preserved.

Use the XmlWriterOptions object to specify serialization conventions and options, like indentation or new-line character style, for example.

Following is a simple example, exporting a LINQ to XML document with pre elements being serialized as xml:space="preserve":

using A = AxDa.EnhancedXmlWriter;

XDocument xDoc = new XDocument();
xDoc.Load(@"C:\Data\MyWebPage.html");

A.XmlWriterOptions options = new A.XmlWriterOptions()
{
  OmitXmlDeclaration = true,
  Indentation = true,
  IndentationString = "  "
};
options.ElementFeatures.Add(XName.Get("pre"), ContentType.PreserveWhitespace);

MemoryStream ms = new MemoryStream();
new A.XmlWriter(options).Write(ms);

Export LINQ to XML documents

Exporting XML stored in a LINQ to XML object tree is simple: Just create a new Enhanced XML Writer object, assign a LINQ to XML XDocument object to it and run one of the Write() or WriteAsync() methods.

Example

using System.IO;
using System.Xml.Linq;

using A = AxDa.EnhancedXmlWriter;

using MemoryStream ms = new MemoryStream();
XDocument xDoc = new XDocument(new XElement
                                ("root"
                                , new XElement("child")
                                )
                              );

new A.XmlWriter(xDoc).Write(ms);

ms.Position = 0L;
string xmlString = new StreamReader(ms).ReadToEnd();

This example produces the following output:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <child/>
</root>

Options

Enhanced XML Writer for .NET provides a powerful set of features for customizing how Enhanced XML Writer serializes a LINQ to XML object tree, enabling developers to produce high-quality results.

The XmlWriterOptions object offers a rich set of properties, providing for versatile XML output.

The full list of option properties is as follows:

XmlWriterOptions Properties

<dl> <dt>DefaultSpaceHandling</dt> <dd>

Gets or sets a value determining the default kind of white-space serialization for the XML object tree stored in the XDocument when no "xml:space" declaration is present in the XML.

Typically, this value is WhiteSpaceHandling.Default.

In case you need literal white-space serialization for the whole XML object tree stored in the XDocumentand don't want to alter the XML object tree stored in the XDocument, set this property to WhiteSpaceHandling.Preserve. It will emulate an xml:space="preserve" attribute being present in the root object of the XML tree.</dd>

<dt>ElementFeatures</dt> <dd>

Using this property, you can apply particular traits to element names.

For example, in HTML the <pre> element is specified with xml:space="preserve" assumed without explicitly declaring this attribute in the document tree. You can add this trait to the <pre> element by specifying it in the ElementFeatures collection. Same for the <code> inline element:

XmlWriterOptions options = new XmlWriterOptions();

options.ElementFeatures.Add(XName.Get("pre"), ContentType.PreserveWhitespace);
options.ElementFeatures.Add(XName.Get("code"), ContentType.PreserveWhitespace);

This will emulate the xml:space="preserve" being added to these element names.

Some XML elements names may be specified as not to contain text but only child elements. To make sure these elements will not serialize any text you can apply the ContentType.ChildrenOnly trait to these element names:

XmlWriterOptions options = new XmlWriterOptions();

options.ElementFeatures.Add(XName.Get("Section", xamlNS), ContentType.ChildrenOnly);
options.ElementFeatures.Add(XName.Get("Paragraph", xamlNS), ContentType.ChildrenOnly);

This will enforce that no text will be serialized for these element names.</dd>

<dt>OmitXmlDeclaration</dt> <dd>

If true, Enhanced XML Writer does not prepend the XML tree with an XML declaration.

This is useful when serializing an HTML document tree.

The default value is false.</dd>

<dt>OmitDuplicateNamespaces</dt> <dd>

If true, Enhanced XML Writer will not serialize namespace declaration attributes merely repeating their ancestors' namespace declarations.

The default value is true.</dd>

<dt>Indent</dt> <dd>

If true, prettifies the serialized XML document by adding a new-line after each XML element and indenting it appropriately.

The default value is true.</dd>

<dt>IndentationString</dt> <dd>

A string specifying the white-space to be used for indentation.

The default value is a string representing two space characters.</dd>

<dt>NewLineChar</dt> <dd>

A string specifying the new-line character sequence to be used within the serialized XML document.

When serializing the XML document, all different kinds of new-line character sequences will be harmonized and substituted with this single new-line character sequence in the resulting text stream.

The default value is the system new-line character sequence (Environment.NewLine).</dd> </dl>

Motivation For Writing a New XML Writer

The current implementation of the Microsoft XmlWriter class (.NET ⇐ v10.0) has a couple of issues, causing it to fail serializing XDocument XML documents correctly, e.g. when it comes to serializing elements with the xml:space="preserve" attribute set.

The Enhanced XML Writer class does not have issues and correctly serializes XML documents stored in an XDocument object tree.

You should use the Enhanced XML Writer whenever you want to serialize business critical XML data.

Feedback, Sponsorship and Contact

You may reach me on axeldahmen.de or LinkedIn