Net4x.DapperLibrary.Extensions.Archive 1.9.9.6

DapperLibrary.Extensions.Archive

Utilities to create archive tables and move old data to archive tables when saving DataTable/DataSet instances via IDapperContext.

Overview

• Purpose: provide a standard workflow for archiving table contents before replacing or truncating the original table. The archive helpers can create archive tables (if needed), enrich primary keys with additional columns (e.g. modified date), delete archived rows from the original table and persist archived rows to the archive table.
• Prefix-based: archive table names are produced by adding a configured prefix to the original table name.

Main types

• ArchiveSetting

  • Configuration model that contains:
    • PrefixToArchive and PrefixArchived � prefixes used to identify tables to archive and the archived target name.
    • IsArchiveEnabled � toggle archiving behaviour.
    • PrimaryKeysForTableType � strategy for determining primary keys for tables (IPrimaryKeysForTableType from DapperLibrary.Data).

• ITableArchiver

  • Interface describing archive operations that can be implemented to customize archiving behavior. Main methods:
    • ArchiveOldTableAsync(...) � move or save existing rows to the archive and remove them from the original table.
    • CreateArchiveTableIfNotExists(...) � ensure the archive table exists with the appropriate schema before archiving.

• TableArchiver (default implementation)

  • Implements ITableArchiver and provides the default archiving logic:
    • Loads the source table via IDapperContext.LoadDataTableFromNameAsync.
    • Creates the archive table if missing.
    • Enriches primary keys (adds any columnsToAdd as part of the composite primary key) so archived rows can include e.g. modification timestamps.
    • Deletes the archived rows from the original table in chunks and saves archived rows to the archive table.

Extension methods

• SaveDataTableExtension / SaveDataSetExtension

  • Provide SaveDataTable/SaveDataSet and async overloads that integrate archiving into the save flow.
  • Default overloads use the context's ConnectionStringToRead but connection-specific methods are available.
  • Parameters commonly used:
    • primaryKeySize � size to use when creating primary key columns on new tables.
    • chunkSize � number of rows to delete at once when removing archived rows from the original table.
    • columnsToAdd � extra columns that get added to the primary key of archived rows (for example ModifiedDate).
    • emptyTable � whether to empty/replace the original table before saving.
    • addDateSuffix � append a date suffix to the table name when saving (useful to avoid name collisions).
    • rowPreProcessor � optional IRowPreProcessor called before save to modify rows (e.g. generate UUIDs).
    • tableArchiver � custom ITableArchiver implementation (if null, default TableArchiver logic is used).

• CreateTableExtension / CreateOrEmptyOriginalAndSaveTableExtension

  • Helpers to create or recreate the target table and then save the data while optionally archiving the old contents.

Behavior notes

• Archiving is opt-in via the ArchiveSetting.IsArchiveEnabled flag; when disabled the archiver is a no-op.
• The archiving logic guards against double-archiving by skipping tables whose names already start with the configured PrefixToArchive or PrefixArchived.
• The default archiver sets archive table primary keys using the configured IPrimaryKeysForTableType and appends any specified columnsToAdd to the composite primary key.
• Deletions from the original table are performed in chunks to avoid locking large operations.

Example

var archiveSetting = new ArchiveSetting("ToArchive_", "Archived_", true, new MyPrimaryKeysForTableType());

// Save a single DataTable while archiving old rows:
var (affectedRows, sql) = await dapperContext.SaveDataTableAsync(
    dataTable,
    rowPreProcessor: null,
    primaryKeySize: 50,
    emptyTable: false,
    archiveSetting: archiveSetting,
    tableArchiver: null, // use default TableArchiver
    chunkSize: 1000,
    addDateSuffix: false
);

// Or save an entire DataSet and archive each table as needed:
var (totalAffected, sqlStatements) = await dapperContext.SaveDataSetAsync(
    dataSet,
    connectionStringName: "MyConnection",
    rowPreProcessor: null,
    primaryKeySize: 50,
    archiveSetting: archiveSetting,
    tableArchiver: null,
    emptyTable: false,
    chunkSize: 1000
);

Dependencies and compatibility

• Built on top of DapperLibrary.DbContexts and DapperLibrary.Data abstractions.
• This project contains code paths for older .NET Framework targets and modern .NET Standard/.NET runtimes; include compatible DapperLibrary assemblies for your target framework.

Extensibility

• Implement ITableArchiver for custom archiving strategies (e.g. copy to external storage, compress archived rows, or transmit them to a separate archival database).
• Provide a custom IPrimaryKeysForTableType implementation to control how primary keys are detected or assigned for different table types.

License / Contributing

See repository root for license and contribution guidelines.