Introducción

Si trabajas con .NET y EF Core en aplicaciones corporativas, ya te has encontrado con escenarios en los que necesitas grabar, actualizar o eliminar miles de registros de una sola vez. EF Core estándar ejecuta una operación SQL por cada entidad en el ChangeTracker: para 10.000 registros, eso son 10.000 roundtrips a la base de datos. En aplicaciones medianas y grandes, eso es inaceptable.

La biblioteca EFCore.BulkExtensions resuelve este problema de forma elegante, usando operaciones nativas de cada base de datos (como MERGE en SQL Server o INSERT ... ON CONFLICT en PostgreSQL) para procesar miles de registros en una única operación.

En este artículo, vas a conocer:

  • Quién mantiene el proyecto y su relación con el ecosistema .NET
  • El error clásico de tracking que el 90% de los desarrolladores comete (y atribuye a EF Core)
  • Por qué EF Core se comporta así — y por qué es correcto
  • Los 8 métodos de la biblioteca con ejemplos reales
  • Integración con Azure Service Bus para procesamiento de alto volumen

Requisitos previos: Familiaridad con C# y EF Core. Se recomienda haber leído los artículos sobre Fluent API e mapeamento com EF Core y Cuello de Botella en Bases de Datos: Mensajería y Paginación antes de continuar.

📦 Código fuente: La implementación completa de este artículo está en el repositorio blog-zocateli-sample en GitHub. Clónalo, explóralo y adáptalo a tu contexto.


El Proyecto EFCore.BulkExtensions

Historia y Mantenimiento

EFCore.BulkExtensions es mantenido por Boris Djurdjevic (@borisdj), un ingeniero de software sénior de Serbia especializado en acceso a datos y rendimiento de bases de datos. El proyecto se creó en 2017 y rápidamente se convirtió en la biblioteca de operaciones bulk más popular del ecosistema .NET.

Cifras del proyecto (marzo de 2026):

MétricaValor
⭐ Stars en GitHub3.700+
📦 Descargas en NuGet30 millones+
🧑‍💻 Contribuidores70+
📋 Issues resueltos900+
🔄 Releases100+
📄 LicenciaMIT

Relación con el Equipo de EF Core y la .NET Foundation

Es importante aclararlo: Boris Djurdjevic no es miembro del equipo de Entity Framework Core de Microsoft, ni EFCore.BulkExtensions es un proyecto oficial de la .NET Foundation. Se trata de un proyecto independiente de la comunidad open-source, con licencia MIT.

Aun así, el proyecto mantiene una compatibilidad rigurosa con cada versión de EF Core (3.x, 5.x, 6.x, 7.x, 8.x) y es ampliamente reconocido por la propia Microsoft en discusiones sobre rendimiento. Varios contribuidores del repositorio tienen experiencia profesional con SQL Server, PostgreSQL y Oracle, lo que explica la calidad de su soporte multi-provider.

Proveedores de Base de Datos Soportados

ProviderEstrategia Bulk
SQL ServerSqlBulkCopy + MERGE (mejor rendimiento)
PostgreSQLCOPY + INSERT ... ON CONFLICT
MySQLLOAD DATA + INSERT ... ON DUPLICATE KEY
SQLiteINSERT OR REPLACE
OracleMediante un provider adaptado

La biblioteca detecta automáticamente el provider configurado en el DbContext y usa la estrategia nativa más eficiente.


El Error Clásico: Delete → ReInsert y el ChangeTracker

Diagrama del error clásico del ChangeTracker: Delete → ReInsert causa InvalidOperationException, solución con ChangeTracker.Clear() o BulkInsertOrUpdate

El Escenario

