Class SqlBulkCopyLoaderOptions<TRecord>

Namespace

Wolfgang.Etl.SqlBulkCopy

Assembly

Wolfgang.Etl.SqlBulkCopy.dll

Options for the SqlBulkCopyLoader<TRecord> constructor.

public sealed record SqlBulkCopyLoaderOptions<TRecord> : LoaderOptions, IEquatable<LoaderOptions>, IEquatable<SqlBulkCopyLoaderOptions<TRecord>> where TRecord : notnull

Type Parameters

TRecord

The record type the loader writes.

Inheritance

object

LoaderOptions

SqlBulkCopyLoaderOptions<TRecord>

Implements

IEquatable<LoaderOptions>

IEquatable<SqlBulkCopyLoaderOptions<TRecord>>

Inherited Members

LoaderOptions.ToString()

LoaderOptions.GetHashCode()

LoaderOptions.Equals(object)

LoaderOptions.Equals(LoaderOptions)

LoaderOptions.<Clone>$()

LoaderOptions.ReportingInterval

LoaderOptions.MaximumItemCount

LoaderOptions.SkipItemCount

LoaderOptions.ErrorPolicy

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

Supplied as the second constructor parameter, ahead of the optional transaction and logger. When the whole options object is null, or an individual property is left unset, the documented defaults below apply — defaults live on the property initializers here rather than in constructor bodies, so no constructor can accidentally diverge from them.

Derives from Wolfgang.Etl.Abstractions.LoaderOptions, so the settings every loader shares — Wolfgang.Etl.Abstractions.LoaderOptions.ReportingInterval, Wolfgang.Etl.Abstractions.LoaderOptions.SkipItemCount, Wolfgang.Etl.Abstractions.LoaderOptions.MaximumItemCount and Wolfgang.Etl.Abstractions.LoaderOptions.ErrorPolicy — are configured here as well (ADR-0009 in Wolfgang.Etl.Abstractions).

The record is generic because the validation callbacks are typed on the record being loaded. Each member except BulkCopyOptions mirrors the loader property of the same name; the constructor applies them in declaration order, so the loader's own range checks (for example BatchSize below 1) fire at construction. BulkCopyOptions has no loader property: it configures the underlying SqlBulkCopy and was previously the constructor's own SqlBulkCopyOptions parameter.

Properties

BatchSize

Gets the number of rows in each batch sent to the server.

public int BatchSize { get; init; }

Property Value

int

The default is 10,000.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 1.

BulkCopyOptions

Gets the SqlBulkCopyOptions flags applied to every bulk copy the loader performs. Defaults to Default.

public SqlBulkCopyOptions BulkCopyOptions { get; init; }

Property Value

SqlBulkCopyOptions

Remarks

Bulk-copy configuration such as TableLock or KeepIdentity belongs here; the transaction the copy runs in is not configuration and stays a constructor parameter.

BulkCopyTimeout

Gets the timeout in seconds for each bulk copy operation. A value of 0 means no timeout.

public int BulkCopyTimeout { get; init; }

Property Value

int

The default is 30 seconds.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is negative.

DestinationSchemaName

Gets an optional destination schema name override. When null, the schema is derived from the [Table] attribute.

public string? DestinationSchemaName { get; init; }

Property Value

string

DestinationTableName

Gets an optional destination table name override. When null, the table name is derived from the [Table] attribute or the type name.

public string? DestinationTableName { get; init; }

Property Value

string

EnableDataValidation

Gets a value indicating whether to validate each item using System.ComponentModel.DataAnnotations attributes before loading.

public bool EnableDataValidation { get; init; }

Property Value

bool

The default is false.

Remarks

Enabling validation adds per-item overhead. Validation is applied recursively to root TRecord instances and to every level of nested-collection children. How a failure is handled is controlled by ValidationFailureBehavior — the default is to throw a SqlBulkCopyValidationException, which fails loudly and stops the load. Set ValidationFailureBehavior to Skip to tolerate dirty data and drop only the failing items.

IsDryRun

Gets a value indicating whether the load runs as a dry run — validating the pipeline against real data without writing to SQL Server.

public bool IsDryRun { get; init; }

Property Value

bool

The default is false.

Remarks

When true, the loader still enumerates the source, applies SkipItemCount / MaximumItemCount, runs data validation, increments the progress counters, and logs as usual — but performs no SQL side effects: the PreAction / PostAction (e.g. truncate / delete) and the bulk insert are all skipped. This lets a caller confirm a pipeline runs end-to-end and surfaces mapping / validation errors without touching the destination.

OnNestedValidationFailed

Gets an optional callback invoked when a nested-collection child instance fails validation.

public Action<object, ICollection<ValidationResult>>? OnNestedValidationFailed { get; init; }

Property Value

Action<object, ICollection<ValidationResult>>

Remarks

Only invoked when EnableDataValidation is true. The callback runs before the configured ValidationFailureBehavior takes effect. The child is passed as object because the child type is resolved at load time, not at TRecord definition. For root-item validation, see OnValidationFailed.

OnValidationFailed

Gets an optional callback invoked when a root TRecord fails validation.

public Action<TRecord, ICollection<ValidationResult>>? OnValidationFailed { get; init; }

Property Value

Action<TRecord, ICollection<ValidationResult>>

Remarks

Only invoked when EnableDataValidation is true. The callback runs before the configured ValidationFailureBehavior takes effect, so consumers can log / inspect the failing item from a single hook regardless of whether the loader then throws or skips. The callback receives the failing root item and the collection of validation errors. For nested-collection children, see OnNestedValidationFailed.

PostAction

Gets the action to execute after loading completes.

public PostAction PostAction { get; init; }

Property Value

PostAction

The default is None.

PostLoadCustomAction

Gets the custom delegate to invoke when PostAction is CustomAction.

public Func<PostLoadActionParameters, Task>? PostLoadCustomAction { get; init; }

Property Value

Func<PostLoadActionParameters, Task>

PreAction

Gets the action to execute before loading begins.

public PreAction PreAction { get; init; }

Property Value

PreAction

The default is None.

PreLoadCustomAction

Gets the custom delegate to invoke when PreAction is CustomAction.

public Func<PreLoadActionParameters, Task>? PreLoadCustomAction { get; init; }

Property Value

Func<PreLoadActionParameters, Task>

ValidationFailureBehavior

Gets how the loader reacts to a validation failure when EnableDataValidation is true.

public ValidationFailureBehavior ValidationFailureBehavior { get; init; }

Property Value

ValidationFailureBehavior

The default is Throw.

Remarks

See ValidationFailureBehavior for the semantics of each option. The same setting applies to both root TRecord instances and nested-collection children.