MigraçõesMigrations

Um modelo de dados muda durante o desenvolvimento e fica fora de sincronia com o banco de dados.A data model changes during development and gets out of sync with the database. Você pode descartar o banco de dados e permitir que o EF crie um novo que corresponda ao modelo, mas esse procedimento resulta na perda de dados.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. O recurso de migrações no EF Core oferece uma maneira de atualizar de forma incremental o esquema de banco de dados para mantê-lo em sincronia com o modelo de dados do aplicativo, preservando os dados existentes no banco de dados.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.

As migrações incluem ferramentas de linha de comando e APIs que ajudam com as seguintes tarefas:Migrations includes command-line tools and APIs that help with the following tasks:

Dica

Se DbContext está em um assembly diferente do projeto de inicialização, você pode especificar explicitamente o destino e os projetos de inicialização nas ferramentas do Console do Gerenciador de Pacotes ou nas ferramentas da CLI do .NET Core.If the DbContext is in a different assembly than the startup project, you can explicitly specify the target and startup projects in either the Package Manager Console tools or the .NET Core CLI tools.

Instalar as ferramentasInstall the tools

Instale as ferramentas de linha de comando:Install the command-line tools:

Criar uma migraçãoCreate a migration

Depois de ter definido seu modelo inicial, é hora de criar o banco de dados.After you've defined your initial model, it's time to create the database. Execute o comando a seguir para adicionar uma migração inicial.To add an initial migration, run the following command.

dotnet ef migrations add InitialCreate

Três arquivos são adicionados ao seu projeto no diretório Migrações:Three files are added to your project under the Migrations directory:

  • XXXXXXXXXXXXXX_InitialCreate.cs– o arquivo principal de migrações.XXXXXXXXXXXXXX_InitialCreate.cs--The main migrations file. Contém as operações necessárias para aplicar a migração (em Up()) e revertê-la (em Down()).Contains the operations necessary to apply the migration (in Up()) and to revert it (in Down()).
  • XXXXXXXXXXXXXX_InitialCreate.Designer.cs– o arquivo de metadados de migrações.XXXXXXXXXXXXXX_InitialCreate.Designer.cs--The migrations metadata file. Contém informações usadas pelo EF.Contains information used by EF.
  • MyContextModelSnapshot.cs– um instantâneo do seu modelo atual.MyContextModelSnapshot.cs--A snapshot of your current model. Usado para determinar o que mudou ao adicionar a próxima migração.Used to determine what changed when adding the next migration.

O carimbo de data/hora no nome de arquivo ajuda a mantê-lo organizado por ordem cronológica para que você possa ver o andamento das alterações.The timestamp in the filename helps keep them ordered chronologically so you can see the progression of changes.

Dica

Você é livre para mover os arquivos de Migrações e alterar o namespace deles.You are free to move Migrations files and change their namespace. Novas migrações são criadas como irmãs da última migração.New migrations are created as siblings of the last migration.

Atualizar o banco de dadosUpdate the database

Em seguida, aplique a migração ao banco de dados para criar o esquema.Next, apply the migration to the database to create the schema.

dotnet ef database update

Personalizar o código de migraçãoCustomize migration code

Após fazer alterações no modelo do EF Core, o esquema de banco de dados pode ficar fora de sincronia. Para atualizá-las, adicione outra migração.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. O nome da migração pode ser usado como uma mensagem de confirmação em um sistema de controle de versão.The migration name can be used like a commit message in a version control system. Por exemplo, é possível escolher um nome como AddProductReviews caso a alteração seja uma nova classe de entidade para revisões.For example, you might choose a name like AddProductReviews if the change is a new entity class for reviews.

dotnet ef migrations add AddProductReviews

Depois que o scaffolding for aplicado à migração (codificado para ela), examine a precisão do código e adicione, remova ou modifique quaisquer operações necessárias para a correta aplicação.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 exemplo, uma migração poderia conter as seguintes operações: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);

Embora essas operações tornem o esquema de banco de dados compatível, elas não preservam os nomes de cliente existentes.While these operations make the database schema compatible, they don't preserve the existing customer names. Para torná-las melhor, regrave-as da seguinte maneira.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");

Dica

O processo de scaffolding da migração avisa quando uma operação puder resultar em perda de dados (como o descarte de uma coluna).The migration scaffolding process warns when an operation might result in data loss (like dropping a column). Caso veja esse aviso, não deixe de examinar a precisão do código de migrações.If you see that warning, be especially sure to review the migrations code for accuracy.

Aplique a migração ao banco de dados usando o comando apropriado.Apply the migration to the database using the appropriate command.

dotnet ef database update

