Introducción

Si ya configuraste EF Core Migrations en un proyecto simple con un único csproj, sabes que es razonablemente directo: dotnet ef migrations add, dotnet ef database update y listo. Pero la realidad de los proyectos corporativos es otra. Tu solución tiene múltiples proyectos — API, Domain, IoC, Infra.Data.PostgreSQL, Infra.Bus, Infra.Http, Infra.Dto — y el DbContext no vive en el mismo proyecto que el entry point. Ahora agrega dotnet secrets para gestionar connection strings de forma segura, la necesidad de hacer scaffolding de bases de datos legadas que ya existen, y un equipo con 5 o 10 desarrolladores creando migrations simultáneamente.

En este artículo, resuelvo cada uno de estos problemas en la práctica. Configuro migrations en una solución multicapa real, uso dotnet user-secrets para connection strings (sin contraseñas en appsettings.json), hago ingeniería inversa de bases existentes con Scaffold-DbContext, y establezco estrategias concretas para evitar conflictos de migrations en equipos grandes. Si todavía no conoces el mapeo avanzado con Fluent API que genera estas migrations, te recomiendo leer antes EF Core 8 Fluent API: Mapeo, ORM y Desacoplamiento.

📦 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.


Estructura del Proyecto Multicapa

Antes de hablar de migrations, es esencial entender la estructura del proyecto. Es una solución .NET 8 con separación de responsabilidades en múltiples csproj:

 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
MeuEcommerce.sln
│
├── src/
│   ├── MeuEcommerce.Api/                    # Entry point — ASP.NET Core Web API
│   │   ├── Program.cs
│   │   ├── Controllers/
│   │   └── appsettings.json
│   │
│   ├── MeuEcommerce.Domain/                 # Entidades e interfaces — SIN dependencia de EF Core
│   │   ├── Entities/
│   │   │   ├── Produto.cs
│   │   │   ├── Categoria.cs
│   │   │   └── ...
│   │   └── Interfaces/
│   │       └── IProdutoRepository.cs
│   │
│   ├── MeuEcommerce.IoC/                    # Inyección de dependencias — registra todo
│   │   └── DependencyInjection.cs
│   │
│   ├── MeuEcommerce.Infra.Data.PostgreSQL/  # EF Core + Migrations (DbContext vive AQUÍ)
│   │   ├── AppDbContext.cs
│   │   ├── Configurations/
│   │   │   ├── ProdutoConfiguration.cs
│   │   │   └── CategoriaConfiguration.cs
│   │   ├── Repositories/
│   │   │   └── ProdutoRepository.cs
│   │   ├── Migrations/                      # Migrations generadas aquí
│   │   └── DesignTimeDbContextFactory.cs    # Factory para el EF CLI
│   │
│   ├── MeuEcommerce.Infra.Bus/             # Mensajería (RabbitMQ, Azure Service Bus)
│   ├── MeuEcommerce.Infra.Http/            # HttpClient para APIs externas
│   └── MeuEcommerce.Infra.Dto/             # DTOs compartidos
│
└── tests/
    └── MeuEcommerce.Tests/

Punto crítico: El DbContext vive en Infra.Data.PostgreSQL, pero el entry point (Program.cs) vive en Api. El EF Core CLI necesita ambos para funcionar — necesita el DbContext para generar migrations y el entry point para resolver connection strings y dependencias.

ℹ️ Información: Esta estructura sigue el patrón de Arquitectura en Capas / Clean Architecture, donde el Domain no depende de la infraestructura. Si quieres entender los patrones arquitectónicos detrás de esta organización, consulta Arquitectura de Software: GoF, Patrones y Microservicios.


Requisitos previos

  • .NET 8.0 SDK o superior
  • Herramienta dotnet-ef (EF Core CLI):
1
2
3
4
5
6
7
dotnet tool install --global dotnet-ef

# O actualizar a la última versión
dotnet tool update --global dotnet-ef

# Verificar la instalación
dotnet ef --version
  • Paquetes NuGet en el proyecto Infra.Data.PostgreSQL:
1
2
3
4
5
cd src/MeuEcommerce.Infra.Data.PostgreSQL

dotnet add package Microsoft.EntityFrameworkCore --version 8.0.*
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL --version 8.0.*
dotnet add package Microsoft.EntityFrameworkCore.Design --version 8.0.*

