Partilhar via

Managing Migrations

À medida que o modelo muda, as migrações são adicionadas e removidas como parte do desenvolvimento normal, e os arquivos de migração são verificados no controle do código-fonte do projeto. Para gerenciar migrações, você deve primeiro instalar as ferramentas de linha de comando EF Core.

Tip

Se o DbContext estiver em um assembly diferente do projeto de inicialização, você poderá especificar explicitamente os projetos de destino e inicialização nas ferramentas do Console do Gerenciador de Pacotes ou nas ferramentas da CLI do .NET.

Adicionar uma migração

Depois que o modelo for alterado, você poderá adicionar uma migração para essa alteração:

dotnet ef migrations add AddBlogCreatedTimestamp

O nome da migração pode ser usado como uma mensagem de confirmação em um sistema de controle de versão. Por exemplo, você pode escolher um nome como AddBlogCreatedTimestamp se a alteração for uma nova propriedade CreatedTimestamp em sua entidade Blog.

Três ficheiros são adicionados ao seu projeto no diretório Migrations:

  • XXXXXXXXXXXXXX_AddBlogCreatedTimestamp.cs--O arquivo de migrações principal. Contém as operações necessárias para aplicar a migração (em Up) e para revertê-la (em Down).
  • XXXXXXXXXXXXXX_AddBlogCreatedTimestamp.Designer.cs--O arquivo de metadados de migrações. Contém informações usadas pela EF.
  • MyContextModelSnapshot.cs--Um instantâneo do seu modelo atual. Usado para determinar o que mudou ao adicionar a próxima migração.

O carimbo de data/hora no nome do arquivo ajuda a mantê-los ordenados cronologicamente para que você possa ver a progressão das alterações.

Namespaces

Você é livre para mover arquivos de migração e alterar seu namespace manualmente. Novas migrações são criadas como paralelas à última migração. Como alternativa, você pode especificar o diretório no momento da geração da seguinte maneira:

dotnet ef migrations add InitialCreate --output-dir Your/Directory

Note

Você também pode alterar o namespace independentemente do diretório usando --namespace.

Personalizar o código de migração

Embora o EF Core geralmente crie migrações precisas, você deve sempre revisar o código e verificar se ele corresponde à alteração desejada; Em alguns casos, é mesmo necessário fazê-lo.

Column renames

Um exemplo notável em que a personalização de migrações é necessária é ao renomear uma propriedade. Por exemplo, se você renomear uma propriedade de Name para FullName, o EF Core gerará a seguinte migração:

migrationBuilder.DropColumn(
    name: "Name",
    table: "Customers");

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

O EF Core geralmente não consegue saber quando a intenção é soltar uma coluna e criar uma nova (duas alterações separadas) e quando uma coluna deve ser renomeada. Se a migração acima for aplicada as-is, todos os nomes dos seus clientes serão perdidos. Para renomear uma coluna, substitua a migração gerada acima pelo seguinte:

migrationBuilder.RenameColumn(
    name: "Name",
    table: "Customers",
    newName: "FullName");

Tip

O processo de scaffolding de migração avisa quando uma operação pode resultar em perda de dados (como eliminar uma coluna). Se vir esse aviso, certifique-se especialmente de revisar o código de migrações para garantir precisão.

Adicionando SQL bruto

Embora a renomeação de uma coluna possa ser obtida por meio de uma API interna, em muitos casos isso não é possível. Por exemplo, podemos querer substituir FirstName e propriedades LastName existentes por uma única e nova propriedade FullName. A migração gerada pelo EF Core será a seguinte:

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

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

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

Como antes, isso causaria perda de dados indesejados. Para transferir os dados das colunas antigas, reorganizamos as migrações e introduzimos uma operação SQL bruta da seguinte maneira:

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

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

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

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

Alterações arbitrárias via SQL bruto

O SQL bruto também pode ser usado para gerenciar objetos de banco de dados dos quais o EF Core não está ciente. Para fazer isso, adicione uma migração sem fazer nenhuma alteração de modelo; uma migração vazia será gerada, que você poderá preencher com operações SQL brutas.