Migrações vaziasEmpty migrations

Às vezes é útil adicionar uma migração sem fazer nenhuma alteração ao modelo.Sometimes it's useful to add a migration without making any model changes. Neste caso, adicionar uma nova migração cria arquivos de código com classes vazias.In this case, adding a new migration creates code files with empty classes. Você pode personalizar essa migração para executar operações que não estejam diretamente relacionadas ao modelo EF Core.You can customize this migration to perform operations that don't directly relate to the EF Core model. Alguns elementos que talvez você queira gerenciar assim são:Some things you might want to manage this way are:

  • Pesquisa de texto completoFull-Text Search
  • FunçõesFunctions
  • Procedimentos armazenadosStored procedures
  • GatilhosTriggers
  • ExibiçõesViews

Remover uma migraçãoRemove a migration

Às vezes, você adiciona uma migração e percebe que precisa fazer alterações adicionais ao modelo do EF Core antes de aplicá-lo.Sometimes you add a migration and realize you need to make additional changes to your EF Core model before applying it. Para remover a última migração, use este comando.To remove the last migration, use this command.

dotnet ef migrations remove

Após remover a migração, você poderá fazer as alterações adicionais ao modelo e adicioná-la novamente.After removing the migration, you can make the additional model changes and add it again.

Reverter uma migraçãoRevert a migration

Se você já tiver aplicado uma migração (ou várias migrações) no banco de dados, mas precisar revertê-la, poderá usar o mesmo comando usado para aplicar as migrações, mas especificando o nome da migração para a qual você deseja reverter.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.

dotnet ef database update LastGoodMigration

Gerar scripts SQLGenerate SQL scripts

Ao depurar suas migrações ou implantá-las em um banco de dados de produção, é útil gerar um script SQL.When debugging your migrations or deploying them to a production database, it's useful to generate a SQL script. O script então pode ser verificado em mais detalhes quanto à precisão e ajustado para atender às necessidades de um banco de dados de produção.The script can then be further reviewed for accuracy and tuned to fit the needs of a production database. O script também pode ser usado em conjunto com uma tecnologia de implantação.The script can also be used in conjunction with a deployment technology. O comando básico é o seguinte.The basic command is as follows.

dotnet ef migrations script

Há várias opções para este comando.There are several options to this command.

A migração de deve ser a última migração aplicada ao banco de dados antes de executar o script.The from migration should be the last migration applied to the database before running the script. Se nenhuma migração tiver sido aplicada, especifique 0 (esse é o padrão).If no migrations have been applied, specify 0 (this is the default).

A migração para é a última migração que será aplicada ao banco de dados após a execução do script.The to migration is the last migration that will be applied to the database after running the script. O padrão é a última migração em seu projeto.This defaults to the last migration in your project.

Um script idempotente pode ser gerado como opção.An idempotent script can optionally be generated. Esse script aplicará migrações somente se elas ainda não tiverem sido aplicadas ao banco de dados.This script only applies migrations if they haven't already been applied to the database. Isso é útil se você não souber exatamente qual foi a última migração aplicada ao banco de dados ou estiver implantando em vários bancos de dados que podem estar, cada um, em uma migração diferente.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 migrações em runtimeApply migrations at runtime

Alguns aplicativos talvez queiram aplicar migrações no runtime durante a inicialização ou a primeira execução.Some apps may want to apply migrations at runtime during startup or first run. Faça isso usando o método Migrate().Do this using the Migrate() method.

Este método é criado sobre o serviço IMigrator, que pode ser usado em cenários mais avançados.This method builds on top of the IMigrator service, which can be used for more advanced scenarios. Use myDbContext.GetInfrastructure().GetService<IMigrator>() para acessá-lo.Use myDbContext.GetInfrastructure().GetService<IMigrator>() to access it.

myDbContext.Database.Migrate();

Aviso

  • Esta abordagem não é para todo mundo.This approach isn't for everyone. Embora seja ótimo para aplicativos com um banco de dados local, a maioria dos aplicativos exigirá uma estratégia de implantação mais robusta, como gerar scripts SQL.While it's great for apps with a local database, most applications will require more robust deployment strategy like generating SQL scripts.
  • Não chame EnsureCreated() antes de Migrate().Don't call EnsureCreated() before Migrate(). O EnsureCreated() ignora as Migrações para criar o esquema e causa falha no Migrate().EnsureCreated() bypasses Migrations to create the schema, which causes Migrate() to fail.

Próximas etapasNext steps

Para obter mais informações, consulte Referência de ferramentas do Entity Framework Core – EF Core.For more information, see Referência de ferramentas do Entity Framework Core – EF Core.