LLS.EFBulkExtensions 1.2.0

LLS.EFBulkExtensions

[English] | Português

High-performance extensions for EF Core 9 bulk operations: insert, update and delete with large volumes, batch processing, SQL Server and PostgreSQL support, type conversions, owned types, and optional returning of generated IDs.

Features

• Bulk insert, update and delete via DbContext extension methods
• Batch processing (BatchSize) and timeout control
• Support for SQL Server (SqlBulkCopy/MERGE) and PostgreSQL (binary COPY)
• Optional returning of generated IDs on inserts
• Handling properties with conversions (e.g., EnumToString) and owned types
• Optional internal transaction and extra configuration via model annotations

Compatibility and Dependencies

• .NET: net9.0
• EF Core 9.0 (Relational)
• Providers:
  • SQL Server: Microsoft.Data.SqlClient
  • PostgreSQL: Npgsql See project LLS.EFBulkExtensions.csproj.

Installation

• Local project: add a ProjectReference to src/LLS.EFBulkExtensions.
• NuGet (if published): reference the LLS.EFBulkExtensions package and ensure:
  • SQL Server: Microsoft.EntityFrameworkCore.SqlServer
  • PostgreSQL: Npgsql.EntityFrameworkCore.PostgreSQL

Quick Start

Import the extensions and call the methods from your DbContext:

using LLS.EFBulkExtensions.Extensions;
using LLS.EFBulkExtensions.Options;

SQL Server:

var options = new DbContextOptionsBuilder<AppDbContext>()
    .UseSqlServer("<your-connection-string>")
    .Options;

PostgreSQL:

var options = new DbContextOptionsBuilder<AppDbContext>()
    .UseNpgsql("<your-connection-string>")
    .Options;

Insert:

await context.BulkInsertAsync(entities, new BulkInsertOptions {
    ReturnGeneratedIds = false,
    BatchSize = 10_000,
    TimeoutSeconds = 120,
    PreserveIdentity = false,
    UseInternalTransaction = false,
    KeepNulls = false,
    UseAppLock = false
});

Update:

await context.BulkUpdateAsync(entitiesToUpdate, new BulkUpdateOptions {
    BatchSize = 10_000,
    TimeoutSeconds = 120,
    UseInternalTransaction = false
});

Delete:

await context.BulkDeleteAsync(entitiesToDelete, new BulkDeleteOptions {
    BatchSize = 10_000,
    TimeoutSeconds = 120,
    UseInternalTransaction = false
});

Options

• BulkInsertOptions: file
  • ReturnGeneratedIds, BatchSize, TimeoutSeconds, PreserveIdentity, UseInternalTransaction, KeepNulls, UseAppLock
• BulkUpdateOptions: file
  • BatchSize, TimeoutSeconds, UseInternalTransaction
• BulkDeleteOptions: file
  • BatchSize, TimeoutSeconds, UseInternalTransaction

You can also configure annotations directly on the model for insert:

builder.Property(p => p.Id).ValueGeneratedOnAdd(ReturnGeneratedIds: true, BatchSize: 10000);

Extension: SequenceModelExtensions.

Database Support

• SQL Server: SqlServerBulkInserter, SqlServerBulkUpdater, SqlServerBulkDeleter
• PostgreSQL: PostgresBulkInserter, PostgresBulkUpdater, PostgresBulkDeleter

How It Works

• Insert:
  • SQL Server: uses SqlBulkCopy for staging and MERGE with OUTPUT when needed to return IDs.
  • PostgreSQL: uses binary COPY; when requested, inserts into a temporary table and returns IDs via INSERT ... RETURNING.
• Update: creates a temporary table, bulk loads into temp and applies UPDATE with JOIN on PK, ignoring ValueGenerated columns.
• Delete: creates a temporary table and applies DELETE with JOIN on PK. Data construction: DataTableBuilder maps properties, types, conversions (includes EnumToString) and owned types.

Full Examples

• SQL Server: BulkInsertConsoleStyleTests.cs
• PostgreSQL: BulkInsertConsoleStyleTests.cs

Requirements

• EF Core 9 with correct entity mapping (table, schema, PK)
• To return IDs on inserts, use PK with ValueGeneratedOnAdd and optionally annotate ReturnGeneratedIds via model

APIs

• Inserts: BulkInsertAsync
• Updates: BulkUpdateAsync
• Deletes: BulkDeleteAsync

Notes

• BatchSize and Timeout configurable via options and annotations
• Optional internal transaction
• Support for PreserveIdentity and KeepNulls on insert