Un escenario extremadamente común en aplicaciones corporativas: necesitas sincronizar datos de una fuente externa (CSV, API, otro sistema). El enfoque “intuitivo” de muchos desarrolladores es:

  1. Buscar todos los registros existentes
  2. Eliminarlos todos
  3. Insertar los nuevos
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// ❌ INCORRECTO — El clásico "borra todo e inserta de nuevo"
public async Task SincronizarRegistrosAsync(
    List<RegistroApp> registrosNovos,
    CancellationToken ct)
{
    // 1. Busca los existentes (el ChangeTracker empieza a rastrear)
    var existentes = await context.RegistrosApps.ToListAsync(ct);

    // 2. Elimina todos
    context.RegistrosApps.RemoveRange(existentes);
    await context.SaveChangesAsync(ct);

    // 3. Inserta los nuevos — 💥 BOOM!
    await context.RegistrosApps.AddRangeAsync(registrosNovos, ct);
    await context.SaveChangesAsync(ct); // InvalidOperationException!
}

El Error

1
2
3
4
5
System.InvalidOperationException:
The instance of entity type 'RegistroApp' cannot be tracked because
another instance with the same key value for {'Id'} is already being tracked.
When attaching existing entities, ensure that only one entity instance
with a given key value is attached.

Por Qué Ocurre

El ChangeTracker de EF Core es un mapa de identidad en memoria. Cuando haces ToListAsync(), todas las entidades devueltas se rastrean con el estado Unchanged. Al llamar a RemoveRange(), el estado cambia a Deleted. Cuando se ejecuta SaveChangesAsync, las entidades se eliminan de la base de datos, pero el ChangeTracker todavía mantiene referencias a esas entidades con el mismo Id.

Si algún registro nuevo tiene el mismo Id que un registro que acaba de eliminarse, EF Core detecta la colisión y lanza la excepción. Aunque el registro ya se haya borrado de la base de datos, la identidad en memoria todavía existe en el contexto.

La Solución con EF Core Puro

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// ✅ CORRECTO — Limpia el ChangeTracker entre las operaciones
public async Task SincronizarRegistrosAsync(
    List<RegistroApp> registrosNovos,
    CancellationToken ct)
{
    // 1. Elimina los existentes
    var existentes = await context.RegistrosApps.ToListAsync(ct);
    context.RegistrosApps.RemoveRange(existentes);
    await context.SaveChangesAsync(ct);

    // 2. Limpia el mapa de identidad — ESENCIAL
    context.ChangeTracker.Clear();

    // 3. Ahora puede insertar sin conflicto
    await context.RegistrosApps.AddRangeAsync(registrosNovos, ct);
    await context.SaveChangesAsync(ct);
}

ChangeTracker.Clear() descarta todas las referencias rastreadas, lo que permite agregar nuevas entidades con los mismos Ids sin conflicto.


EF Core No Fue Diseñado Para Esto

Antes de culpar a EF Core, entiende quién está detrás de la herramienta. El equipo que mantiene Entity Framework Core no está compuesto solo por desarrolladores: son ingenieros de datos, arquitectos de bases de datos y especialistas con experiencia directa en proveedores como Oracle, SQL Server y PostgreSQL. Nombres como Arthur Vickers, Shay Rojansky (mantenedor de Npgsql) y Brice Lambson contribuyeron directamente a EF Core con décadas de experiencia en motores de bases de datos.

Si EF Core se comporta de determinada forma por defecto — como mantener el tracking activo e impedir que dos instancias con el mismo Id coexistan en el mismo contexto — no es un bug. Es una decisión arquitectónica fundamentada en principios de integridad de datos y concurrencia optimista.

El Propósito de EF Core

EF Core se diseñó para ser un ORM transaccional enfocado en:

  • Unit of Work: agrupa cambios relacionados en una transacción atómica
  • Identity Map: garantiza que cada registro de la base de datos tenga como máximo una representación en memoria
  • Concurrencia optimista: detecta conflictos entre operaciones concurrentes
  • OLTP (procesamiento transaccional): inserta, actualiza y elimina registros individuales o en lotes pequeños con seguridad transaccional

El comportamiento por defecto de EF Core es rastrear entidades porque la mayoría de los escenarios (APIs REST, CRUD, e-commerce) opera sobre decenas de registros por solicitud, no miles.

El Enfoque Correcto Para la Sincronización Masiva

Cuando el escenario exige procesar miles de registros — sincronización de inventario, importación de CSV, ingesta de datos desde colas — estás fuera del alcance de EF Core estándar. Aquí es donde entra EFCore.BulkExtensions.

