Class DataMerge

Namespace

FluentCommand.Merge

Assembly

FluentCommand.SqlServer.dll

Provides a fluent API for configuring and executing SQL Server data merge operations, supporting insert, update, delete, and output of changes.

public class DataMerge : DisposableBase, IDisposable, IAsyncDisposable, IDataMerge

Inheritance

object

DisposableBase

DataMerge

Implements

IDisposable

IAsyncDisposable

IDataMerge

Inherited Members

DisposableBase.Dispose()

DisposableBase.Dispose(bool)

DisposableBase.AssertDisposed()

DisposableBase.DisposeManagedResources()

DisposableBase.DisposeUnmanagedResources()

DisposableBase.DisposeAsync()

DisposableBase.DisposeResourcesAsync()

DisposableBase.IsDisposed

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

DataMergeExtensions.CommandTimeout(IDataMerge, TimeSpan)

Constructors

DataMerge(IDataSession, DataMergeDefinition)

Initializes a new instance of the DataMerge class.

public DataMerge(IDataSession dataSession, DataMergeDefinition mergeDefinition)

Parameters

dataSession IDataSession

The data session used for the merge operation.

mergeDefinition DataMergeDefinition

The data merge definition containing mapping and configuration.

Methods

CommandTimeout(int)

Sets the wait time (in seconds) before terminating the attempt to execute the command and generating an error.

public IDataMerge CommandTimeout(int timeout)

Parameters

timeout int

The time in seconds to wait for the command to execute.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

Execute(DataTable)

Merges the specified tableData into the target table.

public int Execute(DataTable tableData)

Parameters

tableData DataTable

The DataTable containing the data to be merged.

Returns

int

The number of rows processed.

Exceptions

InvalidOperationException

Bulk-Copy is only supported by SQL Server. Ensure DataSession was created with a valid SqlConnection.

ValidationException

Thrown if the merge definition is invalid:

• TargetTable is required.
• At least one column is required.
• At least one column must be marked as a key.
• SourceColumn is required for column mapping.
• NativeType is required for column mapping.

ExecuteAsync(DataTable, CancellationToken)

Asynchronously merges the specified tableData into the target table.

public Task<int> ExecuteAsync(DataTable tableData, CancellationToken cancellationToken = default)

Parameters

tableData DataTable

The DataTable containing the data to be merged.

cancellationToken CancellationToken

A token to monitor for cancellation requests.

Returns

Task<int>

A task representing the asynchronous operation. The result contains the number of rows processed.

Exceptions

InvalidOperationException

Bulk-Copy is only supported by SQL Server. Ensure DataSession was created with a valid SqlConnection.

ValidationException

Thrown if the merge definition is invalid:

• TargetTable is required.
• At least one column is required.
• At least one column must be marked as a key.
• SourceColumn is required for column mapping.
• NativeType is required for column mapping.

ExecuteAsync<TEntity>(IEnumerable<TEntity>, CancellationToken)

Asynchronously merges the specified data into the target table.

public Task<int> ExecuteAsync<TEntity>(IEnumerable<TEntity> data, CancellationToken cancellationToken = default) where TEntity : class

Parameters

data IEnumerable<TEntity>

The data to be merged.

cancellationToken CancellationToken

A token to monitor for cancellation requests.

Returns

Task<int>

A task representing the asynchronous operation. The result contains the number of rows processed.

Type Parameters

TEntity

The type of the entity being merged.

ExecuteOutput(DataTable)

Merges the specified table into the target table and returns the output rows describing the changes.

public IEnumerable<DataMergeOutputRow> ExecuteOutput(DataTable table)

Parameters

table DataTable

The DataTable containing the data to be merged.

Returns

IEnumerable<DataMergeOutputRow>

A collection of DataMergeOutputRow instances describing the merge results.

Exceptions

InvalidOperationException

Bulk-Copy is only supported by SQL Server. Ensure DataSession was created with a valid SqlConnection.

ValidationException

Thrown if the merge definition is invalid:

• TargetTable is required.
• At least one column is required.
• At least one column must be marked as a key.
• SourceColumn is required for column mapping.
• NativeType is required for column mapping.

ExecuteOutputAsync(DataTable, CancellationToken)

Asynchronously merges the specified table into the target table and returns the output rows describing the changes.

public Task<IEnumerable<DataMergeOutputRow>> ExecuteOutputAsync(DataTable table, CancellationToken cancellationToken = default)

Parameters

table DataTable

The DataTable containing the data to be merged.

cancellationToken CancellationToken

A token to monitor for cancellation requests.

Returns

Task<IEnumerable<DataMergeOutputRow>>

