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>, IReportsItemErrors, IAsyncDisposable, IDisposable 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>

IReportsItemErrors

IAsyncDisposable

IDisposable

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>.DisposeAsync()

ExtractorBase<TRecord, XmlReport>.Dispose()

ExtractorBase<TRecord, XmlReport>.ReportingInterval

ExtractorBase<TRecord, XmlReport>.CurrentItemCount

ExtractorBase<TRecord, XmlReport>.CurrentSkippedItemCount

ExtractorBase<TRecord, XmlReport>.CurrentErrorItemCount

ExtractorBase<TRecord, XmlReport>.MaximumItemCount

ExtractorBase<TRecord, XmlReport>.SkipItemCount

ExtractorBase<TRecord, XmlReport>.WorkerResilience

ExtractorBase<TRecord, XmlReport>.ErrorPolicy

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 owningExtractor = new XmlSingleStreamExtractor<Person>
(
    File.OpenRead("data.xml"),
    new XmlSingleStreamExtractorOptions { LeaveOpen = false }
);
await foreach (var person in owningExtractor.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.

[RequiresUnreferencedCode("XmlSingleStreamExtractor deserializes TRecord via System.Xml.Serialization.XmlSerializer, which uses runtime reflection/Reflection.Emit the trimmer cannot follow. The library is not trim/NativeAOT safe.")]
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.

[RequiresUnreferencedCode("XmlSingleStreamExtractor deserializes TRecord via System.Xml.Serialization.XmlSerializer, which uses runtime reflection/Reflection.Emit the trimmer cannot follow. The library is not trim/NativeAOT safe.")]
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.

[RequiresUnreferencedCode("XmlSingleStreamExtractor deserializes TRecord via System.Xml.Serialization.XmlSerializer, which uses runtime reflection/Reflection.Emit the trimmer cannot follow. The library is not trim/NativeAOT safe.")]
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.

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

Initializes a new instance of the XmlSingleStreamExtractor<TRecord> class. This is the canonical constructor — every other overload delegates to it — and it is the only one that lets options and logger be supplied together without also supplying XmlReaderSettings.

[RequiresUnreferencedCode("XmlSingleStreamExtractor deserializes TRecord via System.Xml.Serialization.XmlSerializer, which uses runtime reflection/Reflection.Emit the trimmer cannot follow. The library is not trim/NativeAOT safe.")]
public XmlSingleStreamExtractor(Stream stream, XmlSingleStreamExtractorOptions? options, ILogger<XmlSingleStreamExtractor<TRecord>>? logger = null)

Parameters

stream Stream: The stream containing XML data to read from.
options XmlSingleStreamExtractorOptions: Options that control extractor behaviour. When null, defaults are used.
logger ILogger<XmlSingleStreamExtractor<TRecord>>: An optional logger instance for diagnostic output. When null, logging is disabled.

Examples

// Options and a logger, without having to supply XmlReaderSettings:
var extractor = new XmlSingleStreamExtractor<Person>
(
    stream,
    options: new XmlSingleStreamExtractorOptions { LeaveOpen = false },
    logger: loggerFactory.CreateLogger<XmlSingleStreamExtractor<Person>>()
);

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.