En lugar de Delete + ReInsert, el enfoque correcto es un UPSERT (INSERT or UPDATE):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// ✅ CORRECTO — UPSERT masivo con BulkExtensions
public async Task SincronizarRegistrosAsync(
    List<RegistroApp> registrosAtuais,
    CancellationToken ct)
{
    var bulkConfig = new BulkConfig
    {
        UpdateByProperties = [
            nameof(RegistroApp.NomeProjeto),
            nameof(RegistroApp.Repositorio)
        ],
        PropertiesToExcludeOnUpdate = [
            nameof(RegistroApp.Id),
            nameof(RegistroApp.CriadoEm)
        ],
        TrackingEntities = false,
        BatchSize = 1000
    };

    // Una única operación: inserta nuevos, actualiza existentes
    await context.BulkInsertOrUpdateAsync(registrosAtuais, bulkConfig, cancellationToken: ct);
}

Este enfoque:

  • No necesita buscar primero los registros existentes
  • No accede al ChangeTracker
  • Ejecuta un MERGE nativo en SQL Server (o INSERT ... ON CONFLICT en PostgreSQL)
  • Procesa 10.000 registros en ~2 segundos (vs. ~100 segundos con EF Core puro)

Si necesitas algo más que el UPSERT — eliminar registros que ya no existen en la fuente — usa BulkInsertOrUpdateOrDeleteAsync (sección 5 más abajo).


Instalación y Configuración

Instalación vía NuGet

1
dotnet add package EFCore.BulkExtensions

La biblioteca detecta automáticamente el provider de EF Core configurado. Para SQL Server, no se necesita ninguna configuración adicional. Para PostgreSQL, asegúrate de que Npgsql esté instalado.

1
2
3
<!-- .csproj — Paquetes necesarios -->
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.13" />
<PackageReference Include="EFCore.BulkExtensions" Version="8.1.3" />

Compatibilidad

EF CoreBulkExtensions.NET
8.x8.x.NET 8+
7.x7.x.NET 7+
6.x6.x.NET 6+

Consejo: Usa siempre la misma major version de EFCore.BulkExtensions que tu EF Core. Ejemplo: EF Core 8.0.13 → BulkExtensions 8.1.3.

Namespace

1
using EFCore.BulkExtensions;

Todos los métodos son extension methods de DbContext: no es necesario heredar de ninguna clase especial.


Todos los Métodos con Ejemplos Reales

Comparación de rendimiento: EF Core estándar (100s con 10.000 INSERTs individuales) vs BulkExtensions (2s con BatchSize=1000)

A continuación, los 8 métodos principales de la biblioteca con ejemplos reales usando las entidades RegistroApp, ClienteApp y ConfiguracaoSegura del repositorio blog-zocateli-sample.

1. BulkInsertAsync — INSERT Masivo

Inserta miles de registros usando SqlBulkCopy (SQL Server) o COPY (PostgreSQL). Cero interacción con el ChangeTracker.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
public async Task<int> InserirEmMassaAsync(
    List<RegistroApp> registros,
    CancellationToken ct = default)
{
    if (registros.Count == 0)
        return 0;

    var bulkConfig = new BulkConfig
    {
        BatchSize = 1000,
        SetOutputIdentity = true,   // Devuelve los IDs generados por la base de datos
        PreserveInsertOrder = true  // Mantiene el orden de la lista original
    };

    await dbContext.BulkInsertAsync(registros, bulkConfig, cancellationToken: ct);
    return registros.Count;
}

Cuándo usarlo: Carga inicial de datos, importación de CSV, datos obtenidos de una base de datos diferente, ingesta de eventos.


2. BulkUpdateAsync — UPDATE Masivo

