MigracionesMigrations

Un modelo de datos cambia durante el desarrollo y deja de estar sincronizado con la base de datos.A data model changes during development and gets out of sync with the database. Puede quitar la base de datos y dejar que EF cree una que coincida con el modelo, pero este procedimiento provoca la pérdida de datos.You can drop the database and let EF create a new one that matches the model, but this procedure results in the loss of data. La característica de migraciones de EF Core proporciona una manera de actualizar incrementalmente el esquema de la base de datos para mantenerla sincronizada con el modelo de datos de la aplicación al tiempo que se conservan los datos existentes en la base de datos.The migrations feature in EF Core provides a way to incrementally update the database schema to keep it in sync with the application's data model while preserving existing data in the database.

Las migraciones incluyen herramientas de línea de comandos y API que facilitan las siguientes tareas:Migrations includes command-line tools and APIs that help with the following tasks:

Instalar las herramientasInstall the tools

Instale las herramientas de línea de comandos:Install the command-line tools:

Crear una migraciónCreate a migration

Una vez definido el modelo inicial, es el momento de crear la base de datos.After you've defined your initial model, it's time to create the database. Para agregar una migración inicial, ejecute el siguiente comando.To add an initial migration, run the following command.

Add-Migration InitialCreate
dotnet ef migrations add InitialCreate

Se agregan tres archivos al proyecto en el directorio Migraciones:Three files are added to your project under the Migrations directory:

  • 00000000000000_InitialCreate.cs: archivo principal de migraciones.00000000000000_InitialCreate.cs--The main migrations file. Contiene las operaciones necesarias para aplicar la migración (en Up()) y para revertirla (en Down()).Contains the operations necessary to apply the migration (in Up()) and to revert it (in Down()).
  • 00000000000000_InitialCreate.Designer.cs: archivo de metadatos de migraciones.00000000000000_InitialCreate.Designer.cs--The migrations metadata file. Contiene información que usa EF.Contains information used by EF.
  • MyContextModelSnapshot.cs: instantánea del modelo actual.MyContextModelSnapshot.cs--A snapshot of your current model. Se usa para determinar qué ha cambiado al agregar la siguiente migración.Used to determine what changed when adding the next migration.

La marca de tiempo del nombre del archivo ayuda a mantenerlos ordenados cronológicamente para que se pueda ver la progresión de cambios.The timestamp in the filename helps keep them ordered chronologically so you can see the progression of changes.

Sugerencia

Puede mover los archivos de Migraciones y cambiar su espacio de nombres.You are free to move Migrations files and change their namespace. Se crean nuevas migraciones como elementos del mismo nivel de la última migración.New migrations are created as siblings of the last migration.

Actualizar la base de datosUpdate the database

Luego aplique la migración a la base de datos para crear el esquema.Next, apply the migration to the database to create the schema.

Update-Database
dotnet ef database update

Personalizar el código de migraciónCustomize migration code

Después de realizar cambios en el modelo de EF Core, puede que el esquema de la base de datos no esté sincronizado. Para ponerlo al día, agregue otra migración.After making changes to your EF Core model, the database schema might be out of sync. To bring it up to date, add another migration. El nombre de la migración se puede usar como mensaje de confirmación en un sistema de control de versiones.The migration name can be used like a commit message in a version control system. Por ejemplo, podría elegir un nombre como AddProductReviews si el cambio es una nueva clase de entidad para las revisiones.For example, you might choose a name like AddProductReviews if the change is a new entity class for reviews.

Add-Migration AddProductReviews
dotnet ef migrations add AddProductReviews

Tras aplicar scaffolding a la migración (código generado para ella), revise el código para mayor precisión y agregue, quite o modifique todas las operaciones necesarias para aplicarla correctamente.Once the migration is scaffolded (code generated for it), review the code for accuracy and add, remove or modify any operations required to apply it correctly.

Por ejemplo, una migración podría contener las siguientes operaciones:For example, a migration might contain the following operations:

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

migrationBuilder.AddColumn<string>(
    name: "Name",
    table: "Customer",
    nullable: true);

Aunque estas operaciones hacen que el esquema de la base de datos sea compatible, no conservan los nombres de cliente existentes.While these operations make the database schema compatible, they don't preserve the existing customer names. Para que sea mejor, vuelva a escribirla como se indica a continuación.To make it better, rewrite it as follows.

migrationBuilder.AddColumn<string>(
    name: "Name",
    table: "Customer",
    nullable: true);

