I was working on a payment system that processes mass payments, splitting a single payment request across multiple recipient accounts.

Everything worked fine in testing, but when we moved to production with real data volumes, our API started taking seconds to process a single payment request across a few thousand accounts.

In this post, I want to walk you through the steps to resolve this performance issue. I increased performance by 15x with 1 line of code in EF Core.

Let's dive in!

Let's explore the real-world payment system I have been working on.

It was a mass payment system that allowed customers to pay on multiple accounts at once. The payment amount is distributed across all eligible accounts.

Some payments were even spread to thousands of accounts.

Here is the create-payment endpoint:

csharp
1public record CreatePaymentRequest(
2    decimal Amount,
3    string GroupingProperty,
4    string? Currency,
5    string? CustomerId,
6    string? CustomerName,
7    string? PaymentMethod,
8    string? Description);
9
10public record CreatePaymentResponse(
11    string PaymentBatchReference,
12    decimal TotalAmount,
13    int PaymentsCreated,
14    decimal AmountDistributed,
15    decimal RemainingAmount,
16    List<PaymentInfo> Payments);
17
18public record PaymentInfo(
19    Guid PaymentId,
20    string PaymentReference,
21    decimal Amount,
22    string RecipientName,
23    string Status);
24
25public class CreatePaymentEndpoint : ICarterModule
26{
27    public void AddRoutes(IEndpointRouteBuilder app)
28    {
29        app.MapPost("/api/payments/create-payment", HandleCreatePaymentAsync)
30            .WithName("CreatePayment")
31            .WithTags("Payments")
32            .WithOpenApi();
33    }
34}

This endpoint accepts a CreatePaymentRequest that contains a GroupingProperty field. This field identifies which accounts should receive the payment.

The first step is to retrieve all eligible accounts from the database:

csharp
1private static async Task<List<PaymentAccount>> RetrievePaymentAccountsAsync(
2    PaymentsDbContext dbContext,
3    string groupingProperty,
4    CancellationToken cancellationToken)
5{
6    return await dbContext.PaymentAccounts
7        .Where(x => x.GroupingProperty == groupingProperty)
8        .Where(x => x.PaidAmount < x.AmountToPay)
9        .OrderBy(x => x.Id)
10        .ToListAsync(cancellationToken);
11}

We search the payment_accounts table for accounts that have not been fully paid yet.

The next step is to insert the payment records into the payments table:

csharp
1private static async Task<Results<Ok<CreatePaymentResponse>, BadRequest<string>>> HandleCreatePaymentAsync(
2    CreatePaymentRequest request,
3    PaymentsDbContext dbContext,
4    CancellationToken cancellationToken)
5{
6    var paymentAccounts = await RetrievePaymentAccountsAsync(
7        dbContext,
8        request.GroupingProperty,
9        cancellationToken);
10
11    if (paymentAccounts.Count == 0)
12    {
13        return TypedResults.BadRequest(
14            $"No payment accounts found for grouping property: {request.GroupingProperty}");
15    }
16
17    var batchReference = GeneratePaymentBatchReference();
18    
19    var distributionResult = CreatePaymentsForAccounts(
20        request,
21        paymentAccounts,
22        batchReference);
23
24    // Use standard SaveChangesAsync method
25    dbContext.Payments.AddRange(distributionResult.Payments);
26    await dbContext.SaveChangesAsync(cancellationToken);
27
28    var response = MapToResponse(request, distributionResult, batchReference);
29    return TypedResults.Ok(response);
30}

Here, we use the SaveChangesAsync method to insert the payments into the database.

I use SQL Server as the database provider:

csharp
1services.AddDbContext<PaymentsDbContext>((_, options) =>
2{
3    options.UseSqlServer(connectionString, dbOptions =>
4        {
5            dbOptions.MigrationsHistoryTable(
6                DatabaseConsts.MigrationHistoryTable, DatabaseConsts.Schema);
7        });
8
9    options.UseSnakeCaseNamingConvention();
10});

Let's run the application and test the request performance from Postman:

I tested the request with 19,000 accounts, and it took 8.22 seconds to process. Our p99 SLA was 1 second. The API was 8x slower than the SLA requirement.

The problem is with the SaveChangesAsync method.

In many databases, EF Core batches multiple inserts into a single command. But the database still executes these inserts one by one.

For SQL Server - EF Core uses a MERGE statement to insert multiple rows at once. This is a similar strategy that Entity Framework Extensions introduced back in 2014.