Actualiza registros existentes por clave primaria. Puedes elegir qué propiedades actualizar.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public async Task<int> AtualizarEmMassaAsync(
    List<RegistroApp> registros,
    CancellationToken ct = default)
{
    if (registros.Count == 0)
        return 0;

    var bulkConfig = new BulkConfig
    {
        BatchSize = 1000,
        PropertiesToIncludeOnUpdate =
        [
            nameof(RegistroApp.Linguagem),
            nameof(RegistroApp.VersaoFramework),
            nameof(RegistroApp.Legado),
            nameof(RegistroApp.Desativado),
            nameof(RegistroApp.AtualizadoEm)
        ],
        TrackingEntities = false
    };

    await dbContext.BulkUpdateAsync(registros, bulkConfig, cancellationToken: ct);
    return registros.Count;
}

Cuándo usarlo: Actualizar estados en lote, flags de procesamiento, campos calculados.


3. BulkDeleteAsync — DELETE Masivo

Elimina registros por clave primaria sin cargar antes las entidades.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
public async Task<int> RemoverEmMassaAsync(
    List<RegistroApp> registros,
    CancellationToken ct = default)
{
    if (registros.Count == 0)
        return 0;

    await dbContext.BulkDeleteAsync(registros, cancellationToken: ct);
    return registros.Count;
}

Cuándo usarlo: Eliminación periódica de datos expirados, limpieza de registros huérfanos, purga de datos antiguos.


4. BulkInsertOrUpdateAsync — UPSERT (MERGE)

El método más potente de la biblioteca. Ejecuta un MERGE en SQL Server: inserta registros nuevos y actualiza los existentes en una única operación.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
public async Task<int> InserirOuAtualizarAsync(
    List<RegistroApp> registros,
    IReadOnlyCollection<string> propriedadesExcluirNoUpdate,
    CancellationToken ct = default)
{
    if (registros.Count == 0)
        return 0;

    var bulkConfig = new BulkConfig
    {
        SetOutputIdentity = true,
        PreserveInsertOrder = true,
        UpdateByProperties =
        [
            nameof(RegistroApp.NomeProjeto),
            nameof(RegistroApp.Repositorio)
        ],
        PropertiesToExcludeOnUpdate = [.. propriedadesExcluirNoUpdate],
        SqlBulkCopyOptions = EFCore.BulkExtensions.SqlBulkCopyOptions.Default,
        TrackingEntities = false,
        BatchSize = 1000
    };

    await dbContext.BulkInsertOrUpdateAsync(registros, bulkConfig, cancellationToken: ct);
    return registros.Count;
}

Cuándo usarlo: Sincronización con una fuente externa (API, CSV, Azure DevOps, datos de otra base de datos), ingesta de mensajes desde colas.


5. BulkInsertOrUpdateOrDeleteAsync — Sincronización Completa

Hace todo lo que hace el UPSERT, pero también elimina los registros que existen en la base de datos y no existen en la lista proporcionada. Es la sincronización delta completa.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
public async Task<int> SincronizarAsync(
    List<RegistroApp> registrosAtuais,
    CancellationToken ct = default)
{
    if (registrosAtuais.Count == 0)
        return 0;

    var bulkConfig = new BulkConfig
    {
        SetOutputIdentity = true,
        UpdateByProperties =
        [
            nameof(RegistroApp.NomeProjeto),
            nameof(RegistroApp.Repositorio)
        ],
        PropertiesToExcludeOnUpdate =
        [
            nameof(RegistroApp.Id),
            nameof(RegistroApp.CriadoEm)
        ],
        TrackingEntities = false,
        BatchSize = 1000
    };

    await dbContext.BulkInsertOrUpdateOrDeleteAsync(
        registrosAtuais, bulkConfig, cancellationToken: ct);

    return registrosAtuais.Count;
}

Cuándo usarlo: Sync total con un sistema maestro, espejado de catálogos, mirror de repositorios de Azure DevOps.

⚠️ Cuidado: Este método elimina de la base de datos todo lo que no esté en la lista. Úsalo con sabiduría y siempre en un contexto transaccional.


6. BulkSaveChangesAsync — Sustituto de SaveChangesAsync

