Class XmlSingleStreamExtractor<TRecord>

Namespace: Wolfgang.Etl.Xml

Assembly: Wolfgang.Etl.Xml.dll

Extracts items of type TRecord from a single XML stream containing a root element with child elements.

public sealed class XmlSingleStreamExtractor<TRecord> : ExtractorBase<TRecord, XmlReport>, IExtractWithProgressAndCancellationAsync<TRecord, XmlReport>, IExtractWithCancellationAsync<TRecord>, IExtractWithProgressAsync<TRecord, XmlReport>, IExtractAsync<TRecord> where TRecord : notnull, new()

Type Parameters

TRecord: The type of items to extract. Must be notnull and have a parameterless constructor.

Inheritance: object

ExtractorBase<TRecord, XmlReport>

XmlSingleStreamExtractor<TRecord>

Implements: IExtractWithProgressAndCancellationAsync<TRecord, XmlReport>

IExtractWithCancellationAsync<TRecord>

IExtractWithProgressAsync<TRecord, XmlReport>

IExtractAsync<TRecord>

Inherited Members: ExtractorBase<TRecord, XmlReport>.ExtractAsync()

ExtractorBase<TRecord, XmlReport>.ExtractAsync(CancellationToken)

ExtractorBase<TRecord, XmlReport>.ExtractAsync(IProgress<XmlReport>)

ExtractorBase<TRecord, XmlReport>.ExtractAsync(IProgress<XmlReport>, CancellationToken)

ExtractorBase<TRecord, XmlReport>.ReportingInterval

ExtractorBase<TRecord, XmlReport>.CurrentItemCount

ExtractorBase<TRecord, XmlReport>.CurrentSkippedItemCount

ExtractorBase<TRecord, XmlReport>.MaximumItemCount

ExtractorBase<TRecord, XmlReport>.SkipItemCount

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Leave stream open (default) — caller controls stream lifetime:
using var stream = File.OpenRead("data.xml");
var extractor = new XmlSingleStreamExtractor<Person>(stream);
await foreach (var person in extractor.ExtractAsync(cancellationToken))
{
    Console.WriteLine(person.Name);
}

// Transfer stream ownership — closed automatically when extraction completes:
var extractor = new XmlSingleStreamExtractor<Person>
(
    File.OpenRead("data.xml"),
    new XmlSingleStreamExtractorOptions { LeaveOpen = false }
);
await foreach (var person in extractor.ExtractAsync(cancellationToken))
{
    Console.WriteLine(person.Name);
}

Remarks

Reads an XML document (e.g. <ArrayOfPerson><Person/>...</ArrayOfPerson>) from a Stream and yields each deserialized child element as an item in the async enumerable sequence. Uses XmlReader for streaming deserialization so that the entire document is not buffered in memory.

By default the stream is left open after extraction completes. To have the stream closed automatically when extraction finishes, set LeaveOpen to false, mirroring the behaviour of StreamReader and BinaryReader.

Constructors

XmlSingleStreamExtractor(Stream, ILogger<XmlSingleStreamExtractor<TRecord>>)

Initializes a new instance of the XmlSingleStreamExtractor<TRecord> class with a logger.

public XmlSingleStreamExtractor(Stream stream, ILogger<XmlSingleStreamExtractor<TRecord>> logger)

Parameters

stream Stream: The stream containing XML data to read from.
logger ILogger<XmlSingleStreamExtractor<TRecord>>: The logger instance for diagnostic output.

Exceptions

ArgumentNullException: Thrown when stream or logger is null.

XmlSingleStreamExtractor(Stream, XmlReaderSettings, ILogger<XmlSingleStreamExtractor<TRecord>>, XmlSingleStreamExtractorOptions?)

Initializes a new instance of the XmlSingleStreamExtractor<TRecord> class with custom reader settings.

public XmlSingleStreamExtractor(Stream stream, XmlReaderSettings readerSettings, ILogger<XmlSingleStreamExtractor<TRecord>> logger, XmlSingleStreamExtractorOptions? options = null)

Parameters

stream Stream: The stream containing XML data to read from.
readerSettings XmlReaderSettings: The XML reader settings to use for deserialization.
logger ILogger<XmlSingleStreamExtractor<TRecord>>: The logger instance for diagnostic output.
options XmlSingleStreamExtractorOptions: Options that control extractor behaviour. When null, defaults are used.

Exceptions

ArgumentNullException: Thrown when stream, readerSettings, or logger is null.

XmlSingleStreamExtractor(Stream, XmlSingleStreamExtractorOptions?)

Initializes a new instance of the XmlSingleStreamExtractor<TRecord> class.

public XmlSingleStreamExtractor(Stream stream, XmlSingleStreamExtractorOptions? options = null)

Parameters

stream Stream: The stream containing XML data to read from.
options XmlSingleStreamExtractorOptions: Options that control extractor behaviour. When null, defaults are used.

Exceptions

ArgumentNullException: Thrown when stream is null.

Methods

CreateProgressReport()

Creates a progress report of type TProgress. This gives the derived class the opportunity to implement a custom progress report that is specific to the extraction process.

protected override XmlReport CreateProgressReport()

Returns

XmlReport: Progress of type TProgress

CreateProgressTimer(IProgress<XmlReport>)

Creates the Wolfgang.Etl.Abstractions.IProgressTimer used to drive progress callbacks. Override this method in a derived class to inject a custom timer (for example, a custom implementation that allows manual control in unit tests).

protected override IProgressTimer CreateProgressTimer(IProgress<XmlReport> progress)

Parameters

progress IProgress<XmlReport>: The progress sink that will receive callbacks.

Returns

IProgressTimer: A started Wolfgang.Etl.Abstractions.IProgressTimer instance.

ExtractWorkerAsync(CancellationToken)

This method is the core implementation of the extraction logic and should be overridden by derived classes.

protected override IAsyncEnumerable<TRecord> ExtractWorkerAsync(CancellationToken token)

Parameters

token CancellationToken: A CancellationToken to observe while waiting for the task to complete.

Returns

IAsyncEnumerable<TRecord>: IAsyncEnumerable<TSource> The result may be an empty sequence if no data is available or if the extraction fails.