⚠️ Atención: El paquete Microsoft.EntityFrameworkCore.Design es obligatorio para que el CLI de EF Core funcione. Puede agregarse en el proyecto de datos O en el proyecto de startup. Si está solo en el startup, usa --startup-project al ejecutar los comandos.


Configurando Migrations en Multiproyecto

El Problema

Al ejecutar dotnet ef migrations add sin configuración adicional, el CLI intenta encontrar el DbContext y las dependencias en el proyecto actual. En un proyecto multicapa, esto falla con errores como:

1
2
Unable to create a 'DbContext' of type 'AppDbContext'.
The exception 'Unable to resolve service for type...' was thrown.

El CLI necesita dos informaciones:

  1. Dónde está el DbContext (--project) — en Infra.Data.PostgreSQL
  2. Dónde está el entry point (--startup-project) — en Api (para resolver la DI y la connection string)

Solución 1: Parámetros del CLI (Rápido)

1
2
3
4
5
6
7
8
9
# Desde la raíz de la solución
dotnet ef migrations add InitialCreate \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL \
  --startup-project src/MeuEcommerce.Api \
  --output-dir Migrations

dotnet ef database update \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL \
  --startup-project src/MeuEcommerce.Api

Funciona, pero es verboso. En cada migration necesitas recordar las rutas.

Solución 2: IDesignTimeDbContextFactory (Recomendado)

Crea una factory en el proyecto Infra.Data.PostgreSQL que el CLI usa en design-time — sin depender del Program.cs de la API:

 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
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;
using Microsoft.Extensions.Configuration;

namespace MeuEcommerce.Infra.Data.PostgreSQL;

/// <summary>
/// Factory usada SOLO por el EF Core CLI (dotnet ef migrations add/update).
/// En runtime, el DbContext se resuelve por la DI configurada en IoC.
/// </summary>
public class DesignTimeDbContextFactory : IDesignTimeDbContextFactory<AppDbContext>
{
    public AppDbContext CreateDbContext(string[] args)
    {
        // Busca la connection string en user-secrets o environment variables
        var configuration = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json", optional: true)
            .AddUserSecrets<DesignTimeDbContextFactory>(optional: true)
            .AddEnvironmentVariables()
            .Build();

        var connectionString = configuration.GetConnectionString("DefaultConnection")
            ?? throw new InvalidOperationException(
                "Connection string 'DefaultConnection' no encontrada. " +
                "Configúrela vía 'dotnet user-secrets set' o variable de entorno.");

        var optionsBuilder = new DbContextOptionsBuilder<AppDbContext>();
        optionsBuilder.UseNpgsql(connectionString, npgsql =>
        {
            npgsql.MigrationsAssembly(
                typeof(DesignTimeDbContextFactory).Assembly.FullName);
        });

        return new AppDbContext(optionsBuilder.Options);
    }
}

Con esta factory, el CLI encuentra el DbContext directamente:

1
2
3
4
5
# Ahora basta apuntar al proyecto de datos — sin --startup-project
cd src/MeuEcommerce.Infra.Data.PostgreSQL

dotnet ef migrations add InitialCreate
dotnet ef database update

💡 Consejo: La IDesignTimeDbContextFactory es usada solo por el CLI de EF Core (en design-time). En runtime, el DbContext sigue siendo resuelto por la inyección de dependencias configurada en el proyecto IoC. Las dos vías coexisten sin conflicto.


dotnet user-secrets para Connection Strings

Nunca pongas connection strings con contraseñas en appsettings.json (que va a Git). Usa dotnet user-secrets para almacenar datos sensibles localmente.

Configuración Inicial

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# En el proyecto que tiene la IDesignTimeDbContextFactory (Infra.Data.PostgreSQL)
cd src/MeuEcommerce.Infra.Data.PostgreSQL
dotnet user-secrets init

# Definir la connection string
dotnet user-secrets set "ConnectionStrings:DefaultConnection" \
  "Host=localhost;Port=5432;Database=meuecommerce;Username=postgres;Password=minha-senha-local"

# Verificar los secrets almacenados
dotnet user-secrets list

En el proyecto Api (entry point), haz lo mismo:

1
2
3
4
5
cd src/MeuEcommerce.Api
dotnet user-secrets init

dotnet user-secrets set "ConnectionStrings:DefaultConnection" \
  "Host=localhost;Port=5432;Database=meuecommerce;Username=postgres;Password=minha-senha-local"

En appsettings.json — Sin Contraseña