However, EF Core's approach is limited by the number of SQL parameters (2,100 per batch). Performance drops quickly when entities have many columns.

I spent a day optimizing the code, but could not meet the SLA requirements.

Here is where I found the Entity Framework Extensions library.

Entity Framework Extensions library offers simpler, more elegant and configurable options for bulk inserts that allow inserting thousands of records in a single database call.

To get started with Entity Framework Extensions, install the following NuGet package:

bash
1dotnet add package Z.EntityFramework.Extensions.EFCore

Entity Framework Extensions allows you to bulk insert thousands of entities with a single line of code with the BulkInsertAsync method:

csharp
1// @nuget: Z.EntityFramework.Extensions.EFCore
2using Z.EntityFramework.Extensions;
3
4var paymentAccounts = await RetrievePaymentAccountsAsync(dbContext, request.GroupingProperty, cancellationToken);
5if (paymentAccounts.Count == 0)
6{
7    return TypedResults.BadRequest($"No payment accounts found for grouping property: {request.GroupingProperty}");
8}
9
10var batchReference = GeneratePaymentBatchReference();
11
12var distributionResult = CreatePaymentsForAccounts(request, paymentAccounts, batchReference);
13
14// Bulk insert - one line of code with Entity Framework Extensions
15await dbContext.BulkInsertAsync(distributionResult.Payments, cancellationToken);
16
17var response = MapToResponse(request, distributionResult, batchReference);
18return TypedResults.Ok(response);

BulkInsert from Entity Framework Extensions lets you insert thousands of records in a single database call.

Both BulkInsert and BulkInsertAsync methods are available.

csharp
1// @nuget: Z.EntityFramework.Extensions.EFCore
2using Z.EntityFramework.Extensions;
3
4// Synchronous usage with Entity Framework Extensions
5dbContext.BulkInsert(payments);
6
7// Asynchronous usage with Entity Framework Extensions
8await dbContext.BulkInsertAsync(payments);

Entity Framework Extensions goes further by using SqlBulkCopy under the hood, which is much faster for large datasets in SQL Server. It's even faster than using a native MERGE statement, especially when entities have many columns.

IncludeGraph option in Entity Framework Extensions lets you bulk insert an entire object graph without manually saving each level:

csharp
1// @nuget: Z.EntityFramework.Extensions.EFCore
2using Z.EntityFramework.Extensions;
3
4var productCarts = GenerateProductCarts(10_000);
5
6// Bulk insert with IncludeGraph option - one line of code with Entity Framework Extensions
7await dbContext.BulkInsertAsync(productCarts, options => options.IncludeGraph = true);
8
9private static List<ProductCart> GenerateProductCarts(int count)
10{
11    var users = GenerateUsers(100);
12
13    var products = GenerateProducts(200);
14
15    return GenerateProductCarts(products, users, count);
16}

Let's run the application and test the request performance from Postman:

The request now takes 910 ms to process. That's finally under our SLA.

I continued to explore the Entity Framework Extensions library documentation and found the BulkInsertOptimized method.

If you don't need to return identity or other output values after insertion, you can use the BulkInsertOptimized method from Entity Framework Extensions.

Under the hood, Entity Framework Extensions uses a temporary table when outputting values. Instead, BulkInsertOptimized uses the BulkCopy strategy directly into the destination table.

In general, BulkInsertOptimized acts the same as the BulkInsert method with the AutoMapOutputDirection = false option.

But the main difference is that BulkInsertOptimized provides hints and recommendations for better performance. It returns the following object:

csharp
1// @nuget: Z.EntityFramework.Extensions.EFCore
2using Z.EntityFramework.Extensions;
3
4public class BulkOptimizedAnalysis 
5{
6    /// <summary>True if the bulk insert is optimized.</summary>
7    public bool IsOptimized { get; }
8
9    /// <summary>Gets a text containing all tips to optimize the bulk insert method.</summary>
10    public string TipsText { get; }
11    
12    /// <summary>Gets a list of tips to optimize the bulk insert method.</summary>
13    public List<string> Tips { get; }
14}

Let's use the BulkInsertOptimized method to optimize the CreatePayment endpoint:

