System.Xml.XmlReader.Create methods

This article provides supplementary remarks to the reference documentation for this API.

Most of the Create overloads include a settings parameter that accepts an XmlReaderSettings object. You can use this object to:

• Specify which features you want supported on the XmlReader object.
• Reuse the XmlReaderSettings object to create multiple readers. You can use the same settings to create multiple readers with the same functionality. Or, you can modify the settings on an XmlReaderSettings instance and create a new reader with a different set of features.
• Add features to an existing XML reader. The Create method can accept another XmlReader object. The underlying XmlReader object can be a user-defined reader, a XmlTextReader object, or another XmlReader instance that you want to add additional features to.
• Take full advantage of features such as better conformance checking and compliance to the XML 1.0 (fourth edition) recommendation that are available only on XmlReader objects created by the static Create method.

Note

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

Default settings

If you use a Create overload that doesn't accept a XmlReaderSettings object, the following default reader settings are used:

Setting	Default
CheckCharacters	true
ConformanceLevel	ConformanceLevel.Document
IgnoreComments	false
IgnoreProcessingInstructions	false
IgnoreWhitespace	false
LineNumberOffset	0
LinePositionOffset	0
NameTable	null
DtdProcessing	Prohibit
Schemas	An empty XmlSchemaSet object
ValidationFlags	ProcessIdentityConstraints enabled
ValidationType	None
XmlResolver	null

Settings for common scenarios

Here are the XmlReaderSettings properties you should set for some of the typical XML reader scenarios.

Requirement	Set
Data must be a well-formed XML document.	ConformanceLevel to Document.
Data must be a well-formed XML parsed entity.	ConformanceLevel to Fragment.
Data must be validated against a DTD.	DtdProcessing to Parse ValidationType to DTD.
Data must be validated against an XML schema.	ValidationType to Schema Schemas to the XmlSchemaSet to use for validation. Note that XmlReader doesn't support XML-Data Reduced (XDR) schema validation.
Data must be validated against an inline XML schema.	ValidationType to Schema ValidationFlags to ProcessInlineSchema.
Type support.	ValidationType to Schema Schemas to the XmlSchemaSet to use.

XmlReader doesn't support XML-Data Reduced (XDR) schema validation.

Asynchronous programming

In synchronous mode, the Create method reads the first chunk of data from the buffer of the file, stream, or text reader. This may throw an exception if an I/O operation fails. In asynchronous mode, the first I/O operation occurs with a read operation, so exceptions that arise will be thrown when the read operation occurs.

Security considerations

By default, the XmlReader uses an XmlUrlResolver object with no user credentials to open resources. This means that, by default, the XML reader can access any location that doesn't require credentials. Use the XmlResolver property to control access to resources:

• Set XmlResolver to an XmlSecureResolver object to restrict the resources that the XML reader can access, or...
• Set XmlResolver to null to prevent the XML reader from opening any external resources.

Examples

This example creates an XML reader that strips insignificant white space, strips comments, and performs fragment-level conformance checking.

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

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

The following example uses an XmlUrlResolver with default credentials to access a file.

// Set the reader settings.
XmlReaderSettings settings = new XmlReaderSettings();
settings.IgnoreComments = true;
settings.IgnoreProcessingInstructions = true;
settings.IgnoreWhitespace = true;

' Set the reader settings.
Dim settings as XmlReaderSettings = new XmlReaderSettings()
settings.IgnoreComments = true
settings.IgnoreProcessingInstructions = true
settings.IgnoreWhitespace = true

// Create a resolver with default credentials.
XmlUrlResolver resolver = new XmlUrlResolver();
resolver.Credentials = System.Net.CredentialCache.DefaultCredentials;

// Set the reader settings object to use the resolver.
settings.XmlResolver = resolver;

// Create the XmlReader object.
XmlReader reader = XmlReader.Create("http://ServerName/data/books.xml", settings);

' Create a resolver with default credentials.
Dim resolver as XmlUrlResolver = new XmlUrlResolver()
resolver.Credentials = System.Net.CredentialCache.DefaultCredentials

' Set the reader settings object to use the resolver.
settings.XmlResolver = resolver

' Create the XmlReader object.
Dim reader as XmlReader = XmlReader.Create("http://ServerName/data/books.xml", settings)

The following code wraps a reader instance within another reader.

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);

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)

This example chains readers to add DTD and 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

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