System.Xml.XmlReader Class

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

See Also: XmlReader Members

Syntax

public abstract class XmlReader : IDisposable

Remarks

System.Xml.XmlReader provides forward-only, read-only access to a stream of XML data. The System.Xml.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.

Note:

Although the .NET Framework includes concrete implementations of the System.Xml.XmlReader class, such as the System.Xml.XmlTextReader, System.Xml.XmlNodeReader, and the System.Xml.XmlValidatingReader classes, in the 2.0 release the recommended practice is to create System.Xml.XmlReader instances using the erload:System.Xml.XmlReader.Create method. For more information, see Creating XML Readers.

System.Xml.XmlReader throws an System.Xml.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 from the actual node type of the current node. Use the XmlReader.ReadState property to check whether the reader is in error state.

For further discussion on the System.Xml.XmlReader class, see Reading XML with the XmlReader.

The following methods can be used with asynchronous method calls:

Some synchronous methods have asynchronous counterparts that include "Async" at the end of the method name. For example, the asynchronous equivalents for the ReadContentAsXxx and ReadElementContentAsXxx methods are:

The following sections describe asynchronous usage for methods that don't have asynchronous counterparts.

ReadStartElement method

Example

public static async Task ReadStartElementAsync(this XmlReader reader, string localname, string ns) {
 if (await 
   reader.MoveToContentAsync() != 
   XmlNodeType.Element) {
 throw new 
InvalidOperationException(
reader.NodeType.ToString() + " is an invalid XmlNodeType");
   }
 if (reader.LocalName == 
     localname && 
     reader.NamespaceURI == ns) {
 await reader.ReadAsync();
   }
 else {
 throw new InvalidOperationException("localName or namespace doesn’t match");
    }
}

ReadEndElement method

Extension function:

Example

public static async Task ReadEndElementAsync(this XmlReader reader) {
if (await reader.MoveToContentAsync() != XmlNodeType.EndElement) {
    throw new InvalidOperationException();
   }
 await reader.ReadAsync();
}

ReadToNextSibling method

Example

public static async Task<bool> ReadToNextSiblingAsync(this XmlReader reader, string localName, string namespaceURI) {
 if (localName == null || 
    localName.Length == 0) {
 throw new ArgumentException ("localName is empty or null");
   }
 if (namespaceURI == null) {
 throw new ArgumentNullException("namespaceURI");
   }

// atomize local name and namespace
   localName = 
    reader.NameTable.Add(localName);
   namespaceURI = 
   reader.NameTable.Add(namespaceURI);

// find the next sibling
 XmlNodeType nt;
 do {
 await reader.SkipAsync();
 if (reader.ReadState !=
 ReadState.Interactive)
 break;
      nt = reader.NodeType;
 if (nt == XmlNodeType.Element &&
      ((object)localName == 
      (object)reader.LocalName) && 
      ((object)namespaceURI == 
      (object)reader.NamespaceURI)) {
 return true;
       }
   }while(nt != XmlNodeType.EndElement 

   && !reader.EOF);
 return false;
}

ReadToFollowing method

Example

public static async Task<bool> ReadToFollowingAsync(this XmlReader reader, string localName, string namespaceURI) 
{
 if (localName == null || 
     localName.Length == 0) {
 throw new 
     ArgumentException(
     "localName is empty or null");
   }
 if (namespaceURI == null) {
 throw new 
      ArgumentNullException(
     "namespaceURI");
}

// atomize local name and namespace
   localName = 
    reader.NameTable.Add(localName);
   namespaceURI = 
   reader.NameTable.Add(namespaceURI);

// find element with that name
 while (await reader.ReadAsync()) {
 if (reader.NodeType == XmlNodeType.Element && ((object)localName == (object)reader.LocalName) && ((object)namespaceURI == (object)reader.NamespaceURI)) {
 return true;
      }
   }
 return false;
}

ReadToDescendant method

Example

public static async Task<bool> ReadToDescendantAsync(this XmlReader reader, string localName, string namespaceURI) {
 if (localName == null || localName.Length == 0) {
 throw new ArgumentException("localName is empty or null");
   }
 if (namespaceURI == null) {
 throw new ArgumentNullException("namespaceURI");
   }
 // save the element or root depth
 int parentDepth = reader.Depth;
 if (reader.NodeType != XmlNodeType.Element) {
 // adjust the depth if we are on root node
if (reader.ReadState == ReadState.Initial) {
    parentDepth--;
   }
else {
     return false;
       }
   }
else if (reader.IsEmptyElement) {
   return false;
}

// atomize local name and namespace
localName = reader.NameTable.Add(localName);
namespaceURI = reader.NameTable.Add(namespaceURI);

// find the descendant
while (await reader.ReadAsync() && reader.Depth > parentDepth) {
if (reader.NodeType == XmlNodeType.Element && ((object)localName == (object)reader.LocalName) && ((object)namespaceURI == (object)reader.NamespaceURI)) {
 return true;
}
}
return false;
}

Security considerations

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

Thread Safety

All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe.

Requirements

Namespace: System.Xml
Assembly: System.Xml (in System.Xml.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0, 4.0.0.0