Class XmlReaderExtensions

Namespace

Cuemon.Extensions.Xml

Assembly

Cuemon.Extensions.Xml.dll

Extension methods for the XmlReader class.

public static class XmlReaderExtensions

Inheritance

object

XmlReaderExtensions

Examples

XmlReaderExtensions provides extension methods for XmlReader including navigation, hierarchy building, chunked reading, and stream conversion. This example starts with an XML string containing <root> and two <item> elements, then demonstrates MoveToFirstElement to position at the first element, ToHierarchy to build a tree of element nodes with child names, Chunk(1) to stream only the first element as a new indented XmlReader, and ToStream to convert the entire reader content into a readable stream. Console output shows the root element name ("root"), a hierarchy description with child names, the outer XML of the first chunk (<item id="1">First</item>), and the full XML content.

using System;
using System.IO;
using System.Linq;
using System.Xml;
using Cuemon.Extensions.Xml;

namespace DocExamples;

public static class XmlReaderExtensionsExample
{
    private const string XmlDocument = "<?xml version=\"1.0\" encoding=\"utf-8\"?><root><item id=\"1\">First</item><item id=\"2\">Second</item></root>";

    public static void Demonstrate()
    {
        Console.WriteLine(GetRootName());
        Console.WriteLine(DescribeHierarchy());
        Console.WriteLine(ReadFirstChunk());
        Console.WriteLine(CopyXml());
    }

    private static string GetRootName()
    {
        using var xmlReader = XmlReader.Create(new StringReader(XmlDocument));
        return xmlReader.MoveToFirstElement() ? xmlReader.LocalName : string.Empty;
    }

    private static string DescribeHierarchy()
    {
        using var xmlReader = XmlReader.Create(new StringReader(XmlDocument));
        var hierarchy = xmlReader.ToHierarchy();
        var childNames = string.Join(", ", hierarchy.GetChildren().Select(child => child.Instance.Name));
        return $"{hierarchy.Instance.Name}: {childNames}";
    }

    private static string ReadFirstChunk()
    {
        using var xmlReader = XmlReader.Create(new StringReader(XmlDocument));
        using var firstChunk = xmlReader.Chunk(1, settings => settings.Indent = true).First();

        firstChunk.MoveToFirstElement();
        return firstChunk.ReadOuterXml();
    }

    private static string CopyXml()
    {
        using var xmlReader = XmlReader.Create(new StringReader(XmlDocument));
        using var xmlStream = xmlReader.ToStream();
        using var streamReader = new StreamReader(xmlStream);

        return streamReader.ReadToEnd();
    }
}

Methods

Chunk(XmlReader, int, Action<XmlWriterSettings>)

Creates and returns a sequence of chunked XmlReader instances with a maximum of the specified size of XML node elements located on a depth of 1.

public static IEnumerable<XmlReader> Chunk(this XmlReader reader, int size = 128, Action<XmlWriterSettings> setup = null)

Parameters

reader XmlReader

The XmlReader to extend.

size int

The amount of XML node elements allowed per XmlReader object. Default is 128 XML node element.

setup Action<XmlWriterSettings>

The XmlWriterSettings which may be configured.

Returns

IEnumerable<XmlReader>

An sequence of XmlReader instances that contains no more than the specified size of XML node elements from the reader object.

Exceptions

ArgumentNullException

reader is null.

ArgumentException

The Read() method of the reader object has already been called.

MoveToFirstElement(XmlReader)

Moves the reader to the first element.

public static bool MoveToFirstElement(this XmlReader reader)

Parameters

reader XmlReader

The XmlReader to extend.

Returns

bool

true if an element exists (the reader moves to the first element), otherwise, false (the reader has reached EOF).

Exceptions

ArgumentNullException

reader is null.

ArgumentException

The Read() method of the reader object has already been called.

ToHierarchy(XmlReader)

Converts the XML hierarchy of the reader into an IHierarchy<T>.

public static IHierarchy<DataPair> ToHierarchy(this XmlReader reader)

Parameters

reader XmlReader

The XmlReader to extend.

Returns

IHierarchy<DataPair>

An IHierarchy{DataPair} implementation.

Exceptions

ArgumentNullException

reader cannot be null.

ToStream(XmlReader, Action<XmlCopyOptions>)

Copies everything from the specified reader and returns the result as an XML stream.

public static Stream ToStream(this XmlReader reader, Action<XmlCopyOptions> setup = null)

Parameters

reader XmlReader

The XmlReader to extend.

setup Action<XmlCopyOptions>

The XmlCopyOptions which may be configured.

Returns

Stream

A Stream holding an exact copy of the source reader.

Exceptions

ArgumentNullException

reader is null.

ToStream(XmlReader, Action<XmlWriter, XmlReader, DisposableOptions>, Action<XmlCopyOptions>)

Copies the specified reader using the specified delegate copier and returns the result as an XML stream.

public static Stream ToStream(this XmlReader reader, Action<XmlWriter, XmlReader, DisposableOptions> copier, Action<XmlCopyOptions> setup = null)

Parameters

reader XmlReader

The XmlReader to extend.

copier Action<XmlWriter, XmlReader, DisposableOptions>

The delegate that will create an in-memory copy of reader as a XML stream.

setup Action<XmlCopyOptions>

The XmlCopyOptions which may be configured.

Returns

Stream

A Stream holding the XML copied by the delegate copier from the source reader.

Exceptions

ArgumentNullException

reader is null - or - copier is null.