XmlReader Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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

[DefaultMemberAttribute("Item")]
public abstract class XmlReader : IDisposable

The XmlReader type exposes the following members.

Constructors

  Name Description
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 XmlReader Initializes a new instance of the XmlReader class.

Top

Properties

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

Top

Methods

  Name Description
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Close When overridden in a derived class, changes the ReadState to Closed.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(Stream) Creates a new XmlReader instance using the specified stream.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(String) Creates a new XmlReader instance with specified URI.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(TextReader) Creates a new XmlReader instance with the specified TextReader.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(Stream, XmlReaderSettings) Creates a new XmlReader instance with the specified stream and XmlReaderSettings object.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(String, XmlReaderSettings) Creates a new instance with the specified URI and XmlReaderSettings.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(TextReader, XmlReaderSettings) Creates a new XmlReader instance using the specified TextReader and XmlReaderSettings objects.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(XmlReader, XmlReaderSettings) Creates a new XmlReader instance with the specified XmlReader and XmlReaderSettings objects.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(Stream, XmlReaderSettings, String) Creates a new XmlReader instance using the specified stream, base URI, and XmlReaderSettings object.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(Stream, XmlReaderSettings, XmlParserContext) Creates a new XmlReader instance using the specified stream, XmlReaderSettings, and XmlParserContext objects.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(String, XmlReaderSettings, XmlParserContext) Creates a new XmlReader instance using the specified URI, XmlReaderSettings, and XmlParserContext objects.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(TextReader, XmlReaderSettings, String) Creates a new XmlReader instance using the specified TextReader, XmlReaderSettings, and base URI.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 Create(TextReader, XmlReaderSettings, XmlParserContext) Creates a new XmlReader instance using the specified TextReader, XmlReaderSettings, and XmlParserContext objects.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Dispose()
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Dispose(Boolean) Releases the unmanaged resources used by the XmlReader and optionally releases the managed resources.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Equals(Object) Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 GetAttribute(Int32) When overridden in a derived class, gets the value of the attribute with the specified index.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 GetAttribute(String) When overridden in a derived class, gets the value of the attribute with the specified Name.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 GetAttribute(String, String) When overridden in a derived class, gets the value of the attribute with the specified LocalName and NamespaceURI.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 GetType Gets the Type of the current instance. (Inherited from Object.)
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 IsName Gets a value indicating whether the string argument is a valid XML name.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360 IsNameToken Gets a value indicating whether or not the string argument is a valid XML name token.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 IsStartElement() Calls MoveToContent and tests if the current content node is a start tag or empty element tag.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 LookupNamespace When overridden in a derived class, resolves a namespace prefix in the current element's scope.
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MoveToAttribute(Int32) When overridden in a derived class, moves to the attribute with the specified index.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MoveToAttribute(String) When overridden in a derived class, moves to the attribute with the specified Name.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MoveToAttribute(String, String) When overridden in a derived class, moves to the attribute with the specified LocalName and NamespaceURI.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MoveToElement When overridden in a derived class, moves to the element that contains the current attribute node.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MoveToFirstAttribute When overridden in a derived class, moves to the first attribute.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 MoveToNextAttribute When overridden in a derived class, moves to the next attribute.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Read When overridden in a derived class, reads the next node from the stream.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadAttributeValue When overridden in a derived class, parses the attribute value into one or more Text, EntityReference, or EndEntity nodes.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAs Reads the content as an object of the type specified.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsBase64 Reads the content and returns the Base64 decoded binary bytes.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsBinHex Reads the content and returns the BinHex decoded binary bytes.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsBoolean Reads the text content at the current position as a Boolean.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsDateTime Reads the text content at the current position as a DateTime object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsDecimal Reads the text content at the current position as a Decimal object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsDouble Reads the text content at the current position as a double-precision floating-point number.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsFloat Reads the text content at the current position as a single-precision floating point number.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsInt Reads the text content at the current position as a 32-bit signed integer.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsLong Reads the text content at the current position as a 64-bit signed integer.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsObject Reads the text content at the current position as an Object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadContentAsString Reads the text content at the current position as a String object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAs(Type, IXmlNamespaceResolver) Reads the element content as the requested type.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsBase64 Reads the element and decodes the Base64 content.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsBinHex Reads the element and decodes the BinHex content.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsBoolean() Reads the current element and returns the contents as a Boolean object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsDateTime() Reads the current element and returns the contents as a DateTime object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsDecimal() Reads the current element and returns the contents as a Decimal object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsDouble() Reads the current element and returns the contents as a double-precision floating-point number.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsFloat() Reads the current element and returns the contents as single-precision floating-point number.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsInt() Reads the current element and returns the contents as a 32-bit signed integer.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsLong() Reads the current element and returns the contents as a 64-bit signed integer.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsObject() Reads the current element and returns the contents as an Object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadElementContentAsString() Reads the current element and returns the contents as a String object.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadEndElement Checks that the current content node is an end tag and advances the reader to the next node.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadInnerXml When overridden in a derived class, reads all the content, including markup, as a string.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadOuterXml When overridden in a derived class, reads the content, including markup, representing this node and all its children.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadStartElement() Checks that the current node is an element and advances the reader to the next node.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadStartElement(String) Checks that the current content node is an element with the given Name and advances the reader to the next node.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 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.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadSubtree Returns a new XmlReader instance that can be used to read the current node, and all its descendants.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadToDescendant(String) Advances the XmlReader to the next descendant element with the specified qualified name.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadToDescendant(String, String) Advances the XmlReader to the next descendant element with the specified local name and namespace URI.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadToFollowing(String) Reads until an element with the specified qualified name is found.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadToFollowing(String, String) Reads until an element with the specified local name and namespace URI is found.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadToNextSibling(String) Advances the XmlReader to the next sibling element with the specified qualified name.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadToNextSibling(String, String) Advances the XmlReader to the next sibling element with the specified local name and namespace URI.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ReadValueChunk Reads large streams of text embedded in an XML document.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ResolveEntity When overridden in a derived class, resolves the entity reference for EntityReference nodes.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 Skip Skips the children of the current node.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360 ToString Returns a string that represents the current object. (Inherited from Object.)