El appsettings.json versionado en Git queda sin datos sensibles:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "ConnectionStrings": {
    "DefaultConnection": ""
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

En runtime, el builder.Configuration de ASP.NET Core carga los user-secrets automáticamente cuando IsDevelopment() es true. En producción, usa variables de entorno o Azure Key Vault.

Ejecutando Migrations con Secrets

Con la IDesignTimeDbContextFactory configurada para leer AddUserSecrets, los comandos del EF Core CLI funcionan directamente:

1
2
3
4
5
6
7
8
cd src/MeuEcommerce.Infra.Data.PostgreSQL

# La factory lee la connection string de los user-secrets
dotnet ef migrations add AdicionarTabelaProdutos
dotnet ef database update

# Para ver el SQL que se generará (sin ejecutarlo):
dotnet ef migrations script --idempotent

⚠️ Atención: Cada desarrollador del equipo debe ejecutar dotnet user-secrets set en su máquina con las credenciales de la base local. Los user-secrets se almacenan en %APPDATA%\Microsoft\UserSecrets\ (Windows) o ~/.microsoft/usersecrets/ (Linux/macOS) y nunca van a Git.


Scaffolding: Base de Datos Existente (Ingeniería Inversa)

Cuando necesitas integrarte con una base de datos existente (legada), EF Core puede generar automáticamente las entidades y configuraciones a partir del schema existente. Esto se llama scaffolding o ingeniería inversa (reverse engineering).

Comando Básico

1
2
3
4
5
6
7
8
dotnet ef dbcontext scaffold \
  "Host=localhost;Port=5432;Database=sistema_legado;Username=postgres;Password=senha" \
  Npgsql.EntityFrameworkCore.PostgreSQL \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL \
  --output-dir Entities \
  --context-dir . \
  --context LegadoDbContext \
  --force

Opciones Esenciales del Scaffold

ParámetroDescripción
--output-dir EntitiesDónde generar las clases de entidad
--context-dir .Dónde generar el DbContext
--context LegadoDbContextNombre de la clase DbContext
--schema publicScaffold solo de las tablas de un schema específico
--table produtos --table categoriasScaffold solo de tablas específicas
--no-onconfiguringNo genera OnConfiguring con la connection string hardcoded
--data-annotationsUsa Data Annotations (el default es Fluent API — ¡queremos Fluent API!)
--forceSobrescribe archivos existentes
--no-pluralizeNo pluraliza los nombres de DbSet

Scaffold con Fluent API (Recomendado)

Por defecto, el scaffold ya usa Fluent API (no Data Annotations). Para tener el máximo control:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
dotnet ef dbcontext scaffold \
  "Host=localhost;Port=5432;Database=sistema_legado;Username=postgres;Password=senha" \
  Npgsql.EntityFrameworkCore.PostgreSQL \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL \
  --output-dir Entities/Legado \
  --context-dir . \
  --context LegadoDbContext \
  --no-onconfiguring \
  --no-pluralize \
  --force

💡 Consejo: Después del scaffold, mueve las entidades generadas al proyecto Domain y ajusta los namespaces. El scaffold genera todo en el proyecto de datos, pero siguiendo la arquitectura limpia, las entidades pertenecen al Domain. Las configuraciones Fluent API se quedan en el proyecto de datos.

Scaffold Parcial (Tablas Específicas)

Para bases grandes, haz scaffold solo de las tablas necesarias:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# Solo tablas del schema 'vendas'
dotnet ef dbcontext scaffold \
  "Host=localhost;Database=legado;Username=postgres;Password=senha" \
  Npgsql.EntityFrameworkCore.PostgreSQL \
  --schema vendas \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL \
  --output-dir Entities/Vendas \
  --context VendasDbContext \
  --no-onconfiguring

# O tablas específicas
dotnet ef dbcontext scaffold \
  "Host=localhost;Database=legado;Username=postgres;Password=senha" \
  Npgsql.EntityFrameworkCore.PostgreSQL \
  --table produtos --table categorias --table pedidos \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL \
  --output-dir Entities/Core \
  --context CoreLegadoDbContext \
  --no-onconfiguring

Providers para Scaffold

El provider en el comando scaffold corresponde a la base de datos de destino:

Base de datosProvider NuGet
PostgreSQLNpgsql.EntityFrameworkCore.PostgreSQL
SQL ServerMicrosoft.EntityFrameworkCore.SqlServer
OracleOracle.EntityFrameworkCore
MySQLPomelo.EntityFrameworkCore.MySql
SQLiteMicrosoft.EntityFrameworkCore.Sqlite

Gestionando Migrations en Equipos con Múltiples Desarrolladores

Este es uno de los mayores desafíos prácticos de EF Core en proyectos corporativos. Cuando 3, 5 o 10 desarrolladores crean migrations simultáneamente, los conflictos son inevitables si no hay un proceso claro.

El Problema: Conflictos de Migration

Imagina dos desarrolladores trabajando en branches separadas:

1
2
3
4
5
main ─────────────── Migration_001 (InitialCreate)
  │
  ├── feat/produtos ── Migration_002_AdicionarProdutos (Dev A)
  │
  └── feat/pedidos ─── Migration_002_AdicionarPedidos  (Dev B)

Ambas migrations tienen el mismo snapshot como base (después de Migration_001). Cuando Dev B hace merge después de Dev A, EF Core detecta que el snapshot es inconsistente y falla.

Estrategia 1: Rebase de la Migration (Recomendado)

Cuando haya conflicto, elimina la migration en conflicto y recréala sobre el estado actual:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Dev B después del pull/merge de la branch de Dev A:

# 1. Eliminar la migration en conflicto (ANTES de aplicarla a la base)
dotnet ef migrations remove \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL

# 2. Verificar que la base local está actualizada con las migrations de Dev A
dotnet ef database update \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL

# 3. Recrear la migration sobre el estado correcto
dotnet ef migrations add AdicionarPedidos \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL

Estrategia 2: Merge del Model Snapshot

El archivo AppDbContextModelSnapshot.cs es el que causa la mayoría de los conflictos de merge. Trátalo así:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# En caso de conflicto en el snapshot, SIEMPRE:
# 1. Acepte la versión de la branch destino (main/develop)
git checkout --theirs src/MeuEcommerce.Infra.Data.PostgreSQL/Migrations/AppDbContextModelSnapshot.cs

# 2. Elimine su migration
dotnet ef migrations remove --project src/MeuEcommerce.Infra.Data.PostgreSQL

# 3. Actualice la base local
dotnet ef database update --project src/MeuEcommerce.Infra.Data.PostgreSQL

# 4. Recree su migration con el snapshot correcto como base
dotnet ef migrations add SuaMigration --project src/MeuEcommerce.Infra.Data.PostgreSQL

Estrategia 3: Convención de Nombres con Timestamp

Usa nombres de migration con timestamp para evitar colisiones:

1
2
3
4
5
6
7
8
# En lugar de nombres genéricos que pueden colisionar:
dotnet ef migrations add 20260118_AdicionarTabelaPedidos

# Formato recomendado: YYYYMMDD_NombreDeLaMigration
# Ejemplos:
dotnet ef migrations add 20260118_AdicionarPedidos
dotnet ef migrations add 20260119_AlterarProdutoSku
dotnet ef migrations add 20260120_CriarIndiceProdutoNome

Reglas de Oro Para el Equipo

  1. Nunca edites una migration ya aplicada a la base de producción/staging — crea una nueva migration para corregirla.

  2. Haz merge de la main en tu branch ANTES de crear la migration — garantiza que el snapshot está actualizado.

  3. Una feature, una migration — evita múltiples migrations por PR. Si necesitas ajustes, elimínala, ajusta la entidad y recréala.

  4. Revisa las migrations en el Pull Request — el SQL generado (dotnet ef migrations script) debe revisarse como cualquier otro código.

  5. Mantén el snapshot en Git — el AppDbContextModelSnapshot.cs DEBE versionarse. Nunca lo agregues al .gitignore.

  6. Usa --idempotent para scripts de producción — genera SQL con IF NOT EXISTS, seguro para ejecutar múltiples veces:

1
2
3
dotnet ef migrations script --idempotent \
  --project src/MeuEcommerce.Infra.Data.PostgreSQL \
  --output migration-producao.sql
  1. Comunica en el canal del equipo antes de crear migrations — un mensaje simple como “voy a crear una migration para la tabla X” evita trabajo duplicado.

⚠️ Atención: En equipos más grandes (8+ devs), considera designar una branch de integración donde todas las migrations se consoliden antes de ir a main. Esto reduce drásticamente los conflictos de snapshot.


Flujo Completo: De la Entidad a la Base de Datos

Diagrama del flujo completo de EF Core Migrations con las etapas desde el cambio en la entidad, Fluent API y creación de la migration hasta la actualización de PostgreSQL

Para consolidar todo, aquí está el flujo completo en un proyecto multicapa:

 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
# 1. Crear/editar la entidad en Domain (sin referencia a EF Core)
# src/MeuEcommerce.Domain/Entities/Pedido.cs

# 2. Crear la configuración Fluent API en Infra.Data
# src/MeuEcommerce.Infra.Data.PostgreSQL/Configurations/PedidoConfiguration.cs

# 3. Agregar el DbSet en AppDbContext
# public DbSet<Pedido> Pedidos => Set<Pedido>();

# 4. Registrar en IoC (si es necesario — repository, etc.)

# 5. Asegurar que está en la branch actualizada
git pull origin main

# 6. Crear la migration
cd src/MeuEcommerce.Infra.Data.PostgreSQL
dotnet ef migrations add 20260118_AdicionarPedidos

# 7. Verificar el SQL que se generará
dotnet ef migrations script --idempotent

# 8. Aplicar a la base local
dotnet ef database update

# 9. Probar la aplicación

# 10. Commit y PR
git add .
git commit -m "feat(domain): agregar entidad Pedido con Fluent API"

Comandos Esenciales de Referencia

AcciónComando
Crear migrationdotnet ef migrations add Nome --project Infra.Data
Aplicar migrationsdotnet ef database update --project Infra.Data
Eliminar la última migrationdotnet ef migrations remove --project Infra.Data
Listar migrationsdotnet ef migrations list --project Infra.Data
Generar script SQLdotnet ef migrations script --idempotent --project Infra.Data
Script entre migrationsdotnet ef migrations script MigA MigB --project Infra.Data
Revertir migrationdotnet ef database update NomeMigAnterior --project Infra.Data
Scaffold de base existentedotnet ef dbcontext scaffold "connstr" Provider --project Infra.Data
Verificar pendientesdotnet ef migrations list --project Infra.Data (muestra Pending)

Consejos y Buenas Prácticas

  1. Genera siempre el script SQL antes de aplicar en producción — nunca uses dotnet ef database update directamente en producción. Genéralo con --idempotent, revísalo y aplícalo vía DBA o pipeline.

  2. Usa IDesignTimeDbContextFactory — elimina la dependencia del startup project y permite que cada desarrollador use sus propios secrets.

  3. Separa las migrations por provider — si tu aplicación soporta PostgreSQL y SQL Server, mantén migrations separadas con MigrationsAssembly() apuntando a proyectos diferentes.

  4. No ignores el snapshot — el AppDbContextModelSnapshot.cs es el “estado actual” del modelo para el EF Core CLI. Sin él, el CLI no puede calcular el diff para la próxima migration.

  5. Automatiza con Makefile o scripts — crea atajos para los comandos más usados. Para saber más sobre automatización con Makefile, consulta Makefile: Automatizando tareas para Python, Hugo y Docker.

  6. Revisa el SQL generado en los PRs — agrega la salida de dotnet ef migrations script como comentario en el PR para que el equipo pueda revisar el DDL.

  7. Usa HasData() con cautela — el seed data vía HasData() genera migrations. Para datos grandes o dinámicos, prefiere scripts SQL separados.

  8. Configura retry para database update — en CI/CD, la base puede no estar lista. Usa:

1
2
3
4
5
6
7
optionsBuilder.UseNpgsql(connectionString, npgsql =>
{
    npgsql.EnableRetryOnFailure(
        maxRetryCount: 5,
        maxRetryDelay: TimeSpan.FromSeconds(30),
        errorCodesToAdd: null);
});

Conclusión

Gestionar EF Core Migrations en proyectos multicapa exige configuración específica, pero la recompensa es una base de código organizada, segura y sostenible. La IDesignTimeDbContextFactory resuelve el problema de design-time en soluciones con múltiples csproj. El dotnet user-secrets mantiene las connection strings fuera del código versionado. El scaffolding permite integrar bases legadas sin reescribir el schema manualmente. Y con convenciones claras de nombres, rebase de migrations y comunicación en el equipo, es posible escalar a equipos grandes sin conflictos constantes.

El EF Core CLI es poderoso, pero exige disciplina. Establece las reglas del equipo desde el inicio del proyecto, documenta el flujo de creación de migrations en el README y revisa el SQL generado en cada Pull Request. Para entender cómo el mapeo avanzado con Fluent API genera estas migrations correctamente, consulta EF Core 8 Fluent API: Mapeo, ORM y Desacoplamiento.


Lee También


Referencias