Si ya usas el patrón Add/Update/Remove con el ChangeTracker, puedes simplemente cambiar SaveChangesAsync() por BulkSaveChangesAsync() para ganar rendimiento sin cambiar la lógica.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
public async Task SalvarAlteracoesBulkAsync(CancellationToken ct = default)
{
    var bulkConfig = new BulkConfig
    {
        BatchSize = 500,
        TrackingEntities = false
    };

    // Analiza el ChangeTracker y aplica operaciones bulk
    // para Add, Update y Delete automáticamente
    await dbContext.BulkSaveChangesAsync(bulkConfig, cancellationToken: ct);
}

Cuándo usarlo: Migración gradual de código existente: cambia SaveChangesAsync por BulkSaveChangesAsync sin refactorizar.


7. BulkReadAsync — Lectura en Lote por Clave

Carga registros de forma masiva por clave primaria o clave compuesta. Evita consultas N+1 cuando necesitas buscar entidades antes de un update en lote.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
public async Task<List<RegistroApp>> LerEmMassaAsync(
    List<RegistroApp> registrosComChave,
    CancellationToken ct = default)
{
    if (registrosComChave.Count == 0)
        return [];

    var bulkConfig = new BulkConfig
    {
        UpdateByProperties =
        [
            nameof(RegistroApp.NomeProjeto),
            nameof(RegistroApp.Repositorio)
        ],
        TrackingEntities = false
    };

    // Rellena los registros con los datos de la base de datos
    // usando las propiedades definidas como clave de búsqueda
    await dbContext.BulkReadAsync(registrosComChave, bulkConfig, cancellationToken: ct);
    return registrosComChave;
}

Cuándo usarlo: Precargar entidades para compararlas antes de un update selectivo, validar existencia en lote.


8. TruncateAsync — TRUNCATE TABLE

Ejecuta un TRUNCATE TABLE nativo. A diferencia del DELETE sin WHERE, el truncate:

  • No genera log de transacción por registro (minimal logging)
  • Restablece identity/sequence a su valor inicial
  • Es significativamente más rápido que delete en tablas grandes
1
2
3
4
public async Task TruncarTabelaAsync(CancellationToken ct = default)
{
    await dbContext.TruncateAsync<RegistroApp>(ct);
}

Cuándo usarlo: Limpieza de tablas de staging, reinicio de datos de prueba, recarga completa de una caché almacenada en la base de datos.

⚠️ Cuidado: TRUNCATE no se puede filtrar y no dispara triggers. Úsalo solo en tablas que puedan vaciarse por completo.


BulkConfig: El Corazón de la Biblioteca

BulkConfig es la clase de configuración que controla el comportamiento de todas las operaciones bulk. Estas son las propiedades más importantes:

PropiedadTipoDescripción
BatchSizeintRegistros por lote SQL. Por defecto: 2000. Recomendado: 500-2000.
SetOutputIdentityboolDevuelve los IDs generados por la base de datos (identity/sequence) en los objetos de la lista.
PreserveInsertOrderboolGarantiza que se respete el orden de la lista original en el INSERT.
UpdateByPropertiesList<string>Propiedades usadas como clave para el Match en el MERGE/UPSERT.
PropertiesToIncludeOnUpdateList<string>Whitelist: solo estas propiedades se actualizarán.
PropertiesToExcludeOnUpdateList<string>Blacklist: estas propiedades no se actualizarán.
TrackingEntitiesboolSi es false, no actualiza el ChangeTracker después de la operación. Usa siempre false por rendimiento.
UseTempDBboolSQL Server: usa tempdb para el staging. Útil cuando hay restricciones de permisos.
SqlBulkCopyOptionsSqlBulkCopyOptionsOpciones nativas de SqlBulkCopy (ej.: KeepIdentity, CheckConstraints).

Ejemplo de BulkConfig Completo (Escenario Real)