Top

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 noteImportant 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.

Platform Notes

Silverlight for Windows Phone Silverlight for Windows Phone

  XmlReader does not fail when numeric character entity computation overflows. Instead, an empty string is returned to Value.

Examples

The following example navigates through the stream to determine the current node type, and then uses XmlWriter to output the XmlReader content.

StringBuilder output = new StringBuilder();

String xmlString =
        @"<?xml version='1.0'?>
        <!-- This is a sample XML document -->
        <Items>
          <Item>test with a child element <more/> stuff</Item>
        </Items>";
// Create an XmlReader
using (XmlReader reader = XmlReader.Create(new StringReader(xmlString)))
{
    XmlWriterSettings ws = new XmlWriterSettings();
    ws.Indent = true;
    using (XmlWriter writer = XmlWriter.Create(output, ws))
    {

        // Parse the file and display each of the nodes.
        while (reader.Read())
        {
            switch (reader.NodeType)
            {
                case XmlNodeType.Element:
                    writer.WriteStartElement(reader.Name);
                    break;
                case XmlNodeType.Text:
                    writer.WriteString(reader.Value);
                    break;
                case XmlNodeType.XmlDeclaration:
                case XmlNodeType.ProcessingInstruction:
                    writer.WriteProcessingInstruction(reader.Name, reader.Value);
                    break;
                case XmlNodeType.Comment:
                    writer.WriteComment(reader.Value);
                    break;
                case XmlNodeType.EndElement:
                    writer.WriteFullEndElement();
                    break;
            }
        }

    }
}
OutputTextBlock.Text = output.ToString();

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.