migrationBuilder.Sql(
@"
    UPDATE Customer
    SET Name = FirstName + ' ' + LastName;
");

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

Sugerencia

El proceso de scaffolding de la migración advierte si una operación puede ocasionar una pérdida de datos (como el borrado de una columna).The migration scaffolding process warns when an operation might result in data loss (like dropping a column). Si aparece dicha advertencia, asegúrese especialmente de revisar el código de las migraciones para mayor precisión.If you see that warning, be especially sure to review the migrations code for accuracy.

Aplique la migración a la base de datos con el comando apropiado.Apply the migration to the database using the appropriate command.

Update-Database
dotnet ef database update

Migraciones vacíasEmpty migrations

A veces resulta útil agregar una migración sin realizar ningún cambio de modelo.Sometimes it's useful to add a migration without making any model changes. En este caso, agregar una nueva migración crea archivos de código con clases vacías.In this case, adding a new migration creates code files with empty classes. Puede personalizar esta migración para llevar a cabo operaciones que no estén directamente relacionadas con el modelo de EF Core.You can customize this migration to perform operations that don't directly relate to the EF Core model. Algunos aspectos que podría querer administrar de esta manera son:Some things you might want to manage this way are:

  • Búsqueda de texto completoFull-Text Search
  • FuncionesFunctions
  • Procedimientos almacenadosStored procedures
  • DesencadenadoresTriggers
  • VistasViews

Quitar una migraciónRemove a migration

A veces uno agrega una migración y se da cuenta de que debe realizar cambios adicionales en el modelo de EF Core antes de aplicarla.Sometimes you add a migration and realize you need to make additional changes to your EF Core model before applying it. Para quitar la última migración, use este comando.To remove the last migration, use this command.

Remove-Migration
dotnet ef migrations remove

Después de quitar la migración, puede realizar los cambios de modelo adicionales y volver a agregarla.After removing the migration, you can make the additional model changes and add it again.

Revertir una migraciónRevert a migration

Si ya ha aplicado una migración (o varias migraciones) a la base de datos pero necesita revertirla, puede usar el mismo comando que para aplicar migraciones, aunque debe especificar el nombre de la migración que quiere revertir.If you already applied a migration (or several migrations) to the database but need to revert it, you can use the same command to apply migrations, but specify the name of the migration you want to roll back to.

Update-Database LastGoodMigration
dotnet ef database update LastGoodMigration

Generar scripts SQLGenerate SQL scripts

Al depurar las migraciones o implementarlas en una base de datos de producción, es útil generar un script SQL.When debugging your migrations or deploying them to a production database, it's useful to generate a SQL script. El script luego se puede revisar y ajustar a las necesidades de una base de datos de producción.The script can then be further reviewed for accuracy and tuned to fit the needs of a production database. El script también puede usarse junto con una tecnología de implementación.The script can also be used in conjunction with a deployment technology. El comando básico es el siguiente.The basic command is as follows.

Script-Migration
dotnet ef migrations script

Hay varias opciones para este comando.There are several options to this command.

La migración from debe ser la última migración aplicada a la base de datos antes de ejecutar el script.The from migration should be the last migration applied to the database before running the script. Si no se han aplicado migraciones, especifique 0 (es el valor predeterminado).If no migrations have been applied, specify 0 (this is the default).

La migración to debe ser la última migración que se va a aplicar a la base de datos después de ejecutar el script.The to migration is the last migration that will be applied to the database after running the script. El valor predeterminado es la última migración del proyecto.This defaults to the last migration in your project.

Se puede generar un script idempotent de forma opcional.An idempotent script can optionally be generated. Este script solo aplica migraciones si aún no se han aplicado a la base de datos.This script only applies migrations if they haven't already been applied to the database. Es útil si no sabe exactamente cuál ha sido la última migración aplicada a la base de datos o si va a implementar en varias bases de datos que pueden encontrarse en migraciones diferentes.This is useful if you don't exactly know what the last migration applied to the database was or if you are deploying to multiple databases that may each be at a different migration.

Aplicar migraciones en tiempo de ejecuciónApply migrations at runtime

Algunas aplicaciones pueden querer aplicar migraciones en tiempo de ejecución durante el inicio o la primera ejecución.Some apps may want to apply migrations at runtime during startup or first run. Para ello, se usa el método Migrate().Do this using the Migrate() method.

Este método se basa en el servicio IMigrator, que se puede usar para escenarios más avanzados.This method builds on top of the IMigrator service, which can be used for more advanced scenarios. Use DbContext.GetService<IMigrator>() para acceder a él.Use DbContext.GetService<IMigrator>() to access it.

myDbContext.Database.Migrate();

Advertencia

  • Este método no es para todos.This approach isn't for everyone. Aunque es excelente para las aplicaciones con una base de datos local, la mayoría de las aplicaciones necesitan estrategias de implementación más sólidas, como la generación de scripts SQL.While it's great for apps with a local database, most applications will require more robust deployment strategy like generating SQL scripts.
  • No llame a EnsureCreated() antes de Migrate().Don't call EnsureCreated() before Migrate(). EnsureCreated() omite las migraciones para crear el esquema, lo cual provoca un error de Migrate().EnsureCreated() bypasses Migrations to create the schema, which causes Migrate() to fail.

Pasos siguientesNext steps

Para obtener más información, vea Referencia sobre las herramientas de Entity Framework Core (EF Core).For more information, see Referencia sobre las herramientas de Entity Framework Core (EF Core).