Este es el patrón usado en producción para sincronizar registros de inventario de aplicaciones, basado en un proyecto real de gestión de inventario corporativo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
var bulkConfig = new BulkConfig
{
    // Rendimiento
    BatchSize = 1000,
    TrackingEntities = false,

    // Identidad y orden
    SetOutputIdentity = true,
    PreserveInsertOrder = true,

    // Clave compuesta para el MERGE (¿qué campo identifica el registro?)
    UpdateByProperties =
    [
        nameof(RegistroApp.NomeProjeto),
        nameof(RegistroApp.Repositorio)
    ],

    // Protege campos que no deben sobrescribirse en el UPDATE
    PropertiesToExcludeOnUpdate =
    [
        nameof(RegistroApp.Id),       // Conserva el Id original
        nameof(RegistroApp.CriadoEm)  // Conserva la fecha de creación
    ],

    // SQL Server: opciones nativas de BulkCopy
    SqlBulkCopyOptions = EFCore.BulkExtensions.SqlBulkCopyOptions.Default
};

Ejemplo Real: Inventario de Aplicaciones

Para demostrar el poder de la biblioteca en un escenario enterprise, veamos cómo un sistema de inventario corporativo usa BulkInsertOrUpdateAsync para sincronizar datos de cientos de repositorios de Azure DevOps.

El Escenario

Una empresa necesita mantener un inventario actualizado de todas sus aplicaciones: proyectos, repositorios, lenguajes, versiones de framework y secrets de Azure Key Vault. Un Worker Service se ejecuta periódicamente para:

  1. Consultar la API de Azure DevOps y listar todos los repositorios
  2. Extraer los metadatos (lenguaje, framework, etc.) de cada repositorio
  3. Sincronizar la base de datos mediante BulkInsertOrUpdateAsync

El Repositorio

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
public class RegistroAppRepository(
    BulkDbContext dbContext,
    ILogger<RegistroAppRepository> logger)
{
    public async Task<int> InserirOuAtualizarAsync(
        List<RegistroApp> registros,
        IReadOnlyCollection<string> propriedadesExcluirNoUpdate,
        CancellationToken ct = default)
    {
        if (registros.Count == 0)
            return 0;

        var bulkConfig = new BulkConfig
        {
            SetOutputIdentity = true,
            PreserveInsertOrder = true,
            UpdateByProperties =
            [
                nameof(RegistroApp.NomeProjeto),
                nameof(RegistroApp.Repositorio)
            ],
            PropertiesToExcludeOnUpdate = [.. propriedadesExcluirNoUpdate],
            SqlBulkCopyOptions = EFCore.BulkExtensions.SqlBulkCopyOptions.Default,
            TrackingEntities = false,
            BatchSize = 1000
        };

        await dbContext.BulkInsertOrUpdateAsync(
            registros, bulkConfig, cancellationToken: ct);

        logger.LogInformation(
            "BulkInsertOrUpdate concluído: {Count} registros processados",
            registros.Count);

        return registros.Count;
    }
}

El Mismo Patrón para Secrets

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
public class ConfiguracaoSeguraRepository(
    BulkDbContext dbContext,
    ILogger<ConfiguracaoSeguraRepository> logger)
{
    public async Task<int> SincronizarSecretsAsync(
        List<ConfiguracaoSegura> secrets,
        CancellationToken ct = default)
    {
        if (secrets.Count == 0)
            return 0;

        var bulkConfig = new BulkConfig
        {
            SetOutputIdentity = true,
            PreserveInsertOrder = true,
            UpdateByProperties =
            [
                nameof(ConfiguracaoSegura.Nome),
                nameof(ConfiguracaoSegura.NomeVault)
            ],
            PropertiesToExcludeOnUpdate =
            [
                nameof(ConfiguracaoSegura.Id),
                nameof(ConfiguracaoSegura.CriadoEm)
            ],
            TrackingEntities = false,
            BatchSize = 1000
        };

        await dbContext.BulkInsertOrUpdateAsync(
            secrets, bulkConfig, cancellationToken: ct);

        logger.LogInformation(
            "Secrets sincronizados: {Count} registros", secrets.Count);

        return secrets.Count;
    }
}

Observa que el patrón es idéntico para entidades diferentes: lo que cambia son las propiedades de UpdateByProperties (clave compuesta para el MERGE) y PropertiesToExcludeOnUpdate (campos protegidos).


Integración con Azure Service Bus para Alto Volumen

