Share via


Creating XML Readers

XmlReader instances are created using the Create method. The XmlReaderSettings class is used to specify the set of features you want to enable on the XmlReader object.

Important noteImportant

Although the Microsoft .NET Framework includes concrete implementations of the XmlReader class, such as the XmlTextReader, XmlNodeReader, and the XmlValidatingReader classes, in the .NET Framework version 2.0, we recommend that you create XmlReader instances using the Create method.

Features are enabled or disabled by using the properties on the XmlReaderSettings class. The XmlReaderSettings object is then passed to the Create method.

By using the Create method and the XmlReaderSettings class you get the following benefits:

  • You are able to specify which features you want supported on the created XmlReader object.

  • The XmlReaderSettings class can be reused to create multiple reader objects. You can use the same settings to create multiple readers with the same functionality. Alternatively, you can modify the XmlReaderSettings object and create a new reader with a different set of features.

  • You can add features to an existing reader. The Create method can accept another XmlReader object. The underlying XmlReader object can be a user-defined reader or an XmlTextReader object, or another XmlReader instance that you want to add additional features to.

  • Take full advantage of all the new features added to the XmlReader class in the .NET Framework 2.0 release. There are certain features, such as better conformance checking and compliance to the XML 1.0 recommendation, that are available only on XmlReader objects created by the Create method.

The following table lists the default property settings on the XmlReaderSettings class.

Property

Default value

CheckCharacters

true

ConformanceLevel

ConformanceLevel.Document

IgnoreComments

false

IgnoreProcessingInstructions

false

IgnoreWhitespace

false

LineNumberOffset

0.

LinePositionOffset

0

NameTable

null

DtdProcessing

Prohibit

ProhibitDtd

true. This property is obsolete. Use DtdProcessing instead.

Schemas

An empty XmlSchemaSet object

ValidationFlags

ProcessIdentityConstraints enabled

ValidationType

ValidationType.None

XmlResolver

A new XmlUrlResolver object

XmlReader Scenarios

The following table describes some common scenarios and which settings on the XmlReaderSettings class to apply.

Scenario

XmlReaderSettings

Requires the data to be a well-formed XML document.

ConformanceLevel = ConformanceLevel.Document

Requires the data to be a well-formed XML parsed entity.

ConformanceLevel = ConformanceLevel.Fragment

Needs data to be validated against a DTD.

DtdProcessing = DtdProcessing.Parse

ValidationType = ValidationType.DTD

Needs data to be validated against an XML Schema.

ValidationType = ValidationType.Schema

Schemas = XmlSchemaSet to use for validation

Needs data to be validated against an inline XML Schema.

ValidationType = ValidationType.Schema

ValidationFlags |= XmlSchemaValidationFlags.ProcessInlineSchema

Needs type support.

ValidationType = ValidationType.Schema

Schemas = XmlSchemaSet to use

There are a few special scenarios that may require using an XmlReader implementation that is not created by the Create method.

Note

The XmlValidatingReader class is obsolete in the .NET Framework 2.0 release. We recommend that you consider migrating to XML Schemas and validate using an XmlReader object returned by the Create method.

  • To read XML data from an XmlNode object, use the XmlNodeReader class.

  • If you must expand entities on request (readers created by the Create method expand all entities), or if you do not want your text content normalized, use the XmlTextReader class.

  • If you do not want default attributes returned, use the XmlTextReader class.

To instantiate an XmlReader object

Dim settings As New XmlReaderSettings()
settings.ConformanceLevel = ConformanceLevel.Fragment
settings.IgnoreWhitespace = true
settings.IgnoreComments = true
Dim reader As XmlReader = XmlReader.Create("books.xml", settings)
XmlReaderSettings settings = new XmlReaderSettings();
settings.ConformanceLevel = ConformanceLevel.Fragment;
settings.IgnoreWhitespace = true;
settings.IgnoreComments = true;
XmlReader reader = XmlReader.Create("books.xml", settings);

To wrap a reader instance within another reader

Dim txtReader As XmlTextReader = New XmlTextReader("bookOrder.xml")
Dim settings As New XmlReaderSettings()
settings.Schemas.Add("urn:po-schema", "PO.xsd")
settings.ValidationType = ValidationType.Schema
Dim reader As XmlReader = XmlReader.Create(txtReader, settings)
XmlTextReader txtReader = new XmlTextReader("bookOrder.xml");
XmlReaderSettings settings = new XmlReaderSettings();
settings.Schemas.Add("urn:po-schema", "PO.xsd");
settings.ValidationType = ValidationType.Schema;
XmlReader reader = XmlReader.Create(txtReader, settings);

To chain readers to add additional settings

Dim settings As New XmlReaderSettings()
settings.ValidationType = ValidationType.DTD
Dim inner As XmlReader = XmlReader.Create("book.xml", settings) ' DTD Validation
settings.Schemas.Add("urn:book-schema", "book.xsd")
settings.ValidationType = ValidationType.Schema
Dim outer As XmlReader = XmlReader.Create(inner, settings)  ' XML Schema Validation
XmlReaderSettings settings = new XmlReaderSettings();
settings.ValidationType = ValidationType.DTD;
XmlReader inner = XmlReader.Create("book.xml", settings); // DTD Validation
settings.Schemas.Add("urn:book-schema", "book.xsd");
settings.ValidationType = ValidationType.Schema;
XmlReader outer = XmlReader.Create(inner, settings);  // XML Schema Validation

See Also

Concepts

Reading XML with the XmlReader