Serialization

This guide explains how to use the XmlPrime serializer.

This topic contains the following sections.

Overview

XQuery and XPath operate over instances of the XQuery 1.0 and XPath 2.0 Data Model (XDM) which are represented as sequences of XPathItemXPathItemXPathItem objects in the Microsoft .NET Framework. Serialization is the process of converting an XDM instance into a sequence of octets. It occurs, for example, when an XDM instance is written to a file.

The XmlPrime.SerializationXmlPrime.SerializationXmlPrime.Serialization namespace provides a means to serialize XDM instances in accordance with the XSLT 2.0 and XQuery 1.0 Serialization (Second Edition) specification, augmented with XmlPrime-specific extensions. For example, XmlPrime provides the ability to serialize directly to Canonical XML Version 1.0.

Serialization is performed by creating XdmWriterXdmWriterXdmWriter objects, which are implementations of XmlWriterXmlWriterXmlWriter. Indeed, XdmWriterXdmWriterXdmWriter can be used as a replacement for XmlWriterXmlWriterXmlWriter.

Serialization Settings

The XdmWriterSettingsXdmWriterSettingsXdmWriterSettings class, which is conceptually similar to the XmlWriterSettingsXmlWriterSettingsXmlWriterSettings class, is used to specify the way in which an XdmWriterXdmWriterXdmWriter will serialize an XDM instance. The serialization parameters represented by the properties of the XdmWriterSettingsXdmWriterSettingsXdmWriterSettings class can also be set from within an XQuery program. The post-compilation serialization settings are available in the XQuery.SerializationSettingsXQuery.SerializationSettingsXQuery::SerializationSettings property. See Serialization Parameters for full documentation of the XML serializer.

The following code shows how to specify a serializer that produces indented HTML and writes out HTML to a file.

 
using XmlPrime.Serialization;

XdmWriterSettings settings = new XdmWriterSettings(XdmWriterSettings.HtmlOutputMethod);
settings.Indent = true;

using (XdmWriter writer = XdmWriter.Create("C:\out.htm", settings);
{
    writer.WriteStartElement("html");
    writer.WriteStartElement("head");
    writer.WriteElementString("title", "Hello World");
    writer.WriteEndElement(); // end head
    writer.WriteStartElement("body");
    writer.WriteElementString("p", "Hello World!");
    writer.WriteEndElement(); // end body
    writer.WriteEndElement(); // end html
}
 

Serializing XDM instances

In addition to behaving like an XmlWriterXmlWriterXmlWriter, XdmWriterXdmWriterXdmWriter also provides static methods to serialize XDM instances.

Serializing a document

The following example shows how to serialize an XPathDocumentXPathDocumentXPathDocument with indentation and hexadecimal character references.

 
using System.Xml.XPath;
using XmlPrime.Serialization;

XPathDocument doc = new XPathDocument("input.xml");

XdmWriterSettings settings = new XdmWriterSettings();
settings.CharacterReferenceStyle = CharacterReferenceStyle.Hexadecimal;
settings.Indent = true;

XdmWriter.Serialize(doc.CreateNavigator(), "output.xml", settings);
 

Serializing the results of an XPath expression

The following example shows how to serialize the results of an XPath expression using a default XdmWriterSettingsXdmWriterSettingsXdmWriterSettings.

 
using XmlPrime;
using XmlPrime.Serialization;

// Load the document to be queried
XdmDocument document = new XdmDocument("bib.xml");
XPathNavigator contextItem = document.CreateNavigator();

// Compile the XPath expression
XmlNameTable nameTable = navigator.NameTable;
XPath expression = XPath.Compile("/bib/books", nameTable);

// Evaluate the XPath expression
IEnumerable<XPathItem> results = expression.Evaluate(contextItem);

// Serialize the results of the XPath expression.
XdmWriter.Serialize(results, "output.xml");
 

Serializing the results of an XQuery program

When serializing the result of a query, the XQuery.SerializeXQuery.SerializeXQuery::Serialize method should be used to invoke the query. The method has overloads for writing to a named file, a StreamStreamStream or a TextWriterTextWriterTextWriter. The serialization settings used are those specified by the XQuery.SerializationSettingsXQuery.SerializationSettingsXQuery::SerializationSettings property. Alternatively, use the overload which takes an XmlWriterXmlWriterXmlWriter. to serialize the result using serialization settings other than those specified by the query.

 
using XmlPrime;
using XmlPrime.Serialization;

// Load the document to be queried
XdmDocument document = new XdmDocument("bib.xml");
XPathNavigator contextItem = document.CreateNavigator();

// Compile the query
XmlNameTable nameTable = contextItem.NameTable;
XQuerySettings querySettings = new XQuerySettings(nameTable);
string program = "for $book in /bib/books" +
                  "order by xs:decimal($book/price)" +
                  "return $book";
XQuery query = XQuery.Compile(program, querySettings);

// Execute the query and serialize the results to a file.
query.Serialize("output.xml", contextItem);
 
 
 
Note
If the result of a query is to be serialized, then it is highly recommended to invoke the query in this way rather than just serializing the result set, as the query can be serialized directly, preventing an intermediate representation of the result from being constructed.