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.
CheckCharacters Setting
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.
Note
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.
ConformanceLevel Setting
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.
Note
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. Note 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. Note 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:
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. |