Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Data Conformance Checking with XmlReader

XmlReader objects created by the Create method are, by default, more conformant than the XmlTextReader implementation. XmlReader objects created by the Create method support the following features by default:

  • Normalize new-line characters.

  • Expand entities.

  • Add default attributes.

The XmlReaderSettings.CheckCharacters and XmlReaderSettings.ConformanceLevel properties allow you to specify the type of conformance checks you want to enable on the created XmlReader object.

The CheckCharacters property on the XmlReaderSettings class instructs the reader 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 the following:

  • All characters in the document are within the range of legal XML characters as defined by the W3C XML 1.0 Recommendation.

  • All XML names are valid. For example, if the name of an element starts with a number, an XmlException is thrown. For more information, see http://www.w3.org/TR/REC-xml#NT-Name.

By default, character checking is enabled. If the reader is processing text data, it always checks that XML names are valid, even when the CheckCharacters property is set to false.

The ConformanceLevel property on the XmlReaderSettings class configures the XmlReader to check and guarantee that the stream being read 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 is thrown. The default setting is ConformanceLevel.Document.

NoteNote:

If the reader is configured to support ConformanceLevel.Fragment, but the XML data contains a document type definition (DTD), an XmlException is thrown. The XML 1.0 recommendation requires document-level conformance when a DTD is present.

ConformanceLevel value

Description

Document

The XML data conforms to the rules for a well-formed XML 1.0 document. This level of checking ensures that any processor can consume the stream being read as an XML 1.0 document.

The reader checks for the following:

  • The top-level item must not have any nodes other than XML Declaration, document type definition (DTD), element, comment, white space, or processing instruction.

  • The XML data must have exactly one top-level element node.

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 reader decides which level of conformance checking to apply based on the incoming data.

Document conformance checking is applied if the XML data contains DTD information.

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

  • Text, CDATA or entity reference 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 there is 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 XmlReader. In this case ConformanceLevel.Auto does not add any new conformance checking. Conformance checking is left to the XmlReader that is being wrapped.

XmlTextReader, XmlValidatingReader, and XmlNodeReader Objects

The ConformanceLevel setting has the following behavior when working with XmlTextReader, XmlValidatingReader, or XmlNodeReader objects.

The following code creates a reader that enforces fragment-level conformance.

XmlReaderSettings settings = new XmlReaderSettings();
settings.ConformanceLevel = ConformanceLevel.Fragment;
XmlReader reader = XmlReader.Create(new StringReader(xmlString), settings);
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft