XmlReader Class

Other Versions

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

Represents a reader that provides fast, non-cached, forward-only access to XML data.

Inheritance Hierarchy

System::Object
System.Xml::XmlReader
System.Xml::XmlDictionaryReader

Namespace: System.Xml
Assembly: System.Xml (in System.Xml.dll)

Syntax

C++

No code example is currently available or this language may not be supported.

The XmlReader type exposes the following members.

	Name	Description
	XmlReader	Initializes a new instance of the XmlReader class.

	Name	Description
	AttributeCount	When overridden in a derived class, gets the number of attributes on the current node.
	BaseURI	When overridden in a derived class, gets the base URI of the current node.
	CanReadBinaryContent	Gets a value indicating whether the XmlReader implements the binary content read methods.
	CanReadValueChunk	Gets a value indicating whether the XmlReader implements the ReadValueChunk method.
	CanResolveEntity	Gets a value indicating whether this reader can parse and resolve entities.
	Depth	When overridden in a derived class, gets the depth of the current node in the XML document.
	EOF	When overridden in a derived class, gets a value indicating whether the reader is positioned at the end of the stream.
	HasAttributes	Gets a value indicating whether the current node has any attributes.
	HasValue	When overridden in a derived class, gets a value indicating whether the current node can have a Value.
	IsDefault	When overridden in a derived class, gets a value indicating whether the current node is an attribute that was generated from the default value defined in the DTD.
	IsEmptyElement	When overridden in a derived class, gets a value indicating whether the current node is an empty element (for example, <MyElement/>).
	Item[Int32]	When overridden in a derived class, gets the value of the attribute with the specified index.
	Item[String]	When overridden in a derived class, gets the value of the attribute with the specified Name.
	Item[String, String]	When overridden in a derived class, gets the value of the attribute with the specified LocalName and NamespaceURI.
	LocalName	When overridden in a derived class, gets the local name of the current node.
	Name	When overridden in a derived class, gets the qualified name of the current node.
	NamespaceURI	When overridden in a derived class, gets the namespace URI (as defined in the W3C Namespace specification) of the node on which the reader is positioned.
	NameTable	When overridden in a derived class, gets the XmlNameTable associated with this implementation.
	NodeType	When overridden in a derived class, gets the type of the current node.
	Prefix	When overridden in a derived class, gets the namespace prefix associated with the current node.
	ReadState	When overridden in a derived class, gets the state of the reader.
	Settings	Gets the XmlReaderSettings object used to create this XmlReader instance.
	Value	When overridden in a derived class, gets the text value of the current node.
	ValueType	Gets the common language runtime (CLR) type for the current node.
	XmlLang	When overridden in a derived class, gets the current xml:lang scope.
	XmlSpace	When overridden in a derived class, gets the current xml:space scope.

	Name	Description
	Close	When overridden in a derived class, changes the ReadState to Closed.
	Create(Stream)	Creates a new XmlReader instance using the specified stream.
	Create(String)	Creates a new XmlReader instance with specified URI.
	Create(TextReader)	Creates a new XmlReader instance with the specified TextReader.
	Create(Stream, XmlReaderSettings)	Creates a new XmlReader instance with the specified stream and XmlReaderSettings object.
	Create(String, XmlReaderSettings)	Creates a new instance with the specified URI and XmlReaderSettings.
	Create(TextReader, XmlReaderSettings)	Creates a new XmlReader instance using the specified TextReader and XmlReaderSettings objects.
	Create(XmlReader, XmlReaderSettings)	Creates a new XmlReader instance with the specified XmlReader and XmlReaderSettings objects.
	Create(Stream, XmlReaderSettings, String)	Creates a new XmlReader instance using the specified stream, base URI, and XmlReaderSettings object.
	Create(Stream, XmlReaderSettings, XmlParserContext)	Creates a new XmlReader instance using the specified stream, XmlReaderSettings, and XmlParserContext objects.
	Create(String, XmlReaderSettings, XmlParserContext)	Creates a new XmlReader instance using the specified URI, XmlReaderSettings, and XmlParserContext objects.
	Create(TextReader, XmlReaderSettings, String)	Creates a new XmlReader instance using the specified TextReader, XmlReaderSettings, and base URI.
	Create(TextReader, XmlReaderSettings, XmlParserContext)	Creates a new XmlReader instance using the specified TextReader, XmlReaderSettings, and XmlParserContext objects.
	Dispose()	Releases all resources used by the current instance of the XmlReader class.
	Dispose(Boolean)	Releases the unmanaged resources used by the XmlReader and optionally releases the managed resources.
	Equals(Object)	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	GetAttribute(Int32)	When overridden in a derived class, gets the value of the attribute with the specified index.
	GetAttribute(String)	When overridden in a derived class, gets the value of the attribute with the specified Name.
	GetAttribute(String, String)	When overridden in a derived class, gets the value of the attribute with the specified LocalName and NamespaceURI.
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	GetValueAsync	Asynchronously gets the value of the current node.
	IsName	Gets a value indicating whether the string argument is a valid XML name.
	IsNameToken	Gets a value indicating whether or not the string argument is a valid XML name token.
	IsStartElement()	Calls MoveToContent and tests if the current content node is a start tag or empty element tag.
	IsStartElement(String)	Calls MoveToContent and tests if the current content node is a start tag or empty element tag and if the Name property of the element found matches the given argument.
	IsStartElement(String, String)	Calls MoveToContent and tests if the current content node is a start tag or empty element tag and if the LocalName and NamespaceURI properties of the element found match the given strings.
	LookupNamespace	When overridden in a derived class, resolves a namespace prefix in the current element's scope.
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	MoveToAttribute(Int32)	When overridden in a derived class, moves to the attribute with the specified index.
	MoveToAttribute(String)	When overridden in a derived class, moves to the attribute with the specified Name.
	MoveToAttribute(String, String)	When overridden in a derived class, moves to the attribute with the specified LocalName and NamespaceURI.
	MoveToContent	Checks whether the current node is a content (non-white space text, CDATA, Element, EndElement, EntityReference, or EndEntity) node. If the node is not a content node, the reader skips ahead to the next content node or end of file. It skips over nodes of the following type: ProcessingInstruction, DocumentType, Comment, Whitespace, or SignificantWhitespace.
	MoveToContentAsync	Asynchronously checks whether the current node is a content node. If the node is not a content node, the reader skips ahead to the next content node or end of file.
	MoveToElement	When overridden in a derived class, moves to the element that contains the current attribute node.
	MoveToFirstAttribute	When overridden in a derived class, moves to the first attribute.
	MoveToNextAttribute	When overridden in a derived class, moves to the next attribute.
	Read	When overridden in a derived class, reads the next node from the stream.
	ReadAsync	Asynchronously reads the next node from the stream.
	ReadAttributeValue	When overridden in a derived class, parses the attribute value into one or more Text, EntityReference, or EndEntity nodes.
	ReadContentAs	Reads the content as an object of the type specified.
	ReadContentAsAsync	Asynchronously reads the content as an object of the type specified.
	ReadContentAsBase64	Reads the content and returns the Base64 decoded binary bytes.
	ReadContentAsBase64Async	Asynchronously reads the content and returns the Base64 decoded binary bytes.
	ReadContentAsBinHex	Reads the content and returns the BinHex decoded binary bytes.
	ReadContentAsBinHexAsync	Asynchronously reads the content and returns the BinHex decoded binary bytes.
	ReadContentAsBoolean	Reads the text content at the current position as a Boolean.
	ReadContentAsDateTime	Reads the text content at the current position as a DateTime object.
	ReadContentAsDateTimeOffset	Reads the text content at the current position as a DateTimeOffset object.
	ReadContentAsDecimal	Reads the text content at the current position as a Decimal object.
	ReadContentAsDouble	Reads the text content at the current position as a double-precision floating-point number.
	ReadContentAsFloat	Reads the text content at the current position as a single-precision floating point number.
	ReadContentAsInt	Reads the text content at the current position as a 32-bit signed integer.
	ReadContentAsLong	Reads the text content at the current position as a 64-bit signed integer.
	ReadContentAsObject	Reads the text content at the current position as an Object.
	ReadContentAsObjectAsync	Asynchronously reads the text content at the current position as an Object.
	ReadContentAsString	Reads the text content at the current position as a String object.
	ReadContentAsStringAsync	Asynchronously reads the text content at the current position as a String object.
	ReadElementContentAs(Type, IXmlNamespaceResolver)	Reads the element content as the requested type.
	ReadElementContentAs(Type, IXmlNamespaceResolver, String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the element content as the requested type.
	ReadElementContentAsAsync	Asynchronously reads the element content as the requested type.
	ReadElementContentAsBase64	Reads the element and decodes the Base64 content.
	ReadElementContentAsBase64Async	Asynchronously reads the element and decodes the Base64 content.
	ReadElementContentAsBinHex	Reads the element and decodes the BinHex content.
	ReadElementContentAsBinHexAsync	Asynchronously reads the element and decodes the BinHex content.
	ReadElementContentAsBoolean()	Reads the current element and returns the contents as a Boolean object.
	ReadElementContentAsBoolean(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as a Boolean object.
	ReadElementContentAsDateTime()	Reads the current element and returns the contents as a DateTime object.
	ReadElementContentAsDateTime(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as a DateTime object.
	ReadElementContentAsDecimal()	Reads the current element and returns the contents as a Decimal object.
	ReadElementContentAsDecimal(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as a Decimal object.
	ReadElementContentAsDouble()	Reads the current element and returns the contents as a double-precision floating-point number.
	ReadElementContentAsDouble(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as a double-precision floating-point number.
	ReadElementContentAsFloat()	Reads the current element and returns the contents as single-precision floating-point number.
	ReadElementContentAsFloat(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as a single-precision floating-point number.
	ReadElementContentAsInt()	Reads the current element and returns the contents as a 32-bit signed integer.
	ReadElementContentAsInt(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as a 32-bit signed integer.
	ReadElementContentAsLong()	Reads the current element and returns the contents as a 64-bit signed integer.
	ReadElementContentAsLong(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as a 64-bit signed integer.
	ReadElementContentAsObject()	Reads the current element and returns the contents as an Object.
	ReadElementContentAsObject(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as an Object.
	ReadElementContentAsObjectAsync	Asynchronously reads the current element and returns the contents as an Object.
	ReadElementContentAsString()	Reads the current element and returns the contents as a String object.
	ReadElementContentAsString(String, String)	Checks that the specified local name and namespace URI matches that of the current element, then reads the current element and returns the contents as a String object.
	ReadElementContentAsStringAsync	Asynchronously reads the current element and returns the contents as a String object.
	ReadEndElement	Checks that the current content node is an end tag and advances the reader to the next node.
	ReadInnerXml	When overridden in a derived class, reads all the content, including markup, as a string.
	ReadInnerXmlAsync	Asynchronously reads all the content, including markup, as a string.
	ReadOuterXml	When overridden in a derived class, reads the content, including markup, representing this node and all its children.
	ReadOuterXmlAsync	Asynchronously reads the content, including markup, representing this node and all its children.
	ReadStartElement()	Checks that the current node is an element and advances the reader to the next node.
	ReadStartElement(String)	Checks that the current content node is an element with the given Name and advances the reader to the next node.
	ReadStartElement(String, String)	Checks that the current content node is an element with the given LocalName and NamespaceURI and advances the reader to the next node.
	ReadSubtree	Returns a new XmlReader instance that can be used to read the current node, and all its descendants.
	ReadToDescendant(String)	Advances the XmlReader to the next descendant element with the specified qualified name.
	ReadToDescendant(String, String)	Advances the XmlReader to the next descendant element with the specified local name and namespace URI.
	ReadToFollowing(String)	Reads until an element with the specified qualified name is found.
	ReadToFollowing(String, String)	Reads until an element with the specified local name and namespace URI is found.
	ReadToNextSibling(String)	Advances the XmlReader to the next sibling element with the specified qualified name.
	ReadToNextSibling(String, String)	Advances the XmlReader to the next sibling element with the specified local name and namespace URI.
	ReadValueChunk	Reads large streams of text embedded in an XML document.
	ReadValueChunkAsync	Asynchronously reads large streams of text embedded in an XML document.
	ResolveEntity	When overridden in a derived class, resolves the entity reference for EntityReference nodes.
	Skip	Skips the children of the current node.
	SkipAsync	Asynchronously skips the children of the current node.
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Remarks

XmlReader provides forward-only, read-only access to a stream of XML data. The XmlReader class conforms to the W3C Extensible Markup Language (XML) 1.0 and the Namespaces in XML recommendations.

The current node refers to the node on which the reader is positioned. The reader is advanced using any of the read methods and properties reflect the value of the current node.

Important Note:
You must use Create method to create XmlReader instances.

XmlReader throws an XmlException on XML parse errors. After an exception is thrown the state of the reader is not predictable. For example, the reported node type may be different than the actual node type of the current node. Use the ReadState property to check whether the reader is in error state.

Security Considerations

The following items are things to consider when working with the XmlReader class.

Exceptions thrown the XmlReader can disclose path information that you do not want bubbled up to the application. Your applications must catch exceptions and process them appropriately.
Do not enable DTD processing if you are concerned about denial of service issues or if you are dealing with untrusted sources. DTD processing is disabled by default for XmlReader objects created by the Create method.
You can design your application so that the XML processing is memory and time constrained. For example, configure time-out limits in your ASP.NET application.
XML data can contain a large number of attributes, namespace declarations, nested elements and so on that require a substantial amount of time to process. To limit the size of the input that is sent to the XmlReader, create a custom IStream implementation and supply it the XmlReader.
The ReadValueChunk method can be used to handle large streams of data. This method reads a small number of characters at a time instead of allocating a single string for the whole value.
When reading an XML document with a large number of unique local names, namespaces, or prefixes, a problem can occur. If you are using class that derives from XmlReader, and you call either the LocalName, Prefix, or NamespaceURI property for each item, the returned string is added to a NameTable. The collection held by the NameTable never decreases in size, creating a virtual "memory leak" of the string handles. One mitigation for this is to derive from the NameTable class and enforce a maximum size quota. (There is no way to prevent the use of a NameTable, or to switch the NameTable when it is full). Another mitigation is to avoid using the properties mentioned and instead use the MoveToAttribute method with the IsStartElement method where possible; those methods do not return strings and thus avoid the problem of overfilling the NameTable collection.