Por exemplo, a migração a seguir cria um procedimento armazenado do SQL Server:

migrationBuilder.Sql(
@"
    EXEC ('CREATE PROCEDURE getFullName
        @LastName nvarchar(50),
        @FirstName nvarchar(50)
    AS
        RETURN @LastName + @FirstName;')");

Tip

EXEC é usado quando uma instrução deve ser a primeira ou a única em um lote SQL. Pode também ser usado para contornar erros de parser em scripts de migração idempotentes que podem ocorrer quando as colunas referenciadas não existem presentemente numa tabela.

Isso pode ser usado para gerenciar qualquer aspeto do seu banco de dados, incluindo:

  • Stored procedures
  • Full-Text Search
  • Funções
  • Triggers
  • Views

Na maioria dos casos, o EF Core encapsulará automaticamente cada migração em sua própria transação ao aplicar migrações. Infelizmente, algumas operações de migração não podem ser executadas dentro de uma transação em alguns bancos de dados; Para estes casos, pode optar por não participar na transação passando suppressTransaction: true para migrationBuilder.Sql.

Remover uma migração

Às vezes, você adiciona uma migração e percebe que precisa fazer alterações adicionais no seu modelo EF Core antes de aplicá-lo. Para remover a última migração, use este comando.

dotnet ef migrations remove

Depois de remover a migração, você pode fazer as alterações adicionais do modelo e adicioná-lo novamente.

Warning

Evite remover quaisquer migrações que já tenham sido aplicadas a bancos de dados de produção. Isso significa que você não poderá reverter essas migrações dos bancos de dados e poderá quebrar as suposições feitas pelas migrações subsequentes.

Listing migrations

Você pode listar todas as migrações existentes da seguinte maneira:

dotnet ef migrations list

Verificação de alterações pendentes no modelo

Note

Esse recurso foi adicionado ao EF Core 8.0.

Às vezes, você pode querer verificar se houve alguma alteração de modelo feita desde a última migração. Isso pode ajudá-lo a saber quando você ou um colega de equipe esqueceu de adicionar uma migração. Uma maneira de fazer isso é usando esse comando.

dotnet ef migrations has-pending-model-changes

Você também pode executar essa verificação programaticamente usando context.Database.HasPendingModelChanges(). Isso pode ser usado para escrever um teste de unidade que falha quando você se esquece de adicionar uma migração.

Redefinição de todas as migrações

Em alguns casos extremos, pode ser necessário remover todas as migrações e começar de novo. Isso pode ser feito facilmente excluindo sua pasta Migrações e descartando seu banco de dados; Nesse ponto, você pode criar uma nova migração inicial, que conterá todo o esquema atual.

Também é possível redefinir todas as migrações e criar uma única sem perder seus dados. Isso às vezes é chamado de "esmagamento", e envolve algum trabalho manual:

  1. Faça backup do seu banco de dados, caso algo dê errado.
  2. No banco de dados, exclua todas as linhas da tabela de histórico de migrações (por exemplo, DELETE FROM [__EFMigrationsHistory] no SQL Server).
  3. Exclua a sua pasta Migrações.
  4. Crie uma nova migração e gere um script SQL para ela (dotnet ef migrations script).
  5. Insira uma única linha no histórico de migrações, para registrar que a primeira migração já foi aplicada, uma vez que suas tabelas já estão lá. A inserção SQL é a última operação no script SQL gerado acima e é semelhante à seguinte (não se esqueça de atualizar os valores):
INSERT INTO [__EFMigrationsHistory] ([MIGRATIONID], [PRODUCTVERSION])
VALUES (N'<full_migration_timestamp_and_name>', N'<EF_version>');

Warning

Qualquer de código de migração personalizado será perdida quando a pasta Migrações for excluída. Todas as personalizações devem ser aplicadas manualmente à nova migração inicial para serem preservadas.

Additional resources

  • Last updated on