Class XmlSingleStreamLoader<TRecord>

Namespace: Wolfgang.Etl.Xml

Assembly: Wolfgang.Etl.Xml.dll

Loads items of type TRecord into a single XML stream wrapped in a root element.

public sealed class XmlSingleStreamLoader<TRecord> : LoaderBase<TRecord, XmlReport>, ILoadWithProgressAndCancellationAsync<TRecord, XmlReport>, ILoadWithProgressAsync<TRecord, XmlReport>, ILoadWithCancellationAsync<TRecord>, ILoadAsync<TRecord> where TRecord : notnull, new()

Type Parameters

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

Inheritance: object

LoaderBase<TRecord, XmlReport>

XmlSingleStreamLoader<TRecord>

Implements: ILoadWithProgressAndCancellationAsync<TRecord, XmlReport>

ILoadWithProgressAsync<TRecord, XmlReport>

ILoadWithCancellationAsync<TRecord>

ILoadAsync<TRecord>

Inherited Members: LoaderBase<TRecord, XmlReport>.LoadAsync(IAsyncEnumerable<TRecord>)

LoaderBase<TRecord, XmlReport>.LoadAsync(IAsyncEnumerable<TRecord>, CancellationToken)

LoaderBase<TRecord, XmlReport>.LoadAsync(IAsyncEnumerable<TRecord>, IProgress<XmlReport>)

LoaderBase<TRecord, XmlReport>.LoadAsync(IAsyncEnumerable<TRecord>, IProgress<XmlReport>, CancellationToken)

LoaderBase<TRecord, XmlReport>.ReportingInterval

LoaderBase<TRecord, XmlReport>.CurrentItemCount

LoaderBase<TRecord, XmlReport>.CurrentSkippedItemCount

LoaderBase<TRecord, XmlReport>.MaximumItemCount

LoaderBase<TRecord, XmlReport>.SkipItemCount

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Default root element name (ArrayOfPerson), stream left open:
using var stream = File.Create("output.xml");
var loader = new XmlSingleStreamLoader<Person>(stream);
await loader.LoadAsync(items, cancellationToken);

// Custom root element name, stream closed automatically:
var loader = new XmlSingleStreamLoader<Person>
(
    File.Create("output.xml"),
    new XmlSingleStreamLoaderOptions
    {
        RootElementName = "People",
        LeaveOpen = false,
    }
);
await loader.LoadAsync(items, cancellationToken);

Remarks

Writes an XML document to a Stream by serializing each item from the input async enumerable sequence as a child element of a configurable root element. The root element name defaults to ArrayOf{TypeName} (e.g. ArrayOfPerson) but can be overridden via RootElementName. Each item is serialized using XmlSerializer.

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

Constructors

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

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

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

Parameters

stream Stream: The stream to write XML data to.
logger ILogger<XmlSingleStreamLoader<TRecord>>: The logger instance for diagnostic output.

Exceptions

ArgumentNullException: Thrown when stream or logger is null.

XmlSingleStreamLoader(Stream, XmlWriterSettings, ILogger<XmlSingleStreamLoader<TRecord>>, XmlSingleStreamLoaderOptions?)

Initializes a new instance of the XmlSingleStreamLoader<TRecord> class with custom writer settings.

public XmlSingleStreamLoader(Stream stream, XmlWriterSettings writerSettings, ILogger<XmlSingleStreamLoader<TRecord>> logger, XmlSingleStreamLoaderOptions? options = null)

Parameters

stream Stream: The stream to write XML data to.
writerSettings XmlWriterSettings: The XML writer settings to use for serialization.
logger ILogger<XmlSingleStreamLoader<TRecord>>: The logger instance for diagnostic output.
options XmlSingleStreamLoaderOptions: Options that control loader behaviour. When null, defaults are used.

Exceptions

ArgumentNullException: Thrown when stream, writerSettings, or logger is null.
ArgumentException: Thrown when RootElementName is an empty or whitespace string.

XmlSingleStreamLoader(Stream, XmlSingleStreamLoaderOptions?)

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

public XmlSingleStreamLoader(Stream stream, XmlSingleStreamLoaderOptions? options = null)

Parameters

stream Stream: The stream to write XML data to.
options XmlSingleStreamLoaderOptions: Options that control loader behaviour. When null, defaults are used.

Exceptions

ArgumentNullException: Thrown when stream is null.
ArgumentException: Thrown when RootElementName is an empty or whitespace string.

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

LoadWorkerAsync(IAsyncEnumerable<TRecord>, CancellationToken)

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

protected override Task LoadWorkerAsync(IAsyncEnumerable<TRecord> items, CancellationToken token)

Parameters

items IAsyncEnumerable<TRecord>: The items to be loaded to the destination.
token CancellationToken: A CancellationToken to observe while waiting for the task to complete.

Returns

Task: A task representing the asynchronous operation.

Remarks

Items may be an empty sequence if no data is available or if the loading fails.

Exceptions

ArgumentNullException: Argument items is null