Class BulkInsertOptionsBuilder

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Fluent builder for BulkInsertOptions. Every setter validates immediately and returns the builder, so an invalid option fails at the call site rather than at execution.

public sealed class BulkInsertOptionsBuilder

Inheritance

object

BulkInsertOptionsBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

EntityBuilderExtensions.AsEntityBuilder<T>(object?)

Methods

Build()

Builds the immutable options.

public BulkInsertOptions Build()

Returns

BulkInsertOptions

The configured options.

CheckConstraints(bool)

Checks CHECK and FOREIGN KEY constraints during the write (SQL Server native path only).

public BulkInsertOptionsBuilder CheckConstraints(bool value = true)

Parameters

value bool

Whether constraints are checked; defaults to true.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

ClickHouse(ClickHouseBulkInsertOptions)

Supplies the ClickHouse native options group.

public BulkInsertOptionsBuilder ClickHouse(ClickHouseBulkInsertOptions options)

Parameters

options ClickHouseBulkInsertOptions

The ClickHouse options; must not be null.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentNullException

options is null.

Database(string)

Overrides the database part of the destination.

public BulkInsertOptionsBuilder Database(string database)

Parameters

database string

The database name; must not be empty.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentException

database is null or empty.

FireTriggers(bool)

Fires INSERT triggers for the written rows (SQL Server native path only).

public BulkInsertOptionsBuilder FireTriggers(bool value = true)

Parameters

value bool

Whether triggers fire; defaults to true.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

IgnoreDuplicates(bool)

Skips rows that violate a unique constraint. Honoured where either path can express it (the native provider load or the portable statement); a provider where neither can refuses the request by name instead of writing the rows as a plain insert, and an explicit Native refuses it rather than silently dropping the option.

public BulkInsertOptionsBuilder IgnoreDuplicates(bool value = true)

Parameters

value bool

Whether to skip conflicting rows; defaults to true.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

KeepIdentity(bool)

Writes explicit values to identity columns. The path stays capability based: Auto uses the native path where it can honour the option and the portable path otherwise, Native refuses the request by name instead of dropping the option, and Portable selects the portable path explicitly.

public BulkInsertOptionsBuilder KeepIdentity(bool value = true)

Parameters

value bool

Whether to write identity values; defaults to true.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

KeepNulls(bool)

Writes explicit null values instead of the destination DEFAULT (SQL Server native path only).

public BulkInsertOptionsBuilder KeepNulls(bool value = true)

Parameters

value bool

Whether nulls are kept; defaults to true.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

MaxBatchSize(int)

Limits the rows written per statement (the portable path chunks; the native path treats it as a batch hint or ignores it).

public BulkInsertOptionsBuilder MaxBatchSize(int rows)

Parameters

rows int

The maximum rows per statement; must be positive.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentOutOfRangeException

rows is not positive.

MaxParameters(int)

Limits the bound parameters per statement on the portable path.

public BulkInsertOptionsBuilder MaxParameters(int count)

Parameters

count int

The maximum parameters per statement; must be positive.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentOutOfRangeException

count is not positive.

MaxSqlLength(int)

Limits the approximate SQL text length per statement on the portable path.

public BulkInsertOptionsBuilder MaxSqlLength(int characters)

Parameters

characters int

The approximate maximum SQL length; must be positive.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentOutOfRangeException

characters is not positive.

Mode(BulkInsertMode)

Selects the execution path.

public BulkInsertOptionsBuilder Mode(BulkInsertMode mode)

Parameters

mode BulkInsertMode

The requested mode; must be a defined BulkInsertMode value.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentOutOfRangeException

mode is undefined.

NotifyAfter(int, Action<int, CancellationToken>)

Reports progress with the cumulative written-row count every rows rows.

public BulkInsertOptionsBuilder NotifyAfter(int rows, Action<int, CancellationToken> onRows)

Parameters

rows int

The reporting interval in rows; must be positive.

onRows Action<int, CancellationToken>

Called with the cumulative written-row count and the progress cancellation token.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentNullException

onRows is null.

ArgumentOutOfRangeException

rows is not positive.

ProgressCancellationTokenSource(CancellationTokenSource)

Supplies the token passed to the NotifyAfter(int, Action<int, CancellationToken>) callback, enabling cooperative time-limiting (source.CancelAfter(timeout)). The source is owned by the caller.

public BulkInsertOptionsBuilder ProgressCancellationTokenSource(CancellationTokenSource source)

Parameters

source CancellationTokenSource

The source whose token the callback observes.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentNullException

source is null.

Schema(string)

Overrides the schema part of the destination, keeping the mapped or explicit table.

public BulkInsertOptionsBuilder Schema(string schema)

Parameters

schema string

The schema name; must not be empty.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentException

schema is null or empty.

Server(string)

Overrides the server part of the destination where the provider/path supports server qualification.

public BulkInsertOptionsBuilder Server(string server)

Parameters

server string

The server name; must not be empty.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentException

server is null or empty.

SqlServer(SqlServerBulkInsertOptions)

Supplies the SQL Server native options group.

public BulkInsertOptionsBuilder SqlServer(SqlServerBulkInsertOptions options)

Parameters

options SqlServerBulkInsertOptions

The SQL Server options; must not be null.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentNullException

options is null.

Table(string)

Overrides the target table for this write. The naming convention is not applied to an explicit target; use the two-argument Table(string, string) overload to qualify it with a schema.

public BulkInsertOptionsBuilder Table(string table)

Parameters

table string

The destination table name; must not be empty.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentException

table is null or empty.

Table(string, string)

Overrides the target table for this write and qualifies it with a schema (or database).

public BulkInsertOptionsBuilder Table(string schema, string table)

Parameters

schema string

The schema (or database) name; must not be empty.

table string

The destination table name; must not be empty.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentException

schema or table is null or empty.

TableLock(bool)

Takes a table-level bulk-update lock for the duration of the write (SQL Server native path only).

public BulkInsertOptionsBuilder TableLock(bool value = true)

Parameters

value bool

Whether the table is locked; defaults to true.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

TargetKind(BulkInsertTargetKind)

Selects the kind of destination table.

public BulkInsertOptionsBuilder TargetKind(BulkInsertTargetKind kind)

Parameters

kind BulkInsertTargetKind

The requested target kind; must be a defined BulkInsertTargetKind value.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentOutOfRangeException

kind is undefined.

Timeout(TimeSpan)

Sets the whole-invocation timeout budget (all paths), measured from execution entry.

public BulkInsertOptionsBuilder Timeout(TimeSpan timeout)

Parameters

timeout TimeSpan

The budget; must be positive.

Returns

BulkInsertOptionsBuilder

This builder, for chaining.

Exceptions

ArgumentOutOfRangeException

timeout is zero or negative.