System.Xml
2.0.0.0
4.0.0.0
System.Object
In the dnprdnext release, the method is the preferred mechanism for obtaining instances. The method uses the class to specify which features to implement in the created object.
For more information, see Creating XML Readers.
Security Considerations
The following are things to consider when using the class.
-
The and validation flags of an object are not set by default. When these flags are set, the of the object is used to resolve schema locations encountered in the instance document in the . If the object is null, schema locations are not resolved even if the and validation flags are set.
-
Schemas added during validation add new types and can change the validation outcome of the document being validated. As a result, external schemas should only be resolved from trusted sources.
-
Validation error messages may expose sensitive content model information. Validation error and warning messages are handled using the delegate, or are exposed as an if no event handler is provided to the object (validation warnings do not cause an to be thrown). This content model information should not be exposed in untrusted scenarios. Validation warning messages are suppressed by default and can be reported by setting the flag.
-
The property of an returns the URI path to the schema file that caused the exception. The property should not be exposed in untrusted scenarios.
-
Disabling the flag (enabled by default) is recommended when validating, untrusted, large XML documents in high availability scenarios against a schema with identity constraints over a large part of the document.
-
objects can contain sensitive information such as user credentials. You should be careful when caching objects, or when passing the object from one component to another.
-
DTD processing is disabled by default. If you enable DTD processing, you need to be aware of including DTDs from untrusted sources and possible denial of service attacks. Use the to restrict the resources that the can access.
-
Do not accept supporting components, such as , , and objects, from an untrusted source.
-
Memory usage of an application that uses may have a correlation to the size of the parsed XML document. One form of denial of service attack is when excessively large XML documents are submitted to be parsed. You can limit the size of the document that can be parsed by setting the property and then limit the number of characters that result from expanding entities by setting the property.
Specifies a set of features to support on the object created by the method.
Constructor
2.0.0.0
4.0.0.0
The following table shows initial property values for an instance of .
-
Property
Initial value
-
false.
-
true.
-
.
-
false.
-
false.
-
false.
-
0.
-
0.
-
0 (There is no limit on the number of characters that result from expanding entities).
-
0 (There is no limit on the size of the XML document).
-
null.
-
-
true. This property is obsolete. Use instead. If you had set to its default value true set to Prohibit. If you had set to false set to Parse.
-
An empty object.
-
.
-
.
-
A new object.
Initializes a new instance of the class.
Property
4.0.0.0
System.Boolean
To be added.
You must set this value to true when you create a new instance if you want to use asynchronous methods on that instance. After the instance is created, the property is read-only. The default value of this property is false.
This flag is ignored by the overload. This means that if you create a new based on an existing , the async behavior depends on the input , and you cannot use the flag to change the async behavior.
Gets or sets whether asynchronous methods can be used on a particular instance.
Property
2.0.0.0
4.0.0.0
System.Boolean
To be added.
Instructs the reader to check characters and throw an exception if any characters are outside the range of legal XML characters. Character checking includes checking for illegal characters in the document, as well as checking the validity of XML names (for example, an XML name may not start with a numeral).
For more information, see sections 2.2 (http://www.w3.org/TR/REC-xml#charsets) and 2.3 (http://www.w3.org/TR/REC-xml#NT-Name) of the W3C XML 1.0 recommendation.
Gets or sets a value indicating whether to do character checking.
Method
2.0.0.0
4.0.0.0
System.Xml.XmlReaderSettings
The cloned object can be modified without affecting the settings on the original object.
Creates a copy of the instance.
The cloned object.
Property
2.0.0.0
4.0.0.0
System.Boolean
To be added.
This setting is used when a stream or is passed to the method. If a stream is created by the reader for its own processing, such as when the reader is created with a URI or when it opens an external document type definition, it is always closed when the reader is closed.
Gets or sets a value indicating whether the underlying stream or should be closed when the reader is closed.
Property
2.0.0.0
4.0.0.0
System.Xml.ConformanceLevel
To be added.
Note that objects created by the method are more compliant by default than the class. The following are conformance improvements that are not enabled on , but are available by default on readers created by the method:
-
New lines and attribute value are normalized according to the XML spec.
-
All entities are automatically expanded.
-
Default attributes declared in the document type definition are always added even when the reader does not validate.
-
Declaration of XML prefix mapped to the correct XML namespace URI is allowed.
-
The notation names in a single NotationType attribute declaration, as well as the NmTokens in a single Enumeration attribute declaration, must all be distinct.
For more information, see Data Conformance Checking with XmlReader.
Gets or sets the level of conformance which the will comply.
Property
4.0.0.0
System.Xml.DtdProcessing
To be added.
The enumeration contains the , , and enumerators. is the default behavior. The property replaces the ProhibitDTD property and adds the ability to ignore the DOCTYPE element. If you had set to its default value true set to Prohibit. If you had set to false set to Parse.
If the property is set to , the will not report the DTDs. This means that the DTD/DOCTYPE will be lost on output.
Gets or sets a value that determines the processing of DTDs.
Property
2.0.0.0
4.0.0.0
System.Boolean
To be added.
Setting this property to true can result in multiple contiguous text nodes being returned from the reader. This does not affect validation.
Gets or sets a value indicating whether to ignore comments.
Property
2.0.0.0
4.0.0.0
System.Boolean
To be added.
Setting this property to true can result in multiple contiguous text nodes being returned from the reader. This does not affect validation.
Gets or sets a value indicating whether to ignore processing instructions.
Property
2.0.0.0
4.0.0.0
System.Boolean
To be added.
White space that is not considered to be significant includes spaces, tabs, and blank lines used to set apart the markup for greater readability. An example of this is white space in element content.
This property setting does not affect white space between markup in a mixed content mode, or white space that occurs within the scope of an xml:space='preserve' attribute.
Gets or sets a value indicating whether to ignore insignificant white space.
Property
2.0.0.0
4.0.0.0
System.Int32
To be added.
The setting determines the point where the property starts counting. This is useful if your XML data is embedded within a larger document. For example, if your XML data were embedded in a larger document, and your data started on line 101 of the document, you may want to specify that the reader start at line 100. Therefore, if the reader threw an exception while parsing the first line of the XML, it would report the line number as line 101, rather than line 1.
Gets or sets line number offset of the object.
Property
2.0.0.0
4.0.0.0
System.Int32
To be added.
The setting determines the point where the property starts counting. This is useful if your XML data is embedded within a larger document and there is no new line at the beginning of the XML. In this case, if the reader throws an exception while parsing the XML, you want it to return the line position relative to the main document, not just relative to the XML fragment.
Gets or sets line position offset of the object.
Property
4.0.0.0
System.Int64
To be added.
A zero (0) value means no limits on the number of characters that result from expanding entities. A non-zero value specifies the maximum number of characters that can result from expanding entities.
If the reader attempts to read a document that contains entities such that the expanded size will exceed this property, an will be thrown.
This property allows you to mitigate denial of service attacks where the attacker submits XML documents that attempt to exceed memory limits via expanding entities. By limiting the characters that result from expanded entities, you can detect the attack and recover reliably.
Gets or sets a value indicating the maximum allowable number of characters in a document that result from expanding entities.
Property
4.0.0.0
System.Int64
To be added.
A zero (0) value means no limits on the number of characters in the parsed document. A non-zero value specifies the maximum number of characters that can be parsed.
The maximum character count for the document includes the count of characters that result from expanded entities.
If the reader attempts to read a document with a size that exceeds this property, an will be thrown.
This property allows you to mitigate denial of service attacks where the attacker submits extremely large XML documents. By limiting the size of a document, you can detect the attack and recover reliably.
Gets or sets a value indicating the maximum allowable number of characters XML document. A zero (0) value means no limits on the size of the XML document. A non-zero value specifies the maximum size, in characters.
Property
2.0.0.0
4.0.0.0
System.Xml.XmlNameTable
To be added.
Set this property to an instance if you want to share a common name table among all the created instances.
The class is not thread-safe. Therefore it cannot be shared between objects that run simultaneously in different threads.
Gets or sets the used for atomized string comparisons.
Property
2.0.0.0
4.0.0.0
System.Obsolete("Use DtdProcessing property instead")
System.Boolean
To be added.
When set to true, the throws an when any DTD content is encountered. Do not enable DTD processing if you are concerned about Denial of Service issues or if you are dealing with untrusted sources.
If you have DTD processing enabled, you can use the to restrict the resources that the can access. You can also design your application so that the XML processing is memory and time constrained. For example, configure time-out limits in your ASP.NET application.
This property is obsolete. Use instead. If you had set to its default value true set to Prohibit. If you had set to false set to Parse.
Gets or sets a value indicating whether to prohibit document type definition (DTD) processing. This property is obsolete. Use instead.
Method
2.0.0.0
4.0.0.0
System.Void
The following table shows initial property values for an instance of .
-
Property
Initial Value
-
false.
-
true.
-
.
-
false.
-
false.
-
false.
-
0.
-
0.
-
0 (There is no limit on the number of characters that result from expanding entities).
-
0 (There is no limit on the size of the XML document).
-
null.
-
-
true. This property is obsolete. Use instead. If you had set to its default value true set to Prohibit. If you had set to false set to Parse.
-
An empty object.
-
.
-
.
-
A new object.
Resets the members of the settings class to their default values.
Property
2.0.0.0
4.0.0.0
System.Xml.Schema.XmlSchemaSet
To be added.
The class only supports XML Schema definition language (XSD) schemas. instances created by the method cannot be configured to enable XML-Data Reduced (XDR) schema validation.
Gets or sets the to use when performing schema validation.
Event
2.0.0.0
4.0.0.0
System.Xml.Schema.ValidationEventHandler
These events occur while reading an XML instance document if the is set to either or . If the setting has been enabled on the property these events also occur when any validation warnings are encountered.
If the reader is configured for validation and no validation event handler has been set, an is thrown for all validation errors. (Validation warnings do not cause an to be thrown).
Validation error messages may expose sensitive content model information. Validation error and warning messages are handled using the delegate, or are exposed as an if no event handler is provided to the object (validation warnings do not cause an to be thrown). This content model information should not be exposed in untrusted scenarios. Validation warning messages are suppressed by default and can be reported by setting the flag.
The property of an returns the URI path to the schema file that caused the exception. The property should not be exposed in untrusted scenarios.
Occurs when the reader encounters validation errors.
Property
2.0.0.0
4.0.0.0
System.Xml.Schema.XmlSchemaValidationFlags
To be added.
The and validation flags of an object are not set by default. When these flags are set, the of the object is used to resolve schema locations encountered in the instance document in the . If the object is null, schema locations are not resolved even if the and validation flags are set.
Schemas added during validation add new types and can change the validation outcome of the document being validated. As a result, external schemas should only be resolved from trusted sources.
Disabling the flag (enabled by default) is recommended when validating, untrusted, large XML documents in high availability scenarios against a schema with identity constraints over a large part of the document.
Gets or sets a value indicating the schema validation settings. This setting applies to schema validating objects ( property set to ValidationType.Schema).
Property
2.0.0.0
4.0.0.0
System.Xml.ValidationType
To be added.
The following table describes the values.
The and enumeration values are obsolete in .NET Framework version 2.0.
-
ValidationType
Description
-
DTD
Validation is performed using a document type definition (DTD).
The property must also be set to .
-
None
The does not validate data, or perform any type assignment.
-
Schema
Validation and type assignment is performed using an XML Schema definition language (XSD) schema. The reader accesses the XML Schema using the following:
-
Uses the property to access the object associated with this reader.
-
Uses the in-line schema contained in the XML instance document. (The option must be enabled.)
-
Uses the XML Schema specified by schema location hints (xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute) found in the XML instance document. (The option must be enabled.)
Gets or sets a value indicating whether the will perform validation or type assignment when reading.
Property
2.0.0.0
4.0.0.0
System.Xml.XmlResolver
To be added.
The is used to locate and open an XML instance document, or to locate and open any external resources referenced by the XML instance document. This can include entities, DTD, or schemas. The property can be used to specify any credentials required for network authentication.
Because the can contain sensitive information such as user credentials, you should be careful when caching objects, or when passing the object from one component to another.
An can be used to access external documents. The class helps to secure another implementation of by wrapping the object and restricting the resources that the underlying has access to. For more information, see How to: Use the XmlSecureResolver Class.
The and validation flags of an object are not set by default. When these flags are set, the of the object is used to resolve schema locations encountered in the instance document in the . If the object is null, schema locations are not resolved even if the and validation flags are set.
Schemas added during validation add new types and can change the validation outcome of the document being validated. As a result, external schemas should only be resolved from trusted sources.
Sets the used to access external documents.