Class DbLoader<TRecord, TProgress>

Namespace: Wolfgang.Etl.DbClient

Assembly: Wolfgang.Etl.DbClient.dll

Loads records into a database via INSERT or UPDATE commands. Uses Dapper for parameter mapping from POCO properties.

public class DbLoader<TRecord, TProgress> : LoaderBase<TRecord, TProgress>, ILoadWithProgressAndCancellationAsync<TRecord, TProgress>, ILoadWithProgressAsync<TRecord, TProgress>, ILoadWithCancellationAsync<TRecord>, ILoadAsync<TRecord> where TRecord : notnull where TProgress : notnull

Type Parameters

TRecord: The POCO type representing a single row. Properties are mapped to command parameters by name or [Column("name")] attribute.
TProgress: The type of the progress object reported during loading. Use DbReport for the default implementation.

Inheritance: object

LoaderBase<TRecord, TProgress>

DbLoader<TRecord, TProgress>

Implements: ILoadWithProgressAndCancellationAsync<TRecord, TProgress>

ILoadWithProgressAsync<TRecord, TProgress>

ILoadWithCancellationAsync<TRecord>

ILoadAsync<TRecord>

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

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

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

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

LoaderBase<TRecord, TProgress>.CreateProgressTimer(IProgress<TProgress>)

LoaderBase<TRecord, TProgress>.LoadWorkerAsync(IAsyncEnumerable<TRecord>, CancellationToken)

LoaderBase<TRecord, TProgress>.CreateProgressReport()

LoaderBase<TRecord, TProgress>.IncrementCurrentItemCount()

LoaderBase<TRecord, TProgress>.IncrementCurrentSkippedItemCount()

LoaderBase<TRecord, TProgress>.ReportingInterval

LoaderBase<TRecord, TProgress>.CurrentItemCount

LoaderBase<TRecord, TProgress>.CurrentSkippedItemCount

LoaderBase<TRecord, TProgress>.MaximumItemCount

LoaderBase<TRecord, TProgress>.SkipItemCount

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Two transaction modes are supported:

Caller-managed — pass a DbTransaction to the constructor. The loader uses it but never commits or rolls back. The caller is responsible for transaction lifetime.
Auto-managed — pass null for the transaction parameter. The loader creates its own transaction, commits on success, and rolls back on exception.

The caller owns the DbConnection lifetime — the loader does not open, close, or dispose it. The connection must be open before calling LoadAsync.

Constructors

DbLoader(DbConnection, string, DbTransaction?, ILogger<DbLoader<TRecord, TProgress>>?)

Initializes a new DbLoader<TRecord, TProgress> with a custom SQL command.

public DbLoader(DbConnection connection, string commandText, DbTransaction? transaction = null, ILogger<DbLoader<TRecord, TProgress>>? logger = null)

Parameters

connection DbConnection: An open DbConnection. The caller owns its lifetime.
commandText string: The SQL INSERT or UPDATE command to execute per record.
transaction DbTransaction: An optional DbTransaction. If null, the loader creates and manages its own transaction (commit on success, rollback on failure).
logger ILogger<DbLoader<TRecord, TProgress>>: An optional logger for diagnostic output.

Exceptions

ArgumentNullException: connection or commandText is null.

DbLoader(DbConnection, WriteMode, DbTransaction?, ILogger<DbLoader<TRecord, TProgress>>?)

Initializes a new DbLoader<TRecord, TProgress> that auto-generates an INSERT statement from [Table] and [Column] attributes on TRecord.

public DbLoader(DbConnection connection, WriteMode writeMode, DbTransaction? transaction = null, ILogger<DbLoader<TRecord, TProgress>>? logger = null)

Parameters

connection DbConnection: An open DbConnection. The caller owns its lifetime.
writeMode WriteMode: Determines whether to generate INSERT or UPDATE commands.
transaction DbTransaction: An optional DbTransaction. If null, the loader creates and manages its own transaction.
logger ILogger<DbLoader<TRecord, TProgress>>: An optional logger for diagnostic output.

Exceptions

ArgumentNullException: connection is null.
InvalidOperationException: TRecord does not have a [Table] attribute, or writeMode is Update and no [Key] properties exist.

Properties

CommandText

The SQL command text being executed per record.

public string CommandText { get; }

Property Value

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 TProgress CreateProgressReport()

Returns

TProgress: Progress of type TProgress

CreateProgressTimer(IProgress<TProgress>)

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<TProgress> progress)

Parameters

progress IProgress<TProgress>: 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