csharp
1// @nuget: Z.EntityFramework.Extensions.EFCore
2using Z.EntityFramework.Extensions;
3
4var paymentAccounts = await RetrievePaymentAccountsAsync(dbContext, request.GroupingProperty, cancellationToken);
5if (paymentAccounts.Count == 0)
6{
7    return TypedResults.BadRequest($"No payment accounts found for grouping property: {request.GroupingProperty}");
8}
9
10var batchReference = GeneratePaymentBatchReference();
11
12var distributionResult = CreatePaymentsForAccounts(request, paymentAccounts, batchReference);
13
14// Bulk insert optimized - one line of code with Entity Framework Extensions
15await dbContext.BulkInsertOptimizedAsync(distributionResult.Payments, cancellationToken);
16
17var response = MapToResponse(request, distributionResult, batchReference);
18return TypedResults.Ok(response);

Let's run the application and test the request performance from Postman:

The request now takes 521 ms to process, which is almost 2x faster than the BulkInsert method from Entity Framework Extensions.

When comparing the SaveChanges and BulkInsertOptimized methods, we find that BulkInsertOptimized is 15x faster. And it took only 1 line of code to increase the performance!

In our Payment system, we faced another problem.

Each day at midnight, our service synchronizes payments with an external system to ensure that no payment requests are missed.

We need to update the ExternalStatus for the existing payments and insert new payments that were paid from another service.

Here is the sync-payments endpoint:

csharp
1public record SyncPaymentsRequest(
2    DateTime SyncDateTime,
3    List<SyncPaymentItem> Payments);
4
5public record SyncPaymentItem(
6    string AccountNumber,
7    PaymentStatus Status);
8
9public class SyncPaymentsEndpoint : ICarterModule
10{
11    public void AddRoutes(IEndpointRouteBuilder app)
12    {
13        app.MapPost("/api/payments/sync-payments", HandleSyncPaymentsAsync)
14            .WithName("SyncPayments")
15            .WithTags("Payments")
16            .WithOpenApi();
17    }
18
19    private static async Task<Results<Ok, BadRequest<string>>> HandleSyncPaymentsAsync(
20        SyncPaymentsRequest request,
21        PaymentsDbContext dbContext,
22        CancellationToken cancellationToken)
23    {
24        var existingPayments = await RetrievePaymentsByAccountNumbersAsync(dbContext,
25            request.SyncDateTime, request.Payments, cancellationToken);
26
27        var syncItems = PreparePaymentsForSync(existingPayments, request.Payments,
28            request.SyncDateTime);
29
30        await MergePaymentsAsync(syncItems, cancellationToken: cancellationToken);
31
32        return TypedResults.Ok();
33    }
34}

Here are the steps we need to take to sync the payments:

1. Retrieve all payments that were paid on the same day as the SyncDateTime
2. Update the ExternalStatus for the existing payments
3. Insert new payments that were paid from another service
4. Save all changes to the database

A typical MergePaymentsAsync implementation would look like this:

csharp
1private static async Task MergePaymentsAsync(
2    PaymentsDbContext dbContext,
3    List<Payment> paymentsToMerge,
4    CancellationToken cancellationToken)
5{
6    var paymentIds = paymentsToMerge.Select(p => p.Id).ToList();
7    
8    var existingPaymentIds = await dbContext.Payments
9        .Where(p => paymentIds.Contains(p.Id))
10        .Select(p => p.Id)
11        .ToHashSetAsync(cancellationToken);
12
13    var paymentsToUpdate = paymentsToMerge
14        .Where(p => existingPaymentIds.Contains(p.Id))
15        .ToList();
16
17    var paymentsToInsert = paymentsToMerge
18        .Where(p => !existingPaymentIds.Contains(p.Id))
19        .ToList();
20
21    foreach (var payment in paymentsToUpdate)
22    {
23        dbContext.Payments.Update(payment);
24    }
25
26    if (paymentsToInsert.Count > 0)
27    {
28        dbContext.Payments.AddRange(paymentsToInsert);
29    }
30
31    await dbContext.SaveChangesAsync(cancellationToken);
32}

Here are a few problems with this manual approach:

1. The MergePaymentsAsync method is very long and hard to read.
2. The paymentIds.Contains(p.Id) is slow when used with many ids, even with an index. You can also hit a database limit with the number of ids - the WHERE IN clause in SQL Server has a limit of a few thousand parameters
3. SaveChangesAsync is slow when used with thousands or tens of thousands of rows

The Entity Framework Extensions library solves all these problems with ease.

Entity Framework Extensions provides a WhereBulkContains method that allows you to filter a list of entities by a large list of values:

csharp
1// @nuget: Z.EntityFramework.Extensions.EFCore
2using Z.EntityFramework.Extensions;
3
4private static async Task<List<Payment>> RetrievePaymentsByAccountNumbersAsync(
5    PaymentsDbContext dbContext,
6    DateTime syncDateTime,
7    List<SyncPaymentItem> paymentItems,
8    CancellationToken cancellationToken)
9{
10    var startOfDay = syncDateTime.Date;
11    var endOfDay = startOfDay.AddDays(1).AddTicks(-1);
12
13    var accounts = paymentItems
14        .Select(x => new { RecipientAccountNumber = x.AccountNumber })
15        .ToList();
16
17    return await dbContext.Payments
18        .Where(x => x.LastSyncDate == null || (x.LastSyncDate >= startOfDay && x.LastSyncDate <= endOfDay))
19        .WhereBulkContains(accounts, x => x.RecipientAccountNumber)
20        .ToListAsync(cancellationToken);
21}

WhereBulkContains method is much faster than the Contains method. You do not need to worry about the number of ids you pass or hitting database parameter limits.

And the MergePaymentsAsync method can be simplified to just one line of code:

csharp
1// @nuget: Z.EntityFramework.Extensions.EFCore
2using Z.EntityFramework.Extensions;
3
4private static async Task<Results<Ok, BadRequest<string>>> HandleSyncPaymentsAsync(
5    SyncPaymentsRequest request,
6    PaymentsDbContext dbContext,
7    CancellationToken cancellationToken)
8{
9    var existingPayments = await RetrievePaymentsByAccountNumbersAsync(dbContext,
10        request.SyncDateTime, request.Payments, cancellationToken);
11
12    var syncItems = PreparePaymentsForSync(existingPayments, request.Payments, request.SyncDateTime);
13
14    // Perform a bulk merge - one line of code with Entity Framework Extensions
15    await dbContext.BulkMergeAsync(syncItems,
16        options => options.ColumnPrimaryKeyExpression = c => c.RecipientAccountNumber,
17        cancellationToken: cancellationToken);
18
19    return TypedResults.Ok();
20}

BulkMergeAsync from Entity Framework Extensions performs an upsert operation, inserting new records and updating existing ones. It is a much faster alternative to SaveChangesAsync.

Both sync BulkMerge and async BulkMergeAsync methods are available.

csharp
1// @nuget: Z.EntityFramework.Extensions.EFCore
2using Z.EntityFramework.Extensions;
3
4// Synchronous usage with Entity Framework Extensions
5dbContext.BulkMerge(payments);
6
7// Asynchronous usage with Entity Framework Extensions
8await dbContext.BulkMergeAsync(payments);

Let's run the application and test the sync request performance from Postman:

For 500 synced records, it took only 181 ms.

Here is why Entity Framework Extensions is a better fit than the manual merge approach:

• Fewer database round trips: one operation for upsert instead of multiple separate queries (inserts and updates).
• Stable performance with large batches: no IN clause limits, no 2,100-parameter trap that EF Core has
• Flexible when requirements change: you can change how the merge matches or updates with options, instead of rewriting the entire flow.

Here are examples of flexible options you can toggle later without refactoring the sync flow: Match by a different key or composite key if the business key changes:

csharp
1options => options.ColumnPrimaryKeyExpression = p => new { p.CustomerId, p.RecipientAccountNumber }

Building a high-performance real-world apps requires careful attention to how you handle bulk database operations.

Entity Framework Extensions transformed our production API from an 8-second bottleneck into a 500ms success story with minimal code changes.

The library's BulkInsert and BulkInsertOptimized methods delivered a 15x performance improvement by using bulk inserts with minimal database round trips.

This eliminated the performance issues caused by EF Core's default SaveChanges method when processing thousands of records.

The BulkMerge method further simplified our daily payment sync operations, replacing complex manual merge logic with a single line of code.

Entity Framework Extensions offers flexible configuration options that adapt easily to changing requirements. For production systems handling large datasets, Entity Framework Extensions provides a reliable, well-tested solution that scales with your needs.

The investment in this library pays off quickly through improved performance, reduced development time, and simplified maintenance.

If you often work with big data in .NET, give Entity Framework Extensions a try — it may become your go-to choice for bulk operations in EF Core.

Many thanks to ZZZ Projects for sponsoring this blog post.

Hope you find this newsletter useful. See you next time.