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

IReportsItemErrors

IAsyncDisposable

IDisposable

ISupportDryRun

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

LoaderBase<TRecord, XmlReport>.Dispose()

LoaderBase<TRecord, XmlReport>.ReportingInterval

LoaderBase<TRecord, XmlReport>.CurrentItemCount

LoaderBase<TRecord, XmlReport>.CurrentSkippedItemCount

LoaderBase<TRecord, XmlReport>.CurrentErrorItemCount

LoaderBase<TRecord, XmlReport>.MaximumItemCount

LoaderBase<TRecord, XmlReport>.SkipItemCount

LoaderBase<TRecord, XmlReport>.WorkerResilience

LoaderBase<TRecord, XmlReport>.ErrorPolicy

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 owningLoader = new XmlSingleStreamLoader<Person>
(
    File.Create("output.xml"),
    new XmlSingleStreamLoaderOptions
    {
        RootElementName = "People",
        LeaveOpen = false,
    }
);
await owningLoader.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(IBufferWriter<byte>, ILogger<XmlSingleStreamLoader<TRecord>>)

Initializes a new instance of the XmlSingleStreamLoader<TRecord> class writing to an IBufferWriter<T> of bytes (#8) with a logger.

[RequiresUnreferencedCode("XmlSingleStreamLoader serializes TRecord via System.Xml.Serialization.XmlSerializer, which uses runtime reflection/Reflection.Emit the trimmer cannot follow. The library is not trim/NativeAOT safe.")]
public XmlSingleStreamLoader(IBufferWriter<byte> bufferWriter, ILogger<XmlSingleStreamLoader<TRecord>> logger)

Parameters

bufferWriter IBufferWriter<byte>: The buffer writer to write XML data to.
logger ILogger<XmlSingleStreamLoader<TRecord>>: The logger instance for diagnostic output.

Exceptions

ArgumentNullException: Thrown when bufferWriter or logger is null.

XmlSingleStreamLoader(IBufferWriter<byte>, XmlWriterSettings, ILogger<XmlSingleStreamLoader<TRecord>>, XmlSingleStreamLoaderOptions?)

Initializes a new instance of the XmlSingleStreamLoader<TRecord> class writing to an IBufferWriter<T> of bytes (#8) with custom writer settings.

[RequiresUnreferencedCode("XmlSingleStreamLoader serializes TRecord via System.Xml.Serialization.XmlSerializer, which uses runtime reflection/Reflection.Emit the trimmer cannot follow. The library is not trim/NativeAOT safe.")]
public XmlSingleStreamLoader(IBufferWriter<byte> bufferWriter, XmlWriterSettings writerSettings, ILogger<XmlSingleStreamLoader<TRecord>> logger, XmlSingleStreamLoaderOptions? options = null)

Parameters

bufferWriter IBufferWriter<byte>: The buffer writer 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 bufferWriter, writerSettings, or logger is null.

XmlSingleStreamLoader(IBufferWriter<byte>, XmlSingleStreamLoaderOptions?)

Initializes a new instance of the XmlSingleStreamLoader<TRecord> class that writes to an IBufferWriter<T> of bytes instead of a Stream (#8) — serialized bytes flow straight into the buffer writer with no intermediate stream buffering.

[RequiresUnreferencedCode("XmlSingleStreamLoader serializes TRecord via System.Xml.Serialization.XmlSerializer, which uses runtime reflection/Reflection.Emit the trimmer cannot follow. The library is not trim/NativeAOT safe.")]
public XmlSingleStreamLoader(IBufferWriter<byte> bufferWriter, XmlSingleStreamLoaderOptions? options = null)

Parameters

bufferWriter IBufferWriter<byte>: The buffer writer to write XML data to.
options XmlSingleStreamLoaderOptions: Options that control loader behaviour. When null, defaults are used.

Exceptions

ArgumentNullException: Thrown when bufferWriter is null.

XmlSingleStreamLoader(IBufferWriter<byte>, XmlSingleStreamLoaderOptions?, ILogger<XmlSingleStreamLoader<TRecord>>?)

Initializes a new instance of the XmlSingleStreamLoader<TRecord> class writing to an IBufferWriter<T> of bytes (#8). This is the canonical buffer-writer overload — it is the only one that lets options and logger be supplied together without also supplying XmlWriterSettings.

[RequiresUnreferencedCode("XmlSingleStreamLoader serializes TRecord via System.Xml.Serialization.XmlSerializer, which uses runtime reflection/Reflection.Emit the trimmer cannot follow. The library is not trim/NativeAOT safe.")]
public XmlSingleStreamLoader(IBufferWriter<byte> bufferWriter, XmlSingleStreamLoaderOptions? options, ILogger<XmlSingleStreamLoader<TRecord>>? logger = null)

Parameters

bufferWriter IBufferWriter<byte>: The buffer writer to write XML data to.
options XmlSingleStreamLoaderOptions: Options that control loader behaviour. When null, defaults are used.
logger ILogger<XmlSingleStreamLoader<TRecord>>: An optional logger instance for diagnostic output. When null, logging is disabled.

Exceptions

ArgumentNullException: Thrown when bufferWriter is null.

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

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

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

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

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

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

Initializes a new instance of the XmlSingleStreamLoader<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 XmlWriterSettings.

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

Parameters

stream Stream: The stream to write XML data to.
options XmlSingleStreamLoaderOptions: Options that control loader behaviour. When null, defaults are used.
logger ILogger<XmlSingleStreamLoader<TRecord>>: An optional logger instance for diagnostic output. When null, logging is disabled.

Examples

// Options and a logger, without having to supply XmlWriterSettings:
var loader = new XmlSingleStreamLoader<Person>
(
    stream,
    options: new XmlSingleStreamLoaderOptions { RootElementName = "People" },
    logger: loggerFactory.CreateLogger<XmlSingleStreamLoader<Person>>()
);

Exceptions

ArgumentNullException: Thrown when stream is null.
ArgumentException: Thrown when RootElementName is an empty or whitespace string, or is not a valid XML local name.

Properties

IsDryRun

Gets or sets a value indicating whether the loader runs in dry-run mode (#176). When true, the load enumerates the source, honours Wolfgang.Etl.Abstractions.LoaderBase<TDestination, TProgress>.SkipItemCount / Wolfgang.Etl.Abstractions.LoaderBase<TDestination, TProgress>.MaximumItemCount, advances the progress counters, and logs as usual, but writes nothing to the output stream. Defaults to false.

public bool IsDryRun { get; set; }

Property Value

bool

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