Compartilhar via

Portar do EF6 para EF Core

  • Artigo

O Entity Framework Core ou, abreviadamente, EF Core, é uma reescrita total do Entity Framework para arquiteturas de aplicativos modernas. Devido a alterações fundamentais, não há um caminho direto de atualização. A finalidade desta documentação é fornecer um guia de ponta a ponta para portar seus aplicativos EF6 para o EF Core.

Importante

Antes de você começar o processo de portabilidade, é importante validar se o EF Core atende aos requisitos de acesso a dados do seu aplicativo. Você pode encontrar tudo do que precisa na documentação do EF Core.

Importante

Há um problema conhecido (microsoft/dotnet-apiport #993) com o analisador de portabilidade, que relata erroneamente o EF Core como incompatível com o .NET 5 e .NET 6. Esses avisos podem ser ignorados com segurança, pois o EF Core é 100% compatível com estruturas de destino .NET 5 e .NET 6.

Motivos para atualizar

Todo o novo desenvolvimento do Entity Framework está ocorrendo no EF Core. Não há planos para fazer o backport de novos recursos para o EF6. O EF Core é executado nos runtimes mais recentes do .NET e aproveita ao máximo o runtime, a plataforma específica (como ASP.NET Core ou WPF) e os recursos específicos da linguagem. Eis alguns dos benefícios obtidos com a atualização:

  • Aproveite as melhorias de desempenho contínuas no EF Core. Por exemplo, um cliente que tenha migrado do EF6 para o EF Core 6 viu uma redução de 40x no uso de uma consulta pesada devido ao recurso de divisão de consulta. Muitos clientes relatam enormes ganhos de desempenho simplesmente por migrarem para o EF Core mais recente.
  • Use novos recursos no EF Core. Não haverá novos recursos adicionados ao EF6. Todas as novas funcionalidades, por exemplo, o provedor do Azure Cosmos DB e DbContextFactory, serão adicionadas apenas ao EF Core. Para obter uma comparação completa do EF6 com o EF Core, incluindo vários recursos exclusivos do EF Core, confira: Comparar o EF Core com o EF6.
  • Modernize sua pilha de aplicativos usando a injeção de dependência e integre perfeitamente seu acesso a dados com tecnologias como gRPC e GraphQL.

Uma observação sobre migrações

Esta documentação usa os termos porta e atualização para evitar confusão com o termo migrações como um recurso do EF Core. As migrações no EF Core não são compatíveis com as migrações do EF6 Code First devido a melhorias significativas na forma como as migrações são tratadas. Não há uma abordagem recomendada para portar o histórico de migrações, portanto, planeje iniciar “do zero” no EF Core. Você pode manter a base de código e os dados das migrações do EF6. Aplique sua migração final no EF6 e crie uma migração inicial no EF Core. Você poderá acompanhar o histórico no EF Core ao seguir em frente.

Etapas de atualização

O caminho de atualização foi dividido em vários documentos que estão organizados pela fase da atualização e pelo tipo de aplicativo.

Determinar a “variante” do EF Core

Há várias abordagens sobre como o EF Core funciona com o modelo de domínio e a implementação do banco de dados. Em geral, a maioria dos aplicativos seguirá um desses padrões, e a forma como você aborda sua porta dependerá da “variante” do aplicativo.

O código como fonte de verdade é uma abordagem na qual tudo é modelado por meio de códigos e classes, seja por meio de atributos de dados, configuração fluente ou uma combinação de ambos. O banco de dados é inicialmente gerado com base no modelo definido no EF Core, e as atualizações adicionais normalmente são tratadas por meio de migrações. Isso geralmente é chamado de “code first”, mas o nome não é totalmente preciso porque uma das abordagens é começar com um banco de dados existente, gerar suas entidades e depois manter com o código ao seguir em frente.

A abordagem Banco de dados como fonte de verdade envolve a engenharia reversa ou o scaffolding do código do banco de dados. Quando as alterações de esquema são feitas, o código é regenerado ou atualizado para refletir as alterações. Isso geralmente é chamado de “database first”.

Por fim, uma abordagem de Mapeamento híbrido mais avançada segue a filosofia de que o código e o banco de dados são gerenciados separadamente, e o EF Core é usado para mapear entre os dois. Essa abordagem normalmente evita migrações.

A tabela a seguir resume algumas diferenças de alto nível:

Abordagem Função de desenvolvedor Função DBA Migrações Scaffolding Repo
Code First Criar entidades e verificar/personalizar migrações geradas Verificar definições e alterações de esquema Por confirmação N/D Controlar entidades, DbContext e migrações
Database First Engenharia reversa após alterações e verificar entidades geradas Informar os desenvolvedores quando o banco de dados for alterado para re-scaffold N/D Por alteração de esquema Acompanhar extensões/classes parciais que estendem as entidades geradas
Híbridos Atualizar a configuração fluente para mapear sempre que as entidades ou o banco de dados forem alterados Informar os desenvolvedores quando o banco de dados tiver sido alterado para que eles possam atualizar entidades e configuração de modelo N/D N/D Acompanhar entidades e DbContext

A abordagem híbrida é uma abordagem mais avançada com sobrecarga adicional em comparação às abordagens tradicionais de código e banco de dados.

Entender o impacto do afastamento do EDMX

O EF6 deu suporte a um formato de definição de modelo especial chamado EDMX (Modelo de Dados de Entidade XML). Os arquivos EDMX contêm várias definições, incluindo CSDL (definições de esquema conceitual), MSL (especificações de mapeamento) e SSDL (definições de esquema de armazenamento). O EF Core acompanha os esquemas de domínio, mapeamento e banco de dados por meio de grafos de modelo internos e não dá suporte ao formato EDMX. Muitas postagens e artigos de blog afirmam erroneamente que isso significa que o EF Core só dá suporte a "Code First". O EF Core dá suporte a todos os três modelos de aplicativo descritos na seção anterior. Você pode recompilar o modelo no EF Core fazendo a engenharia reversa do banco de dados. Caso use o EDMX para uma representação visual do modelo de entidade, cogite usar as EF Core Power Tools de código aberto que fornecem recursos semelhantes para o EF Core.

Para obter mais informações sobre o impacto da falta de suporte para arquivos EDMX, leia o guia Porte do EDMX.

Executar as etapas de atualização

Não é um requisito portar o aplicativo inteiro. O EF6 e o EF Core podem ser executados no mesmo aplicativo (confira: Usar o EF Core e o EF6 no mesmo aplicativo). Para minimizar o risco, você pode cogitar:

  1. Ir para o EF6 no .NET Core caso ainda não tenha feito isso.
  2. Migrar uma pequena parte do seu aplicativo para o EF Core e executá-lo lado a lado com o EF6.
  3. Eventualmente, traga o restante da base de código para o EF Core e desative o código EF6.

Quanto ao porte em si, em um alto nível, você vai:

  1. Examinar as alterações de comportamento entre o EF6 e o EF Core.
  2. Executar suas migrações finais, se houver, no EF6.
  3. Criar seu projeto do EF Core.
  4. Copiar o código para o novo projeto, executar a engenharia reversa ou fazer uma combinação de ambos.
  5. Renomear referências e entidades e atualizar comportamentos:
    • System.Data.Entity em Microsoft.EntityFrameworkCore
    • Alterar o construtor DbContext para consumir opções e/ou substituir OnConfiguring
    • DbModelBuilder em ModelBuilder
    • Renomear DbEntityEntry<T> como EntityEntry<T>
    • Mover de Database.Log para Microsoft.Extensions.Logging APIs (avançadas) ou DbContextOptionsBuilder.LogTo (simples)
    • Aplicar alterações em WithRequired e WithOptional (confira aqui)
    • Atualizar código de validação. Não há nenhuma validação de dados interna no EF Core, mas você pode fazer isso por conta própria.
    • Siga as etapas necessárias para portar a partir do EDMX.
  6. Executar etapas específicas com base em sua abordagem do EF Core:

Há muitas considerações relacionadas a todas as abordagens, portanto, você também vai querer examinar formas de abordar e contornar as diferenças detalhadas entre o EF6 e o EF Core.