Net4x.DapperLibrary.MergeUtility 1.9.9.6

DapperLibrary.MergeUtility

Utilities to merge in-memory data (primarily DataTable) into a relational database table via the DapperLibrary IDapperContext abstractions. The library provides a configurable merge engine that generates and executes insert/update/delete statements according to the provided source data and database metadata.

Overview

• Purpose: synchronize rows from an in-memory source (e.g. DataTable, DbDataReader or key/value pairs) into a target database table while handling inserts, updates and optional deletes of non-existing rows.
• The engine is designed to be provider-agnostic: it maps CLR types to database types, prepares parameters, formats SQL and executes batched operations using the host IDapperContext.

Main components

• IMergeHelper � simple public interface exposing Merge() and MergeDataTable(params string[]? primaryKeys).

• MergeHelper (extensions) � extension methods on IDapperContext that:

  • MergeDataTable(DataTable? dataTable, params string[] primaryKeys) � convenience wrapper to run a merge for a DataTable.
  • MergeDataTable(DataTable? dataTable, bool deleteNonExisting, params string[] primaryKeys) � same but optionally delete rows in the DB that are not present in the source.
  • Factory methods to create IMergeHelper instances from DataTable, DbDataReader or arrays of key/value pairs.

• MergeHelperInternal and supporting internals � the core implementation (split across files) that:

  • Computes table metadata (TableMetaData) and column mappings.
  • Builds parameterized SQL statements for INSERT, UPDATE and DELETE operations using SqlFormatter and RowHelperBase/RowInsertHelper/RowUpdateHelper/RowDeleteHelper.
  • Manages value extraction/wrapping for DataTable and DbDataReader sources via data wrappers.
  • Provides hooks for dumping generated SQL (DumperInternal) and for processing rows before save (ProcessRowBeforeSaveEventArgs).

• Mapping and helpers

  • Type mapping (DbTypeMapper, ToDbTypeHelper, DataBaseConstants) ensures parameters use appropriate DbType values for the provider.
  • ParameterReplacerHelper and ParameterReplaceExtension assist with named/positional parameter transformation when generating provider-specific SQL.
  • MergeHelperCreator is used to create the internal helper instances (internal factory/DI style).

Usage examples

Merge a DataTable into the database:

// 'context' is an IDapperContext instance
int affected = context.MergeDataTable(myDataTable, "Id");

// With delete of non-existing rows
int affected2 = context.MergeDataTable(myDataTable, true, "Id");

Create and use a merge helper directly:

var helper = context.CreateMergeHelper(myDataTable);
helper.Merge();

Create a helper from a DbDataReader or from in-memory key/value pairs:

var readerHelper = context.CreateMergeHelper(myDbDataReader, "MyTable");
var kvpHelper = context.CreateMergeHelper(keyValuePairsArray, "MyTable");

Behavior & customization

• The extension MergeDataTable sets the DataTable.PrimaryKey based on the provided primaryKeys and ensures the target table exists by calling CreateDataTableIfNotExists on the IDapperContext prior to merging.
• MergeHelperInternal exposes options and events (internal) to tweak behaviors such as SQL dumping, row pre-processing and delete handling.
• The engine tries to be efficient and safe by using parameterized statements and provider-aware DbType settings.

Dependencies and compatibility

• Depends on DapperLibrary.DbContexts for IDapperContext integration and database operations.
• Relies on internal mapping and helper classes in the DapperLibrary.MergeUtility project; no external database-specific code is required by callers.
• The project contains conditional compilation to support older .NET Framework targets and modern .NET runtimes. Use the build appropriate assemblies for your runtime.

Notes

• The merge implementation is intended for typical OLTP-sized datasets. For very large datasets consider batching or ETL-style approaches.
• SQL generation and parameter handling are provider-aware but edge-case SQL dialect differences may require inspection of the dumped statements (DumperInternal) when diagnosing issues.

License / Contributing

See repository root for license and contribution guidelines.