Cuando el volumen de datos es realmente alto — decenas de miles de registros llegando en ráfagas — la mejor práctica es combinar mensajería con operaciones bulk. Como exploré en detalle en el artículo Cuello de Botella en Bases de Datos: Mensajería y Paginación, la mensajería (Azure Service Bus o RabbitMQ) funciona como buffer entre el productor de datos y la base de datos, lo que permite al Worker consumir en lotes optimizados.

El Patrón: Service Bus + BulkInsertOrUpdate

El flujo es:

1
[Fonte de Dados]  →  [Azure Service Bus (fila)]  →  [Worker Service]  →  [BulkInsertOrUpdate]  →  [SQL Server]
  1. El productor envía mensajes a la cola (uno por registro)
  2. El Worker consume hasta N mensajes a la vez (ReceiveMessagesAsync)
  3. Convierte los mensajes en entidades de dominio
  4. Persiste de forma masiva mediante BulkInsertOrUpdateAsync
  5. Confirma los mensajes procesados con CompleteMessageAsync

Implementación

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
public class RegistroAppBulkProcessor(
    ServiceBusClient serviceBusClient,
    IServiceScopeFactory scopeFactory,
    ILogger<RegistroAppBulkProcessor> logger) : BackgroundService
{
    private const string QueueName = "registro-app-sync";
    private const int TamanhoLote = 1000;
    private const int TimeoutSegundos = 30;

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        var receiver = serviceBusClient.CreateReceiver(QueueName,
            new ServiceBusReceiverOptions
            {
                ReceiveMode = ServiceBusReceiveMode.PeekLock,
                PrefetchCount = TamanhoLote
            });

        while (!ct.IsCancellationRequested)
        {
            try
            {
                await ProcessarLoteAsync(receiver, ct);
            }
            catch (OperationCanceledException) when (ct.IsCancellationRequested)
            {
                break;
            }
            catch (Exception ex)
            {
                logger.LogError(ex,
                    "Erro no ciclo de processamento. Retry em 5s");
                await Task.Delay(TimeSpan.FromSeconds(5), ct);
            }
        }

        await receiver.DisposeAsync();
    }

    private async Task ProcessarLoteAsync(
        ServiceBusReceiver receiver, CancellationToken ct)
    {
        // 1. Recibe hasta TamanhoLote mensajes
        var mensagens = await receiver.ReceiveMessagesAsync(
            TamanhoLote,
            TimeSpan.FromSeconds(TimeoutSegundos), ct);

        if (mensagens.Count == 0)
            return;

        // 2. Convierte mensajes → entidades de dominio
        var registros = new List<RegistroApp>(mensagens.Count);
        var mensagensValidas = new List<ServiceBusReceivedMessage>();

        foreach (var msg in mensagens)
        {
            var dto = JsonSerializer.Deserialize<RegistroAppMessage>(msg.Body);
            if (dto is null)
            {
                await receiver.DeadLetterMessageAsync(msg,
                    "InvalidBody",
                    "Corpo da mensagem inválido", ct);
                continue;
            }

            registros.Add(new RegistroApp
            {
                NomeProjeto     = dto.NomeProjeto,
                Repositorio     = dto.Repositorio,
                Linguagem       = dto.Linguagem,
                Plataforma      = dto.Plataforma,
                TipoAplicacao   = dto.TipoAplicacao,
                VersaoFramework = dto.VersaoFramework,
                Legado          = dto.Legado
            });

            mensagensValidas.Add(msg);
        }

        // 3. Persiste de forma masiva mediante BulkInsertOrUpdate
        using var scope = scopeFactory.CreateScope();
        var dbContext = scope.ServiceProvider
                            .GetRequiredService<BulkDbContext>();

        var bulkConfig = new BulkConfig
        {
            SetOutputIdentity = true,
            PreserveInsertOrder = true,
            UpdateByProperties =
            [
                nameof(RegistroApp.NomeProjeto),
                nameof(RegistroApp.Repositorio)
            ],
            PropertiesToExcludeOnUpdate =
            [
                nameof(RegistroApp.Id),
                nameof(RegistroApp.CriadoEm)
            ],
            TrackingEntities = false,
            BatchSize = 1000
        };

        await dbContext.BulkInsertOrUpdateAsync(
            registros, bulkConfig, cancellationToken: ct);

        // 4. Confirma todos los mensajes procesados
        var completeTasks = mensagensValidas
            .Select(msg => receiver.CompleteMessageAsync(msg, ct));
        await Task.WhenAll(completeTasks);

        logger.LogInformation(
            "Lote processado: {Count} registros persistidos", registros.Count);
    }
}

