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:
| |
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):
| |
- Paquetes NuGet en el proyecto
Infra.Data.PostgreSQL:
| |
⚠️ Atención: El paquete
Microsoft.EntityFrameworkCore.Designes 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-projectal 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:
| |
El CLI necesita dos informaciones:
- Dónde está el DbContext (
--project) — enInfra.Data.PostgreSQL - Dónde está el entry point (
--startup-project) — enApi(para resolver la DI y la connection string)
Solución 1: Parámetros del CLI (Rápido)
| |
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:
| |
Con esta factory, el CLI encuentra el DbContext directamente:
| |
💡 Consejo: La
IDesignTimeDbContextFactoryes usada solo por el CLI de EF Core (en design-time). En runtime, elDbContextsigue 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
| |
En el proyecto Api (entry point), haz lo mismo:
| |
En appsettings.json — Sin Contraseña
El appsettings.json versionado en Git queda sin datos sensibles:
| |
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:
| |
⚠️ Atención: Cada desarrollador del equipo debe ejecutar
dotnet user-secrets seten 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
| |
Opciones Esenciales del Scaffold
| Parámetro | Descripción |
|---|---|
--output-dir Entities | Dónde generar las clases de entidad |
--context-dir . | Dónde generar el DbContext |
--context LegadoDbContext | Nombre de la clase DbContext |
--schema public | Scaffold solo de las tablas de un schema específico |
--table produtos --table categorias | Scaffold solo de tablas específicas |
--no-onconfiguring | No genera OnConfiguring con la connection string hardcoded |
--data-annotations | Usa Data Annotations (el default es Fluent API — ¡queremos Fluent API!) |
--force | Sobrescribe archivos existentes |
--no-pluralize | No 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:
| |
💡 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:
| |
Providers para Scaffold
El provider en el comando scaffold corresponde a la base de datos de destino:
| Base de datos | Provider NuGet |
|---|---|
| PostgreSQL | Npgsql.EntityFrameworkCore.PostgreSQL |
| SQL Server | Microsoft.EntityFrameworkCore.SqlServer |
| Oracle | Oracle.EntityFrameworkCore |
| MySQL | Pomelo.EntityFrameworkCore.MySql |
| SQLite | Microsoft.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:
| |
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:
| |
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í:
| |
Estrategia 3: Convención de Nombres con Timestamp
Usa nombres de migration con timestamp para evitar colisiones:
| |
Reglas de Oro Para el Equipo
Nunca edites una migration ya aplicada a la base de producción/staging — crea una nueva migration para corregirla.
Haz merge de la
mainen tu branch ANTES de crear la migration — garantiza que el snapshot está actualizado.Una feature, una migration — evita múltiples migrations por PR. Si necesitas ajustes, elimínala, ajusta la entidad y recréala.
Revisa las migrations en el Pull Request — el SQL generado (
dotnet ef migrations script) debe revisarse como cualquier otro código.Mantén el snapshot en Git — el
AppDbContextModelSnapshot.csDEBE versionarse. Nunca lo agregues al.gitignore.Usa
--idempotentpara scripts de producción — genera SQL conIF NOT EXISTS, seguro para ejecutar múltiples veces:
| |
- 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
Para consolidar todo, aquí está el flujo completo en un proyecto multicapa:
| |
Comandos Esenciales de Referencia
| Acción | Comando |
|---|---|
| Crear migration | dotnet ef migrations add Nome --project Infra.Data |
| Aplicar migrations | dotnet ef database update --project Infra.Data |
| Eliminar la última migration | dotnet ef migrations remove --project Infra.Data |
| Listar migrations | dotnet ef migrations list --project Infra.Data |
| Generar script SQL | dotnet ef migrations script --idempotent --project Infra.Data |
| Script entre migrations | dotnet ef migrations script MigA MigB --project Infra.Data |
| Revertir migration | dotnet ef database update NomeMigAnterior --project Infra.Data |
| Scaffold de base existente | dotnet ef dbcontext scaffold "connstr" Provider --project Infra.Data |
| Verificar pendientes | dotnet ef migrations list --project Infra.Data (muestra Pending) |
Consejos y Buenas Prácticas
Genera siempre el script SQL antes de aplicar en producción — nunca uses
dotnet ef database updatedirectamente en producción. Genéralo con--idempotent, revísalo y aplícalo vía DBA o pipeline.Usa
IDesignTimeDbContextFactory— elimina la dependencia del startup project y permite que cada desarrollador use sus propios secrets.Separa las migrations por provider — si tu aplicación soporta PostgreSQL y SQL Server, mantén migrations separadas con
MigrationsAssembly()apuntando a proyectos diferentes.No ignores el snapshot — el
AppDbContextModelSnapshot.cses el “estado actual” del modelo para el EF Core CLI. Sin él, el CLI no puede calcular el diff para la próxima migration.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.
Revisa el SQL generado en los PRs — agrega la salida de
dotnet ef migrations scriptcomo comentario en el PR para que el equipo pueda revisar el DDL.Usa
HasData()con cautela — el seed data víaHasData()genera migrations. Para datos grandes o dinámicos, prefiere scripts SQL separados.Configura retry para
database update— en CI/CD, la base puede no estar lista. Usa:
| |
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
- EF Core 8 Fluent API: Mapeo, ORM y Desacoplamiento — mapeo avanzado con Fluent API, todos los tipos de relación, herencia y funcionalidades avanzadas de EF Core 8+.
- Configuración .NET 8+: IOptions, Secrets y Docker — cómo
appsettings.json,dotnet user-secrets, variables de entorno y Docker/Podman secrets se integran en el pipeline de configuración de .NET 8+. - Cuello de Botella en Bases de Datos: Mensajería y Paginación — cómo resolver cuellos de botella de escritura y lectura en proyectos EF Core.
- Paginación en APIs REST con C# y EF Core: Guía Práctica — todos los tipos de paginación con EF Core para diferentes bases.
- Makefile: Automatizando tareas para Python, Hugo y Docker — automatiza tareas repetitivas como migrations con Makefile.
- Diseño de API REST: Verbos HTTP y Parameter Binding — buenas prácticas para la capa de API que consume EF Core.
Referencias
- EF Core — Migrations Overview — documentación oficial sobre la creación y aplicación de migrations en EF Core.
- EF Core — Design-time DbContext Creation — cómo el EF Core CLI encuentra el DbContext, incluida la
IDesignTimeDbContextFactory. - EF Core — Reverse Engineering (Scaffold) — documentación oficial sobre el scaffold de bases existentes para generar entidades y configuraciones.
- ASP.NET Core — Safe storage of secrets — documentación oficial de
dotnet user-secretspara el almacenamiento seguro de configuraciones sensibles. - EF Core — Applying Migrations — estrategias para aplicar migrations en producción (scripts, bundles, runtime).
- EF Core — Managing Migrations — gestión de migrations existentes (eliminar, rebase, squash).
- EF Core CLI Reference — referencia completa de todos los comandos
dotnet ef. - Npgsql — EF Core Provider for PostgreSQL — documentación del provider PostgreSQL para EF Core.
- Repositorio blog-zocateli-sample — Migrations — Código fuente completo de los ejemplos de este artículo

Al comentar, aceptas nuestra Política de Privacidad, Términos de Uso, Política de Eliminación de Datos.