XmlLite Writer Programming Overview
This topic provides an overview of programming with the XmlLite writer. The XmlLite writer provides fast, non-cached, forward-only generation of XML that complies with the W3C Extensible Markup Language (XML) 1.0 specification and the Namespaces in XML specification.
Overview
XmlLite is implemented as a library that you link to and a DLL that implements the XML parser. It is a conventional C++ library—to use it, you include a header that defines the classes. You call methods as appropriate to generate the XML. There are two classes that implement the XmlLite writer: IXmlWriter and IXmlWriterLite. IXmlWriter validates namespaces and attributes, and can automatically close tags, which helps you maintain document correctness. IXmlWriterLite skips namespace and attribute validation, and can be significantly faster when it writes, but requires careful coding to maintain document correctness. We recommend that you use IXmlWriter unless speed is more important than validation. IXmlWriterLite is available in the XmlLite headers and libraries distributed in the Windows 10 SDK, for use on Windows 10.
Usage Scenarios
The following are some common usage scenarios for IXmlWriter and IXmlWriterLite:
Serializing an object tree by constructing XML from it. For example, you might construct a PurchaseOrder XML document by walking an object graph (that is, a PurchaseOrder object that includes a LineItems collection).
Taking data from multiple sources and creating an XML document from them. For example, you might retrieve data from a database, and then wrap a SOAP envelope around the data.
Constructing one XML document by using another as a template. For example, you might to read an inventory document and create a new version with prices increased by 10%. Another example would be to read a WordML document that contains templates in the form of {name}, and constructing a dynamically generated word document by replacing the {name} templates.
You Must Use a Class that Implements IStream
The XmlLite writer requires that the programmer pass a stream class to it for writing the XML. When your application calls the CreateXmlWriter method, it passes in an instantiation of a class that implements IStream. You must either use an instantiation of a class that implements the IStream interface, or implement your own class that extends the IStream interface.
Limitations of IXmlWriter and IXmlWriterLite
The IXmlWriter XmlLite writer helps you write well-formed XML as specified by the XML 1.0 specification. As an example, IXmlWriter enforces constraints on duplicate attributes and duplicate namespaces (which are prohibited by the W3C XML specification). IXmlWriter also helps you create well-formed XML in other ways, such as by automatically writing closing tags. It automatically handles namespace prefixes, writing well-formed comments, and more. However, IXmlWriter does not always enforce creation of well-formed XML. As an example, the WriteRaw and WriteRawChars methods let you output malformed XML.
The IXmlWriterLite writer does not perform the same level of automatic handling and validation as IXmlWriter. This gives you more ways to output malformed XML, but can be faster if you be careful to manage your own correct output. When you use IXmlWriterLite, your code is responsible for correct use of namespaces and attributes, creating well-formed comments and CDATA, and the writing of closing tags. For ease of coding correct XML, we recommend that you use IXmlWriter unless shorter write times are of highest importance.
Namespace Handling
The IXmlWriter maintains a namespace stack corresponding to all the namespaces defined by the current element stack. After you introduce a namespace when writing an element, you can use the same namespace when you write other elements, and IXmlWriter performs the required tasks to write valid XML. For example, if a nested element is in the same namespace as its parent element, IXmlWriter does not repeat the namespace declaration.
After a start element has been written and the namespace and the prefix have been implicitly or explicitly defined, the IXmlWriter writer does not support redefinition of the same prefix in the context of the current start tag.
In other words, it is an error to write any namespace declarations that conflict with any name (the element name or any attribute name) that has been written in the context of the current start tag.
The IXmlWriterLite writer does not perform the same level of namespace validation. You are responsible for the correct introduction and use of namespaces and namespace prefixes in your document. IXmlWriterLite silently writes malformed XML if you do not follow the rules and create duplicate or conflicting names or redefine a prefix in the context of the same element.