Por Qué Funciona con Alto Volumen

Sin BulkExtensionsCon BulkExtensions
10.000 INSERT individuales1 BulkInsertOrUpdate con BatchSize = 1000
~100s (10ms × 10.000)~2-3s
10.000 transacciones10 transacciones (10 batches de 1.000)
ChangeTracker con 10.000 entidadesCero ChangeTracker

Para profundizar en Workers y Background Services de alto volumen, lee el artículo Worker y Background Service en .NET: Alto Volumen.


Cuándo Usar (y Cuándo No Usar) BulkExtensions

✅ Úsala Cuando

  • Carga inicial de datos (seed, migración, ETL)
  • Sincronización periódica con una API externa (Azure DevOps, SAP, otras bases de datos, etc.)
  • Procesamiento de colas (Azure Service Bus, RabbitMQ) con alto volumen
  • Importación de CSV/Excel con miles de filas
  • Actualización de estados en lote (flags, campos calculados)
  • Limpieza periódica de datos expirados

❌ No la Uses Cuando

  • CRUD simple con pocos registros por solicitud (EF Core estándar es suficiente)
  • Operaciones que necesitan validación individual por registro con reglas de negocio complejas
  • Escenarios en los que el ChangeTracker es necesario para auditoría o eventos de dominio
  • Tablas con triggers complejos que deben dispararse por registro

Alternativas Nativas de EF Core 8+

EF Core 8 introdujo ExecuteUpdate y ExecuteDelete, que se ejecutan directamente en la base de datos sin pasar por el ChangeTracker:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// EF Core 8+ nativo — actualiza sin cargar entidades
await context.RegistrosApps
    .Where(r => r.Legado)
    .ExecuteUpdateAsync(s => s
        .SetProperty(r => r.Desativado, true)
        .SetProperty(r => r.AtualizadoEm, DateTime.UtcNow));

// EF Core 8+ nativo — elimina sin cargar entidades
await context.RegistrosApps
    .Where(r => r.Desativado && r.AtualizadoEm < limiteData)
    .ExecuteDeleteAsync();

Estas alternativas son buenas para updates/deletes condicionales, pero no sustituyen a BulkInsertAsync, BulkInsertOrUpdateAsync ni BulkReadAsync, operaciones que EF Core nativo no ofrece.


Conclusión

EFCore.BulkExtensions es, sin duda, una de las bibliotecas más importantes del ecosistema .NET. Con más de 30 millones de descargas y una API consistente, cubre una carencia real de EF Core: las operaciones masivas con rendimiento nativo de base de datos.

Antes de culpar a EF Core por errores de tracking o de rendimiento, entiende el propósito de la herramienta: fue construida por ingenieros de datos que conocen a fondo SQL Server, PostgreSQL y Oracle. Si el comportamiento por defecto parece “incorrecto”, probablemente el escenario está fuera de su alcance.

Puntos clave:

  1. El error de tracking (delete + reinsert) es del desarrollador, no de EF Core: usa ChangeTracker.Clear() o, mejor aún, BulkInsertOrUpdateAsync
  2. TrackingEntities = false debe ser el valor por defecto en operaciones bulk
  3. UpdateByProperties define la clave lógica del MERGE: no necesita ser la PK
  4. PropertiesToExcludeOnUpdate protege campos como Id y CriadoEm de ser sobrescritos
  5. Combinado con Azure Service Bus, el patrón de consumo en lote + persistencia bulk es imbatible para alto volumen

📦 Código fuente: blog-zocateli-sample — DataAccess/BulkOperations