A task representing the asynchronous operation. The result contains a collection of DataMergeOutputRow instances describing the merge results.

Exceptions

InvalidOperationException

Bulk-Copy is only supported by SQL Server. Ensure DataSession was created with a valid SqlConnection.

ValidationException

Thrown if the merge definition is invalid:

• TargetTable is required.
• At least one column is required.
• At least one column must be marked as a key.
• SourceColumn is required for column mapping.
• NativeType is required for column mapping.

ExecuteOutputAsync<TEntity>(IEnumerable<TEntity>, CancellationToken)

Asynchronously merges the specified data into the target table and returns the output rows describing the changes.

public Task<IEnumerable<DataMergeOutputRow>> ExecuteOutputAsync<TEntity>(IEnumerable<TEntity> data, CancellationToken cancellationToken = default) where TEntity : class

Parameters

data IEnumerable<TEntity>

The data to be merged.

cancellationToken CancellationToken

A token to monitor for cancellation requests.

Returns

Task<IEnumerable<DataMergeOutputRow>>

A task representing the asynchronous operation. The result contains a collection of DataMergeOutputRow instances describing the merge results.

Type Parameters

TEntity

The type of the entity being merged.

ExecuteOutput<TEntity>(IEnumerable<TEntity>)

Merges the specified data into the target table and returns the output rows describing the changes.

public IEnumerable<DataMergeOutputRow> ExecuteOutput<TEntity>(IEnumerable<TEntity> data) where TEntity : class

Parameters

data IEnumerable<TEntity>

The data to be merged.

Returns

IEnumerable<DataMergeOutputRow>

A collection of DataMergeOutputRow instances describing the merge results.

Type Parameters

TEntity

The type of the entity being merged.

Execute<TEntity>(IEnumerable<TEntity>)

Merges the specified data into the target table.

public int Execute<TEntity>(IEnumerable<TEntity> data) where TEntity : class

Parameters

data IEnumerable<TEntity>

The data to be merged.

Returns

int

The number of rows processed.

Type Parameters

TEntity

The type of the entity being merged.

IdentityInsert(bool)

Specifies whether to allow identity insert on the target table during the merge operation.

public IDataMerge IdentityInsert(bool value = true)

Parameters

value bool

true to allow identity insert on the target table; otherwise, false.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

IncludeDelete(bool)

Specifies whether to delete data from the target table that is not found in the source data during the merge operation.

public IDataMerge IncludeDelete(bool value = true)

Parameters

value bool

true to delete rows in the target table not present in the source data; otherwise, false.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

IncludeInsert(bool)

Specifies whether to insert data not found in the target table during the merge operation.

public IDataMerge IncludeInsert(bool value = true)

Parameters

value bool

true to insert data not found in the target table; otherwise, false.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

IncludeUpdate(bool)

Specifies whether to update data found in the target table during the merge operation.

public IDataMerge IncludeUpdate(bool value = true)

Parameters

value bool

true to update data found in the target table; otherwise, false.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

Map(Action<DataMergeMapping>)

Begins mapping the columns to merge using the provided fluent mapping builder.

public IDataMerge Map(Action<DataMergeMapping> builder)

Parameters

builder Action<DataMergeMapping>

A delegate to configure the data column mappings using a DataMergeMapping instance.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

Map<TEntity>(Action<DataMergeMapping<TEntity>>)

Begins mapping the columns to merge using a strongly typed fluent mapping builder.

public IDataMerge Map<TEntity>(Action<DataMergeMapping<TEntity>> builder) where TEntity : class

Parameters

builder Action<DataMergeMapping<TEntity>>

A delegate to configure the data column mappings using a DataMergeMapping<TEntity> instance.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

Type Parameters

TEntity

The type of the entity being merged.

Mode(DataMergeMode)

Sets the mode for how the merge will be processed.

public IDataMerge Mode(DataMergeMode mergeMode)

Parameters

mergeMode DataMergeMode

The merge mode to use. See DataMergeMode for options.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

TargetTable(string)

Sets the name of the target table to merge data into.

public IDataMerge TargetTable(string value)

Parameters

value string

The name of the target table.

Returns

IDataMerge

The same IDataMerge instance for fluent chaining.

Validate(DataMergeDefinition, bool)

Validates the specified merge definition for correctness and required configuration.

public static bool Validate(DataMergeDefinition mergeDefinition, bool isBulk)

Parameters

mergeDefinition DataMergeDefinition

The merge definition to validate.

isBulk bool

true if the merge mode is bulk copy; otherwise, false.

Returns

bool

true if the definition is valid; otherwise, an exception is thrown.

Exceptions

ValidationException

Thrown if required properties are missing or invalid in the merge definition.