This documentation is archived and is not being maintained.

Data Conformance and the XmlWriter

The XmlWriter class includes two conformance-checking settings. You can set the XmlWriter to check that the data written out is conformant.

The XmlWriterSettings.CheckCharacters property instructs the writer to check characters and throw an XmlException if any characters are outside the range of legal XML characters. When character checking is enabled, you are ensured that all characters in the document are within the range of legal XML characters as defined by the W3C XML 1.0 Recommendation.

NoteNote:

Character checking does not include checking for illegal characters in XML names, or checking that all XML names are valid. Name checking is a standard part of conformance checking. For more information, see http://www.w3.org/TR/REC-xml#NT-Name

By default, character checking is enabled.

The XmlWriterSettings.ConformanceLevel property configures the XmlWriter to check and guarantee that the stream being written complies with a certain set of rules. Depending on the conformance level that is specified, the XML data can be checked to see that it conforms to the rules for a well-formed XML 1.0 document, or document fragment. If the data is not in conformance, an XmlException or ArgumentException is thrown. The default setting is ConformanceLevel.Document.

NoteNote:

If the writer is configured to support ConformanceLevel.Fragment, but the XML data contains a document type definition (DTD), the writer throws an exception. The XML 1.0 recommendation requires document level conformance when a DTD is present. Thus, if the WriteStartDocument method is called on a writer that is configured to support ConformanceLevel.Fragment, the writer will throw an exception as well.

Conformance level

Description

Document

This setting ensures that the output conforms to the rules for a well-formed XML 1.0 document and is able to be processed by any conforming processor.

NoteNote:

The writer does not parse DTD information that is written. The user is responsible for ensuring that the DTD is well formed.

Fragment

The XML data conforms to the rules for a well-formed XML 1.0 document fragment.

This setting accepts XML data with multiple root elements, or text nodes at the top-level. This level of checking ensures that any processor can consume the stream being read as an XML 1.0 external parsed entity.

NoteNote:

DTD is not allowed in fragments.

Auto

The writer decides which level of conformance checking to apply based on the incoming data. This setting can be useful when you do not know whether the generated XML will be a well-formed XML document or a fragment.

Document conformance checking is applied in the following cases:

Fragment conformance checking is applied if the XML data contains one of following:

  • Text, CDATA, or EntityReference node at the root level.

  • More than one element at the root level.

  • No element at the root level.

An XmlException is thrown if there is a conflict, such as when you try to write a text node and a DTD at the root level.

This setting can be used in wrapping scenarios when the Create method is used to add additional features to an existing writer. In this case, ConformanceLevel.Auto does not add any new conformance checking. Conformance checking is left to the writer that is being wrapped.

Show: