11. Entity Framework Core
O capítulo anterior mostrou como uma aplicação .NET se comunica com um banco de dados por meio de um conector ADO.NET: uma conexão é aberta, comandos SQL são escritos, as linhas do resultado são lidas coluna a coluna e copiadas para objetos. Esse processo de cópia — das linhas para os objetos e dos objetos para os comandos [INSERT], [UPDATE] e [DELETE] — é repetitivo. Ele pode ser automatizado por uma ferramenta: um ORM (Object-Relational Mapper). Este capítulo apresenta o Entity Framework Core (EF Core) da Microsoft.
O curso de 2008 não mencionava ORM: apenas citava, na conclusão de seu capítulo sobre bancos de dados, os "frameworks de acesso a dados de terceiros" (NHibernate, iBatis) e o LINQ. O Entity Framework foi lançado alguns meses depois (em 2008, com o .NET 3.5 SP1), e em 2012 o autor dedicou um curso a ele, intitulado "Introdução ao Entity Framework 5 Code First por meio de exemplos". Este capítulo é inteiramente novo. Ele se baseia no banco de dados de exemplo dos artigos do Capítulo 10 e termina com a versão 7 da aplicação de cálculo de impostos, cuja camada [dao] usa o EF Core.
11.1. O que é um ORM?
11.1.1. Objetos e tabelas
Uma aplicação C# trabalha com objetos: um item tem um nome, um preço e um nível de estoque; um pedido tem um cliente e uma lista de linhas, cada uma das quais se refere a um item. Um banco de dados relacional armazena essas mesmas informações em tabelas: uma linha na tabela [articles] por item, uma linha na tabela [orders] por pedido, com os relacionamentos entre as linhas expressos por chaves estrangeiras. Os dois mundos não se alinham perfeitamente:
- um objeto referencia diretamente outros objetos ([order.Client]); uma linha contém o valor da chave primária de outra linha ([ClientId]);
- um objeto pode conter uma coleção ([order.Lines]); uma tabela contém apenas valores simples; a coleção é representada pelas linhas de outra tabela que apontam para o pedido;
- os tipos C# ([string], [decimal], [DateOnly], [bool]) e os tipos SQL ([varchar(30)], [decimal(10,2)], [date], [tinyint(1)]) não são os mesmos;
- os objetos são consultados com C# (e LINQ), e as tabelas são consultadas com SQL.
Um ORM faz a ponte entre os dois mundos. Definimos de uma vez por todas o mapeamento entre classes e tabelas (o modelo); o ORM então se encarrega de:
- traduzir as consultas LINQ escritas em C# em comandos SQL [SELECT];
- criar objetos a partir das linhas lidas (isso se chama materialização);
- armazenar os objetos lidos e detectar os que foram modificados, adicionados ou excluídos;
- gerar os comandos [INSERT], [UPDATE] e [DELETE] que refletem essas mudanças no banco de dados;
- e, se necessário, criar e atualizar o esquema do banco de dados (tabelas, colunas, índices) a partir das classes.
A arquitetura de uma aplicação que usa o EF Core com o MySQL é a seguinte:

- [1]: a aplicação. Sua camada [dao] não se comunica mais com um conector ADO.NET, mas com o EF Core, por meio de um objeto [DbContext] e de consultas LINQ;
- [2]: o EF Core, independente do SGBD: modelo, tradução das consultas LINQ, rastreamento de alterações, migrações;
- [3]: o provider do EF Core específico do SGBD (aqui o Pomelo para MySQL): ele reconhece o dialeto SQL do SGBD e seus tipos de coluna;
- [4]: o conector ADO.NET do SGBD, o do Capítulo 10 (MySqlConnector): o EF Core não substitui o ADO.NET; ele o utiliza;
- [5]: o SGBD.
11.1.2. EF Core e Entity Framework 6
Há dois produtos chamados Entity Framework:
- Entity Framework 6 (EF 6), o produto original, projetado para o .NET Framework no Windows (desde a versão 6.3, também funciona no .NET Core e em seus sucessores). Ainda é mantido, mas não está mais em desenvolvimento ativo;
- Entity Framework Core, uma reescrita completa lançada em 2016 com o .NET Core. Ele roda em todas as plataformas .NET (Windows, Linux, macOS) e é a versão que recebe todos os novos recursos. Seu número de versão acompanha o do .NET: EF Core 8 com .NET 8, EF Core 9 com .NET 9, EF Core 10 com .NET 10.
Para uma nova aplicação, usamos o EF Core. Os dois produtos têm APIs semelhantes ([DbContext], [DbSet<T>], LINQ, migrações), portanto o que é exposto aqui continua em grande parte válido para o EF 6.
11.1.3. Providers
O EF Core acessa um SGBD por meio de um provider, distribuído em um pacote NuGet. A Microsoft fornece os providers para SQL Server, SQLite e Azure Cosmos DB; os demais são escritos pelos fabricantes dos SGBDs ou pela comunidade: [Npgsql.EntityFrameworkCore.PostgreSQL] para PostgreSQL, [Oracle.EntityFrameworkCore] para Oracle, [Pomelo.EntityFrameworkCore.MySql] e [MySql.EntityFrameworkCore] (da Oracle) para MySQL. Usamos o Pomelo, o provider MySQL mais utilizado, que se baseia no conector [MySqlConnector] do Capítulo 10.
Um provider é compilado para uma versão específica do EF Core: o Pomelo 9 funciona com o EF Core 9, e as versões do Pomelo costumam ser lançadas vários meses depois das do EF Core. O curso usa EF Core 9.0.0 e Pomelo 9.0.0, no .NET 10. Essa combinação funciona: o EF Core 9 tem como alvo o .NET 8 ([net8.0]), e uma biblioteca compilada para o .NET 8 funciona sem modificação no .NET 10. A transição para o EF Core 10 será feita alterando os números de versão dos pacotes; o código deste capítulo deverá então funcionar sem modificação, exceto por alguns pequenos detalhes no SQL gerado. No entanto, na seção sobre LINQ, encontraremos uma pequena incompatibilidade entre o EF Core 9 e o compilador C# 14.
Os pacotes usados neste capítulo são os seguintes:
Pacote | Função |
[Microsoft.EntityFrameworkCore] 9.0.0 | O próprio EF Core |
[Pomelo.EntityFrameworkCore.MySql] 9.0.0 | O provider MySQL; inclui [Microsoft.EntityFrameworkCore.Relational] e [MySqlConnector] |
[Microsoft.EntityFrameworkCore.Design] 9.0.0 | o código usado pela ferramenta de linha de comando [dotnet ef] (migrações) |
ferramenta [dotnet-ef] 9.0.0 | a ferramenta de linha de comando [dotnet ef] |
A ferramenta [dotnet ef] é instalada uma única vez na máquina de desenvolvimento:
As ferramentas "globais" do .NET são instaladas na pasta [.dotnet/tools] dentro do diretório pessoal do usuário, que o instalador do SDK adiciona ao caminho de executáveis (no Linux, você mesmo deve adicioná-la: [export PATH=$PATH:$HOME/.dotnet/tools]).
11.1.4. Code First e Database First
O modelo do EF Core (o mapeamento entre classes e tabelas) pode ser construído de duas maneiras:
- Code First: você escreve as classes C#, e o EF Core deriva delas o esquema do banco de dados, que ele pode criar sozinho e depois atualizar conforme a aplicação evolui (migrações). Essa é a abordagem adotada neste capítulo e no curso de 2012 do autor;
- Database First: o banco de dados já existe, e você gera as classes a partir de seu esquema com o comando [dotnet ef dbcontext scaffold]. Essa é a abordagem usada em aplicações que precisam trabalhar com um banco de dados existente. O código gerado é semelhante ao que escreveríamos à mão.
11.2. Um primeiro exemplo
11.2.1. O projeto
Cada exemplo deste capítulo é um projeto de console: a ferramenta [dotnet ef], usada para as migrações, exige um arquivo de projeto [.csproj]. Os projetos estão agrupados na solução [11-efcore/11-efcore.slnx]. O primeiro, [First], é criado com os seguintes comandos:
Seu arquivo de projeto é o seguinte:
- Linhas 12–13: os dois pacotes adicionados por [dotnet add package].
O banco de dados usado é o [efarticles] no servidor MySQL local, que é o servidor Laragon (veja os apêndices). Ele não precisa existir: o EF Core o criará.
11.2.2. A entidade [Article]
Uma classe cujos objetos são armazenados em uma tabela é chamada de entidade. Nossa primeira entidade é um item de loja, como na tabela [articles] do curso de 2008, abordada no Capítulo 10:
- Linha 4: uma classe C# comum. Ela não herda de nenhuma classe do EF Core e não tem atributos; isso é chamado de POCO (Plain Old CLR Object);
- Linha 7: a propriedade [Id] será a chave primária da tabela. Isso é uma convenção do EF Core: uma propriedade chamada [Id] (ou [ArticleId], o nome da classe seguido de [Id]) é a chave primária. Como é do tipo inteiro, seus valores serão gerados pelo SGBD (coluna [AUTO_INCREMENT] do MySQL);
- linhas 9–12: cada propriedade pública de leitura/escrita se torna uma coluna com o mesmo nome. A propriedade [Name] é inicializada com uma string vazia para satisfazer o compilador (tipos anuláveis habilitados: uma propriedade do tipo [string] não deve permanecer [null]);
- linha 15: uma exibição conveniente do artigo.
11.2.3. Contexto
O acesso ao banco de dados é feito por meio de um objeto do tipo [DbContext]:
- Linha 7: a classe [DbContext] é derivada do EF Core. Um objeto [ArticlesContext] representa uma sessão de trabalho com o banco de dados: ele abre a conexão quando necessário, armazena as entidades que leu e pode salvar as alterações feitas nelas;
- Linha 10: um [DbSet<Article>] representa a tabela de artigos. É nele que as consultas LINQ são executadas e que os artigos são adicionados ou excluídos. A propriedade é definida como um membro com corpo de expressão que chama [Set<Article>()]: cada [DbSet<T>] declarado no contexto introduz o tipo [T] no modelo;
- linha 13: o método [OnConfiguring] é chamado pelo EF Core na primeira vez que o contexto é usado, para configurá-lo;
- linha 15: a cadeia de conexão, a mesma do Capítulo 10: servidor, porta, banco de dados, nome de usuário e senha (em branco para o usuário Laragon [root]);
- linha 18: o contexto usa o provider Pomelo. O segundo parâmetro especifica a versão do servidor MySQL: o SQL gerado depende dela, pois certos recursos só estão disponíveis em versões recentes. O Laragon fornece o MySQL 8; especificamos a versão 8.0.36. O Pomelo também oferece [ServerVersion.AutoDetect(connection)], que consulta o servidor para determinar sua versão. Isso é conveniente, mas gera uma conexão adicional cada vez que um contexto é configurado, e o SQL gerado passa a depender do servidor encontrado. Especificar uma versão explicitamente torna o comportamento da aplicação reproduzível;
- linha 20: o método [LogTo] instrui o EF Core a gravar seu log usando o método [Console.WriteLine]. Mantemos apenas a categoria de mensagens [DbLoggerCategory.Database.Command] — a dos comandos SQL executados — no nível [LogLevel.Information]. Sem esse filtro, o log é muito verboso. Ver o SQL enviado ao servidor é a melhor maneira de entender o que o EF Core faz: faremos isso em todos os exemplos.
11.2.4. O programa
- linha 4: cria o contexto. Uma declaração [using] (C# 8) garante que ele será liberado ([Dispose]) ao final do programa, o que fecha qualquer conexão que ele possa ter aberto;
- linha 7: [context.Database.EnsureDeleted()] exclui o banco de dados se ele existir;
- linha 8: [context.Database.EnsureCreated()] cria o banco de dados e suas tabelas a partir do esquema. Esses dois métodos são convenientes para exemplos e testes; uma aplicação real atualiza seu banco de dados por meio de migrações, que veremos adiante;
- Linhas 11–13: três artigos são adicionados ao [DbSet]. Nada foi enviado ao servidor ainda: o contexto apenas lembra que esses três objetos devem ser inseridos. Não atribuímos valor à propriedade [Id], que será gerado pelo SGBD;
- linha 15: [SaveChanges] envia ao servidor todos os comandos SQL necessários para salvar as alterações armazenadas e retorna o número de linhas afetadas;
- linha 20: uma consulta LINQ sobre [DbSet]: itens em ordem alfabética. Ela é executada pelo SGBD quando o laço [foreach] começa a percorrê-la.
Resultados:
Comentários:
- Cada comando SQL é precedido por um cabeçalho de duas linhas: o tipo de evento ([CommandExecuted]), o tempo de execução e os parâmetros do comando;
- Linha 4: [EnsureDeleted] excluiu o banco de dados, que já existia (o programa já havia sido executado);
- linhas 7–20: [EnsureCreated] criou o banco de dados, atribuiu a ele o conjunto de caracteres [utf8mb4] (o conjunto Unicode completo do MySQL) e depois criou a tabela [Articles] a partir da entidade [Article]: o nome da tabela é o da propriedade [DbSet] do contexto, as colunas têm o nome das propriedades, e a coluna [Id] é a chave primária com valor gerado ([AUTO_INCREMENT]). Todas as colunas são [NOT NULL]: os tipos [int] e [decimal] não permitem o valor [null], nem o tipo [string], já que os tipos anuláveis estão habilitados (voltaremos a isso mais adiante);
- Observe os tipos padrão: [longtext] para uma string (texto de qualquer tamanho) e [decimal(65,30)] para um [decimal] (65 dígitos, 30 deles após a vírgula decimal). Raramente são os que queremos: o parágrafo seguinte mostra como especificá-los;
- linhas 21–41: [SaveChanges] enviou um único comando contendo três comandos [INSERT] parametrizados. Cada um é seguido de um [SELECT] que lê de volta a chave primária gerada pelo MySQL ([LAST_INSERT_ID()]): o EF Core a copia para a propriedade [Id] do objeto inserido. Os valores dos parâmetros são mascarados ('?'): são dados da aplicação, que podem ser confidenciais. Durante a depuração, eles podem ser exibidos adicionando a opção [.EnableSensitiveDataLogging()] à configuração do contexto;
- Linhas 42–50: a consulta LINQ [context.Articles.OrderBy(a => a.Name)] foi traduzida em um comando [SELECT ... ORDER BY]. O EF Core criou um objeto [Article] para cada linha lida.
Não escrevemos nenhum comando SQL nem nenhum código de leitura de colunas: esse é todo o objetivo de um ORM. Vemos também que isso não elimina a necessidade de entender SQL: para determinar se o SQL gerado está correto e é eficiente, é preciso saber lê-lo.
11.3. O modelo
O EF Core constrói seu modelo a partir das entidades em três etapas:
- primeiro, aplica suas convenções;
- depois, complementa ou corrige essas convenções com as anotações (atributos) aplicadas às entidades;
- por fim, aplica a configuração escrita em C# no método [OnModelCreating] do contexto: a API fluente.
11.3.1. As convenções
Vimos o essencial delas no primeiro exemplo:
- qualquer propriedade pública com um getter [get] e um setter [set] (ou [init]) é armazenada em uma coluna de mesmo nome;
- a propriedade [Id] ou [<Entity>Id] é a chave primária; se for um inteiro, seus valores são gerados pelo SGBD;
- o nome da tabela é o da propriedade [DbSet] do contexto (ou, na falta dela, o da classe);
- uma propriedade de tipo anulável ([int?], [DateOnly?], [string?]) resulta em uma coluna [NULL]; uma propriedade de tipo não anulável ([int], [decimal], [string] quando os tipos de referência anuláveis estão habilitados) resulta em uma coluna [NOT NULL];
- uma propriedade que referencia outra entidade, ou uma coleção de entidades, define um relacionamento (veremos isso mais adiante).
11.3.2. Anotações e API fluente
O projeto [Model] define duas entidades configuradas de duas maneiras diferentes. A primeira é configurada por meio de anotações:
- linhas 1–2: os atributos usados pertencem a esses dois namespaces do .NET. Eles não são específicos do EF Core: os atributos de validação ([Required], [MaxLength]) também são usados para validar dados em formulários do ASP.NET Core;
- linha 7: o nome da tabela;
- Linhas 11–12: a chave primária não se chama [Id]; o atributo [Key] a identifica;
- linhas 15–16: uma coluna obrigatória ([Required]: [NOT NULL]) com no máximo 50 caracteres ([MaxLength(50)]: [varchar(50)]). [Required] é redundante aqui, pois o tipo não anulável [string] basta para tornar a coluna obrigatória; ele era essencial antes do C# 8;
- linhas 19–20: o tipo [string?] especifica uma descrição opcional: a coluna aceitará o valor [NULL];
- linhas 23–24: [Column] especifica o nome da coluna e seu tipo SQL: [decimal(10,2)], 10 dígitos, incluindo 2 casas decimais;
- linha 27: uma data opcional. O tipo [DateOnly] (.NET 6) representa uma data sem hora: o Pomelo o associa ao tipo SQL [date];
- linhas 30–31: [NotMapped] exclui uma propriedade do modelo. Aqui, isso é desnecessário: uma propriedade sem acessor ([set]) não é registrada. O atributo documenta a intenção.
A segunda entidade não tem atributos:
Ela é configurada no contexto pela API fluente:
- Linha 13: o banco de dados [efmodel] nunca existirá: esse contexto é usado apenas para examinar o modelo, o que não exige uma conexão (a versão do servidor é especificada explicitamente);
- linha 18: o método [OnModelCreating] recebe um objeto [ModelBuilder] usado para descrever o modelo. Ele é chamado apenas uma vez por tipo de contexto: o EF Core mantém o modelo em cache;
- linha 20: [Entity<Supplier>(...)] recebe uma lambda que configura a entidade [Supplier]. Cada método retorna o objeto de configuração, o que permite encadear as chamadas: daí o nome "API fluente";
- linha 22: o nome da tabela;
- linha 23: a chave primária é a propriedade [Number];
- linha 24: uma coluna obrigatória com no máximo 60 caracteres;
- linha 25: um índice único sobre o nome da empresa: dois fornecedores não podem ter o mesmo nome. Não existe um atributo de validação equivalente; o EF Core oferece o atributo [Index], colocado na classe, que usaremos para os itens;
- linha 26: a propriedade [Phone] é armazenada na coluna [tel];
- linha 27: a coluna [CreationDate] tem um valor padrão, calculado pelo SGBD. Em uma inserção, o EF Core não enviará um valor para essa coluna se a propriedade tiver o valor padrão de seu tipo, o que permitirá ao SGBD usar [CURRENT_TIMESTAMP].
Tudo o que as anotações fazem pode ser feito com a API fluente, e a API fluente permite ainda mais (índices, valores padrão, chaves compostas, relacionamentos complexos). As anotações têm a vantagem de colocar a configuração ao lado da propriedade; a API fluente permite que as entidades permaneçam independentes do EF Core e concentra a configuração em um único lugar. Os dois estilos costumam ser combinados: a API fluente tem precedência em caso de conflito.
O programa [Program.cs] exibe o modelo construído pelo EF Core, seguido do script SQL que criaria as tabelas:
- linha 8: a propriedade [Model] do contexto dá acesso ao modelo: suas entidades ([IEntityType]) e, para cada uma, suas propriedades ([IProperty]);
- Linha 10: [ClrType] é o tipo C# da entidade, e [GetTableName()] é o nome de sua tabela;
- Linhas 13–15: para cada propriedade, são exibidos o nome da coluna, seu tipo SQL, se ela aceita o valor [NULL], e se faz parte da chave primária;
- linha 22: [Database.GenerateCreateScript()] retorna o script SQL de criação das tabelas sem executá-lo. É o script que [EnsureCreated] executaria.
Resultados:
- Linhas 8–12: a entidade [Supplier] e suas colunas. Os tipos SQL vêm da configuração ([varchar(60)], [varchar(20)]) ou das escolhas do provider para um tipo C#: [int] para [int], [datetime(6)] (precisão de microssegundos) para [DateTime];
- linhas 2–7: a entidade [Product]. As propriedades anuláveis ([DateOnly?], [string?]) resultam em colunas [NULL]; a propriedade [PriceInclTax] não aparece no modelo;
- Linhas 16–33: o script de criação. Ele contém toda a configuração: nomes de tabelas e colunas, tipos de dados ([NOT NULL]), valores padrão, chaves primárias (com [AUTO_INCREMENT] para chaves inteiras) e índices únicos. As colunas de texto usam o conjunto de caracteres [utf8mb4].
11.3.3. Tipos anuláveis e colunas NULL
Os tipos de referência anuláveis (C# 8, habilitados por [<Nullable>enable</Nullable>] nos projetos do curso) têm impacto sobre o modelo: o EF Core lê as anotações de nulidade geradas pelo compilador. Uma propriedade [string] resulta em uma coluna [NOT NULL], e uma propriedade [string?] resulta em uma coluna [NULL]. Em um projeto em que os tipos anuláveis não estão habilitados, todas as colunas de texto aceitam [NULL], exceto as marcadas com [Required].
Portanto, é preciso escolher com cuidado o tipo de cada propriedade: ele expressa tanto uma regra do código C# ("este valor pode estar ausente") quanto uma restrição do banco de dados. Para uma propriedade obrigatória, duas notações são comuns:
A segunda é mais segura: o compilador rejeita [new Article { Price = 10 }], em que o nome foi omitido. O EF Core pode criar entidades com membros [required]: ele não passa pelo inicializador de objeto do código C#. Para as propriedades de navegação para outra entidade, que o próprio EF Core preenche, encontramos a notação [= null!]: veremos isso ao tratar dos relacionamentos.
11.4. Os exemplos seguintes: duas bibliotecas compartilhadas
Os exemplos dos parágrafos seguintes usam todos o banco de dados [efarticles] e sua tabela [articles], preenchida com os seis artigos do Capítulo 10. Em vez de repetir a entidade e o contexto em cada projeto, nós os colocamos em uma biblioteca de classes, [Articles.Data], que os projetos referenciam. Também substituímos o log do EF Core, verboso demais para nossos exemplos, por um log mais compacto, colocado em uma segunda biblioteca, [Ef.Tools].
11.4.1. O log SQL compacto
- linhas 12–15: um membro de extensão (C# 14, veja o Capítulo 4) do tipo [DbContextOptionsBuilder], o tipo do parâmetro de [OnConfiguring]. Escreveremos [options.UseMySql(...).WithSqlLog()], como se o método tivesse sido escrito pelo EF Core. Ele chama outra sobrecarga de [LogTo], que recebe duas funções: um filtro, que seleciona os eventos a registrar, e um método de exibição, que recebe o próprio evento ([EventData]) em vez de um texto pré-formatado;
- linhas 19–22: os eventos selecionados. Cada evento do EF Core tem um identificador; os das operações relacionais são constantes da classe [RelationalEventId]. Registramos os comandos SQL executados ou com falha, bem como o início, o commit e o rollback das transações;
- Linhas 27–43: cada tipo de evento corresponde a uma classe derivada de [EventData], que fornece detalhes sobre ele: [CommandExecutedEventData] contém o comando ADO.NET executado ([DbCommand], veja o Capítulo 10). A seleção é feita com um [switch] com filtragem por padrão de tipo e cláusulas [when];
- linhas 52–54: o texto do comando, linha por linha, indentado e precedido por [SQL>], com as linhas vazias removidas;
- linhas 56–60: os parâmetros do comando e seus valores. Nós os lemos diretamente do comando; portanto, nosso log sempre os exibe, ao passo que o log do EF Core os oculta por padrão. Isso é aceitável em um curso, mas não em uma aplicação de produção.
11.4.2. A entidade e o contexto dos artigos
A entidade [Article] da biblioteca [Articles.Data] usa as anotações do parágrafo anterior:
- linha 8: a tabela se chama [articles], como no Capítulo 10;
- linha 9: o atributo [Index] do EF Core (namespace [Microsoft.EntityFrameworkCore]) cria um índice único sobre a coluna [Name]: dois artigos não podem ter o mesmo nome, como no banco de dados do curso de 2008;
- linhas 16–17: um nome obrigatório de no máximo 30 caracteres. O membro é [required]: o código que cria um item deve especificar seu nome;
- linhas 20–21: um preço em [decimal(10,2)].
O contexto é o seguinte:
- linhas 10–11: a cadeia de conexão e a versão do servidor, que são públicas para que outros projetos possam usá-las;
- linha 14: um primeiro construtor, sem parâmetros: a configuração será feita por [OnConfiguring];
- linha 17: um segundo construtor, que recebe um objeto já configurado ([DbContextOptions<ArticlesContext>]) e o repassa ao construtor da classe [DbContext]. É o construtor usado pela injeção de dependência (veremos isso mais adiante);
- linha 25: [OnConfiguring] é chamado nos dois casos. [IsConfigured] verifica se o contexto recebeu uma configuração por meio de seu construtor. Se não, a configuração padrão é usada: MySQL, com o log compacto;
- linhas 33–48: um método estático que recria o banco de dados com seus seis artigos. Ele cria um contexto com uma configuração que não inclui log: não queremos ver o SQL dessa inicialização nos resultados dos exemplos. [DbContextOptionsBuilder<T>] é a versão genérica do objeto recebido por [OnConfiguring]; sua propriedade [Options] retorna a configuração construída. [AddRange] adiciona várias entidades de uma vez.
Os projetos de exemplo referenciam a biblioteca [Articles.Data], que por sua vez referencia [Ef.Tools]:
Os pacotes do EF Core e do Pomelo, referenciados por [Articles.Data], são herdados pelos projetos que a referenciam.
11.5. Operações básicas: adicionar, ler, modificar, excluir
11.5.1. O programa [Crud]
O projeto [Crud] demonstra as quatro operações básicas (CRUD: Create, Read, Update, Delete):
Resultados:
Comentários:
- Linha 10: [Find(1)] procura o registro com chave primária 1. O tipo retornado é [Article?]: [Find] retorna [null] se a chave não existir. O SQL gerado (linhas 2–7) é um [SELECT] parametrizado, limitado a uma linha;
- linha 13: a segunda chamada a [Find(1)] não envia nenhum comando SQL e retorna o mesmo objeto (linha 10). O contexto armazena as entidades que leu ou adicionou: antes de consultar o banco de dados, [Find] verifica se a entidade solicitada já está sendo rastreada. Um contexto nunca contém dois objetos para a mesma linha do banco de dados;
- Linhas 18–19: adição de um item. Antes de [SaveChanges], o item está no estado [Added] e seu valor [Id] é 0 (linha 12). [SaveChanges] envia um comando [INSERT], recupera a chave gerada e a coloca em [x.Id] (linha 21). O item passa ao estado [Unchanged]: ele é idêntico à linha do banco de dados;
- linha 26: para modificar uma linha do banco de dados, basta modificar o objeto. Nenhum método [Update] é necessário: o contexto guardou uma cópia dos valores lidos (os valores originais) e compara os valores atuais com eles. O item passa ao estado [Modified] (linha 23);
- linha 27: [context.Entry(x)] dá acesso às informações de rastreamento da entidade [x]: seu estado ([State]) e, para cada propriedade, seu valor original ([OriginalValue]) e seu valor atual ([CurrentValue]);
- Linha 29: o comando [UPDATE] gerado (linhas 25–28) modifica apenas a coluna que mudou, [Price]. Ele é seguido de um [SELECT ROW_COUNT()]: o EF Core verifica se o comando de fato modificou uma linha;
- linhas 34–36: a exclusão. [Remove] altera o estado do item para [Deleted]; [SaveChanges] envia o comando [DELETE]. O objeto deixa então de ser rastreado pelo contexto: ele está no estado [Detached];
- linhas 41–43: o objeto [context.ChangeTracker] (o "rastreamento de alterações") gerencia as entidades rastreadas. [DetectChanges] compara os valores atuais das entidades com seus valores originais (o EF Core o chama automaticamente em [SaveChanges], [Entry], e em alguns outros métodos). A propriedade [DebugView.LongView] retorna uma descrição de todas as entidades rastreadas (linhas 38–44): o contexto agora rastreia apenas a bicicleta, cujo estoque diminuiu de 10 para 9. O operador [!] em [bike!] informa ao compilador que [bike], do tipo [Article?], não é [null] aqui.
Dois detalhes do SQL gerado pelo Pomelo:
- o comando [INSERT], seguido de um [SELECT] da chave gerada, é envolvido por uma transação (linhas 13–20): o comando contém dois comandos SQL que devem ter sucesso juntos. Voltaremos às transações mais adiante;
- os comandos isolados [UPDATE] e [DELETE] não são envolvidos por uma transação. Eles são precedidos por [SET AUTOCOMMIT = 1], uma configuração de sessão do MySQL (cada comando é confirmado assim que é executado) que o provider restaura por precaução. Essa configuração não tem efeito sobre uma transação aberta explicitamente, como veremos.
11.5.2. Os estados de uma entidade
O rastreamento de alterações se baseia no estado de cada entidade, um valor da enumeração [EntityState]:
Estado | Significado |
[Detached] | O objeto não é rastreado pelo contexto (criado por [new] e ainda não adicionado, ou excluído do banco de dados) |
[Added] | O objeto foi adicionado ao contexto ([Add]): [SaveChanges] o inserirá no banco de dados |
[Unchanged] | O objeto foi lido do banco de dados (ou salvo) e não foi modificado desde então |
[Modified] | Pelo menos uma propriedade foi modificada: [SaveChanges] enviará um comando [UPDATE] |
[Deleted] | O objeto foi marcado para exclusão ([Remove]): [SaveChanges] enviará um comando [DELETE] |
Observe o ciclo de trabalho com o EF Core: as entidades são lidas, modificadas como objetos comuns, adicionadas e excluídas, e então [SaveChanges] é chamado, enviando ao banco de dados todos os comandos necessários em um único lote. O contexto funciona como uma "unidade de trabalho". Um contexto é um objeto leve, projetado para ter vida curta: uma unidade de trabalho, como uma requisição HTTP em uma aplicação web. O mesmo contexto não é usado durante toda a vida de uma aplicação, pois acumularia entidades rastreadas.
11.5.3. Atualizações em massa e leitura sem rastreamento
O rastreamento de alterações tem um custo: para aumentar o preço de 100 itens, é preciso ler os 100 itens, modificá-los um a um, e [SaveChanges] enviará 100 comandos [UPDATE]. O EF Core 7 introduziu dois métodos que enviam diretamente um comando SQL que abrange todas as linhas selecionadas por uma consulta: [ExecuteUpdate] e [ExecuteDelete]. O projeto [BulkUpdate] os descreve, bem como as operações somente leitura:
Resultados:
Comentários:
- Linhas 10–12: [ExecuteUpdate] se aplica a uma consulta ([Where]) e recebe uma lambda que descreve as colunas a modificar: [SetProperty(property, new value)]. O novo valor pode depender da própria linha ([a => a.MinimumStock * 2]). O comando SQL (linhas 3–5) é executado imediatamente, sem [SaveChanges], e retorna o número de linhas modificadas;
- linhas 16–18: um aumento de 10% nos preços baixos. Observe que as constantes do código C# ([150], [1.1M]) são escritas no texto do comando SQL ([150.0], [1.1]);
- linha 23: [ExecuteDelete] remove as linhas selecionadas pela consulta — neste caso, o arco, o único item com preço acima de 550 euros;
- linha 28: [AsNoTracking()] solicita uma leitura sem rastreamento: as entidades lidas não são armazenadas pelo contexto (linha 26). Isso é mais rápido e usa menos memória: é empregado para dados lidos sem serem modificados (exibição, cálculos). Em contrapartida, [SaveChanges] ignora as alterações feitas nessas entidades (linha 27);
- linhas 37–41: uma armadilha. [ExecuteUpdate] opera diretamente no banco de dados: ele não modifica as entidades já carregadas pelo contexto. A bicicleta rastreada pelo contexto mantém seu preço antigo (linha 37) até ser lida novamente com [context.Entry(bike).Reload()]. [Single] retorna o único elemento da consulta e lança uma exceção se houver zero ou mais de um elemento: é por isso que o SQL gerado solicita duas linhas ([LIMIT 2]).
11.6. O LINQ é traduzido em SQL
11.6.1. Consultas
O Capítulo 5 apresentou o LINQ para coleções em memória. Os mesmos operadores ([Where], [OrderBy], [Select], [First], [Count], [Sum]...) se aplicam a um [DbSet<T>], mas não são executados pelo .NET: o EF Core os traduz em SQL, e é o SGBD que os executa. O projeto [Linq] fornece vários exemplos:
Resultados:
Comentários:
- Linhas 10–13: [Where] e [OrderBy] tornam-se as cláusulas [WHERE] e [ORDER BY] (linhas 5–6). A consulta só é executada quando seus resultados são solicitados, neste caso por [ToList]: essa é a execução adiada do LINQ (Capítulo 5);
- Linhas 18–20: uma projeção. [Select] cria um objeto de tipo anônimo para cada item, contendo apenas o nome e o valor do estoque. O SQL gerado (linha 9) recupera somente as colunas relevantes e faz o próprio cálculo. Os objetos do tipo anônimo não são entidades: não são rastreados pelo contexto. O provider converte o estoque, que é um inteiro, em [decimal(65,30)] antes da multiplicação, o que explica as muitas casas decimais no resultado, que é então formatado com [{v.Value:0.00}];
- linha 30: [FirstOrDefault] torna-se [LIMIT 1]. A variável do programa [minPrice] torna-se um parâmetro do comando SQL ([@__minPrice_0], linha 21), ao passo que uma constante escrita na lambda é copiada para o texto SQL. Portanto, não há com o que se preocupar quanto a injeções de SQL: valores vindos de fora do programa são sempre passados como parâmetros. É a regra que o Capítulo 10 aplicou manualmente com consultas parametrizadas;
- linhas 35–36: os agregados [Count] e [Sum] são calculados pelo SGBD ([COUNT(*)], [SUM(...)]): apenas o resultado é transferido, não as linhas. [COALESCE(..., 0.0)] retorna 0 se a tabela estiver vazia, exatamente como o [Sum] do LINQ;
- Linhas 42–45: os métodos do .NET conhecidos pelo EF Core são traduzidos para SQL: [a.Name.StartsWith("b")] torna-se [LIKE 'b%'], e [names.Contains(a.Name)], que se refere a uma lista em memória, torna-se [IN ('bow', 'pump', 'racket')] (linha 35). Há muitos métodos traduzidos: operações sobre strings, datas e funções matemáticas;
- linhas 51–52: [ToQueryString()] retorna o texto SQL de uma consulta sem executá-la (linhas 37–41). Isso é útil para depuração;
- linhas 57–60: a paginação, para exibir uma lista longa página por página. [Skip] ignora os itens das páginas anteriores, enquanto [Take] mantém os da página solicitada: eles se tornam as cláusulas [OFFSET] e [LIMIT] (linha 46). A paginação só faz sentido em uma lista ordenada ([OrderBy]);
- linha 61: essa projeção contém uma string interpolada, que o EF Core não traduz em SQL. Isso não é um erro: quando a operação não traduzível é o [Select] final, o EF Core solicita ao SGBD as colunas necessárias ([Name] e [Price]) e executa a projeção em memória para cada linha lida. Observe que o preço é formatado de acordo com a localidade en-US, usando um ponto decimal;
- linhas 69–71: o EF Core não consegue traduzir a chamada a um método qualquer do programa: ele não conhece seu código e, mesmo que conhecesse, não saberia necessariamente escrevê-lo em SQL. A execução da consulta dispara uma [InvalidOperationException] (linhas 50–51). A mensagem (em inglês, como todas as mensagens de exceção do .NET), da qual o programa exibe apenas a primeira frase, oferece então duas soluções: reescrever a consulta ou passar explicitamente para uma avaliação em memória;
- linha 78: [AsEnumerable()] transfere a consulta de [IQueryable<T>] para [IEnumerable<T>]: a parte anterior é traduzida em SQL (aqui, a leitura da tabela inteira), e a parte seguinte é executada pelo LINQ em memória. O resultado está correto, mas a tabela inteira foi carregada: com uma tabela grande, isso deve ser evitado. É melhor escrever a condição na lambda ([a.CurrentStock < a.MinimumStock]), como mostra a linha 11.
11.6.2. IQueryable e árvores de expressão
Como a mesma lambda pode ser executada em C# sobre uma lista e traduzida em SQL sobre um [DbSet]? O Capítulo 7 deu a resposta: um [DbSet<T>] implementa a interface [IQueryable<T>], cujos métodos [Where], [OrderBy], [Select]... recebem não delegates ([Func<T, bool>]), mas árvores de expressão ([Expression<Func<T, bool>>]). O compilador transforma a lambda [a => a.CurrentStock < a.MinimumStock] em uma estrutura de dados que a descreve ("comparação [<] da propriedade [CurrentStock] e da propriedade [MinimumStock] do parâmetro [a]"); o EF Core percorre essa estrutura e produz o SQL equivalente. Um método como [Rules.OutOfStock] aparece na árvore apenas como uma chamada de método, cujo código não pode ser analisado: daí o erro.
Os operadores são compostos: uma consulta pode ser construída em etapas, com cada etapa retornando um novo [IQueryable<T>], e somente a execução final ([ToList], [First], [Count], [foreach]...) envia um comando SQL:
11.6.3. Uma incompatibilidade entre o EF Core 9 e o C# 14
No programa [Linq], a lista [names] foi declarada com o tipo [List<string>] em vez de [string[]], com um comentário referenciando este parágrafo. Com um array, a consulta [context.Articles.Where(a => names.Contains(a.Name))] compila, mas falha em tempo de execução com um erro [InvalidOperationException] ("An exception was thrown while attempting to evaluate a LINQ query parameter expression"). De fato, o C# 14 tornou a conversão de um array em [ReadOnlySpan<T>] (o tipo introduzido no Capítulo 5) uma conversão implícita da linguagem, que também se aplica ao objeto sobre o qual um método de extensão é chamado. Para um array, a chamada [names.Contains(...)] passa, portanto, a se referir ao método de extensão [MemoryExtensions.Contains(ReadOnlySpan<T>, T)] em vez de [Enumerable.Contains(IEnumerable<T>, T)]: isso fica evidente ao examinar a árvore de expressão da lambda, e o mesmo programa compilado em C# 13 ([<LangVersion>13</LangVersion>]) encontra [Enumerable.Contains] e funciona. O EF Core 9, lançado antes do C# 14, não reconhece esse método: ele tenta avaliar a conversão do array em [ReadOnlySpan<string>] para transformá-la em um parâmetro SQL, o que falha (a exceção interna é uma [ArgumentException] lançada pelo interpretador de árvores de expressão). O EF Core 10, lançado junto com o C# 14, oferece suporte a essa sintaxe. Com o EF Core 9, é possível contornar o problema usando uma lista, como feito aqui, ou escrevendo [((IEnumerable<string>)names).Contains(a.Name)]. Esse é o único problema encontrado neste capítulo ao usar o EF Core 9 com o .NET 10.
11.7. Relacionamentos
11.7.1. O modelo da loja
As tabelas de um banco de dados estão ligadas entre si. O EF Core representa essas ligações por meio de propriedades de navegação: propriedades que referenciam outra entidade ou uma coleção de entidades. O projeto [Relations] usa um banco de dados [efshop] que descreve uma pequena loja:
- um relacionamento um-para-muitos entre [Category] e [Product]: uma categoria contém vários produtos (linha 9), e um produto pertence a uma categoria (linhas 19–20). A propriedade [CategoryId] é a chave estrangeira: por convenção, o nome da propriedade de navegação seguido de [Id]. Ela é opcional no código (o EF Core a criaria na tabela se não existisse na classe), mas é conveniente: permite determinar a categoria de um produto sem carregá-la;
- um relacionamento muitos-para-muitos entre [Product] e [Tag]: um produto tem várias tags (linha 22), e uma tag está associada a vários produtos (linha 30). Não há chave estrangeira: o relacionamento será armazenado em uma tabela de associação criada pelo EF Core;
- os relacionamentos um-para-muitos [Client] - [Order] e [Order] - [OrderLine], e o relacionamento muitos-para-um [OrderLine] - [Product]: uma linha de pedido representa uma quantidade de um produto;
- as coleções são inicializadas com uma coleção vazia ([= []], uma expressão de coleção do C# 12). As propriedades de navegação que apontam para uma única entidade são inicializadas com [null!]: o valor [null], acompanhado do operador [!], que diz ao compilador para não sinalizar uma propriedade não anulável como recebendo [null]. Essa é a notação convencional para uma propriedade que o próprio EF Core preenche durante as leituras e que nunca é [null] em uma entidade corretamente carregada. Tal propriedade define um relacionamento obrigatório (chave estrangeira [NOT NULL]); uma propriedade do tipo [Category?] e uma chave do tipo [int?] definiriam um relacionamento opcional.
O contexto é o seguinte:
- linha 7: o contexto tem um construtor primário (C# 12) cujo parâmetro opcional [log] permite omitir o SQL;
- linhas 9–13: cinco [DbSet]. Uma entidade não precisa de um [DbSet] para fazer parte do modelo: [OrderLine], alcançada pela propriedade de navegação [Order.Lines], faz parte dele de fato;
- linha 19: o log compacto é adicionado se solicitado;
- linha 28: a API fluente define a precisão do preço.
As tabelas criadas por [EnsureCreated] são as seguintes:
- Linhas 5–11: uma tabela por entidade. A tabela [OrderLine] leva o nome da classe, na ausência da propriedade [DbSet]; a tabela [ProductTag] é a tabela de associação do relacionamento muitos-para-muitos;
- Linha 22: a chave estrangeira [CategoryId] na tabela [Products] referencia a tabela [Categories]. A opção [ON DELETE CASCADE] exclui os produtos de uma categoria quando a categoria é excluída: esse é o comportamento padrão do EF Core para um relacionamento obrigatório. O EF Core também cria um índice em cada chave estrangeira (linha 21);
- linhas 26–32: a tabela de associação tem duas colunas, chaves estrangeiras para as duas tabelas ligadas, que juntas formam sua chave primária;
- linha 17: não limitamos o tamanho dos nomes, daí o tipo [longtext].
11.7.2. O programa
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | |
Resultados:
Comentários:
- Linhas 13–32: três categorias são adicionadas, junto com seus produtos e as tags dos produtos: um grafo de objetos. O EF Core percorre as propriedades de navegação e adiciona ao contexto todas as entidades encontradas. [SaveChanges] as insere na ordem correta (categorias antes dos produtos que as referenciam) e preenche as chaves estrangeiras e a tabela de associação. Essa inicialização é feita sem log;
- linhas 35–36: a propriedade [Local] de um [DbSet] dá acesso às entidades já rastreadas pelo contexto, sem consultar o banco de dados;
- linhas 56–71: um cliente, seu pedido e suas duas linhas de pedido são adicionados em uma única chamada a [Add]. O SQL (linhas 11–35) mostra a ordem das inserções: o cliente, depois o pedido — cuja chave estrangeira ([ClientId]) recebe a chave gerada para o cliente ([@p1=2]) — e por fim as linhas de pedido, cuja chave estrangeira ([OrderId]) recebe a chave do pedido;
- Linhas 79–80: por padrão, o EF Core carrega apenas a entidade solicitada. As propriedades de navegação [Client] e [Lines] do pedido lido não foram preenchidas (linha 41): [Client] é igual a [null] (apesar da declaração não anulável, daí o operador [?.]), e a lista de linhas está vazia. O EF Core oferece suporte ao carregamento tardio (lazy loading): a propriedade de navegação é carregada automaticamente na primeira leitura. Ele deve ser habilitado explicitamente (pacote [Microsoft.EntityFrameworkCore.Proxies], propriedades de navegação [virtual]); não o usamos porque ele esconde os acessos ao banco de dados;
- Linhas 87–89: o carregamento antecipado (eager loading). [Include(c => c.Client)] instrui o sistema a carregar o cliente de cada pedido; [Include(c => c.Lines)] carrega as linhas do pedido, e [ThenInclude(l => l.Product)] carrega o produto de cada linha. Tudo é carregado por uma única consulta [SELECT], usando junções (linhas 45–51). A exibição mostra os dois pedidos e suas linhas;
- linha 106: o carregamento explícito. Carregamos a coleção de produtos de uma categoria que já foi lida: uma segunda consulta, [SELECT], lê os produtos cuja chave estrangeira corresponde à da categoria. Para uma propriedade de navegação para uma única entidade, escrevemos [context.Entry(product).Reference(p => p.Category).Load()];
- Linhas 114–116: as propriedades de navegação são usadas em consultas LINQ, sem [Include]: [p.Tags.Any(...)] torna-se uma subconsulta [EXISTS] sobre a tabela de associação (linhas 72–76), e [p.Category.Name] torna-se uma junção;
- linhas 125–126: um cálculo através de duas relações — o valor de cada pedido — inteiramente executado pelo SGBD por meio de uma subconsulta (linhas 81–84);
- linhas 135–138: um agrupamento. [GroupBy] agrupa os produtos pelo nome da categoria; para cada grupo ([g]), a chave ([g.Key]), o número de produtos ([Count]) e o preço médio ([Average]) são calculados pelo SGBD: a consulta torna-se um [GROUP BY] (linhas 90–93). A categoria [diving], que não tem produtos, não aparece: a junção com a tabela de categorias é uma junção interna ([INNER JOIN]).
O chamado problema das "N+1 consultas" é um risco para qualquer usuário de um ORM. Suponha que queremos exibir o nome do cliente de cada pedido e lemos os pedidos sem [Include], e depois obtemos o cliente de cada um por meio de um carregamento explícito (ou de um carregamento tardio, que dá no mesmo sem que percebamos): executamos uma consulta para os N pedidos e depois N consultas, uma por pedido. Com mil pedidos, isso resulta em mil e uma idas e vindas ao servidor, quando uma única teria bastado. As soluções são as mostradas no exemplo: [Include]ou, melhor ainda, uma projeção ([Select]) que recupera apenas os dados relevantes. O log SQL ajuda a identificar o problema: a mesma consulta repetida inúmeras vezes.
11.8. Migrações
11.8.1. O princípio
Até agora, o banco de dados foi criado por [EnsureCreated], depois de ser excluído por [EnsureDeleted]. Isso é impossível em uma aplicação em produção: seu banco de dados contém dados que devem ser preservados quando o modelo evolui (uma nova coluna, uma nova tabela). Além disso, [EnsureCreated] só pode criar um banco de dados que não existe: se o banco de dados já existe com tabelas, ele não faz nada, mesmo que o modelo tenha mudado.
As migrações atendem a essa necessidade. Uma migração é uma classe C#, gerada pela ferramenta [dotnet ef], que descreve a transição de uma versão do modelo para a seguinte: seu método [Up] aplica a mudança (criar uma tabela, adicionar uma coluna), enquanto seu método [Down] a reverte. O banco de dados contém uma tabela chamada [__EFMigrationsHistory], na qual o EF Core registra as migrações que foram aplicadas a ele; isso lhe permite saber quais ainda precisam ser aplicadas.
11.8.2. O projeto
O projeto [Clients] usa o banco de dados [efclients]. Seu arquivo de projeto adiciona o pacote [Microsoft.EntityFrameworkCore.Design], exigido pela ferramenta [dotnet ef]:
- Linhas 15–18: o elemento [PrivateAssets] ("all") indica que esse pacote se destina apenas ao desenvolvimento: ele não é distribuído aos projetos que referenciam este e não é necessário para a execução. É isso que o comando [dotnet add package Microsoft.EntityFrameworkCore.Design] produz.
A entidade é um cliente:
Na primeira versão da aplicação, o cliente não tem número de telefone: as linhas 13–14 ainda não existem. Vamos adicioná-las na segunda versão.
A ferramenta [dotnet ef] precisa ser capaz de criar um contexto para determinar o modelo e, em certos comandos, conectar-se ao banco de dados. Para isso, ela usa, em ordem: uma classe do projeto que implemente a interface [IDesignTimeDbContextFactory<T>], ou o contêiner de injeção de dependência de uma aplicação ASP.NET Core ou, na falta deles, um construtor sem parâmetros do contexto. Vamos escrever uma factory:
- linha 7: o contexto recebe sua configuração por meio de um construtor primário (C# 12), que ele repassa ao construtor de [DbContext]. Ele não tem um método [OnConfiguring]: não conhece seu banco de dados; quem o cria é que o escolhe;
- Linhas 13–21: a fábrica. Seu método [CreateDbContext] monta a configuração ([DbContextOptionsBuilder<T>]) e cria o contexto. O parâmetro [args] recebe os eventuais argumentos passados à ferramenta; não os utilizamos.
11.8.3. A primeira migração
Os comandos da ferramenta [dotnet ef] são digitados na pasta do projeto. A primeira migração, que chamamos de [Initial], é criada pelo comando [dotnet ef migrations add]:
A ferramenta compilou o projeto, criou um contexto com a fábrica, comparou o modelo com o da última migração (que ainda não existe) e gerou três arquivos em uma pasta chamada [Migrations]:
Os nomes dos arquivos começam com a data e a hora de criação da migração (ano, mês, dia, hora, minuto, segundo): as migrações são aplicadas nessa ordem. O arquivo [ClientsContextModelSnapshot.cs] contém uma descrição do modelo no estado em que ele se encontra após a última migração: a ferramenta usa esse arquivo para compará-lo com o modelo atual e gerar a próxima migração. Esses arquivos fazem parte do código-fonte da aplicação: são armazenados e gerenciados junto com o restante do código (em um repositório Git, por exemplo).
A migração gerada é a seguinte:
- linha 9: uma migração deriva da classe [Migration];
- linhas 12–32: o método [Up] descreve as operações a executar, usando um objeto [MigrationBuilder]: modificar o conjunto de caracteres do banco de dados ([AlterDatabase]), criar a tabela [Clients] ([CreateTable]) com suas colunas e sua chave primária. As anotações [MySql:...] contêm informações específicas do provider Pomelo;
- linhas 36–39: o método [Down] desfaz a migração excluindo a tabela.
O código de uma migração pode ser modificado manualmente, por exemplo, para adicionar operações que a ferramenta não consegue deduzir do modelo ([migrationBuilder.Sql("...")] executa qualquer comando SQL).
11.8.4. Aplicar uma migração
O comando [dotnet ef database update] aplica ao banco de dados todas as migrações que ainda não foram aplicadas ou, se receber o nome de uma migração, todas as migrações até ela, inclusive:
O banco de dados [efclients] não existia: ele foi criado. O cliente [mysql] do MySQL mostra suas tabelas:
Ele contém a tabela do modelo [Clients] e a tabela [__EFMigrationsHistory], que contém uma linha por migração aplicada.
11.8.5. Uma segunda migração
A aplicação evolui: a propriedade [Phone], do tipo [string?] e limitada a 20 caracteres, é adicionada à entidade [Client] (esta é a versão do arquivo [Client.cs] mostrada acima). Uma nova migração é criada:
A ferramenta comparou o modelo atual com o snapshot e gerou a seguinte migração:
- Linhas 13–18: [Up] adiciona a coluna [Phone], que é opcional, já que a propriedade é do tipo [string?]. As linhas existentes na tabela receberão o valor [NULL]. Se a propriedade fosse obrigatória ([string]), seria necessário atribuir um valor às linhas existentes: a migração o faria usando a string vazia, que é o valor padrão da coluna ([defaultValue: ""]);
- linhas 25–27: [Down] exclui a coluna.
O snapshot do modelo também foi atualizado. Estas são as principais alterações:
- linha 12: o atributo [DbContext] associa o snapshot ao contexto [ClientsContext];
- linhas 24–48: a descrição da entidade [Client], escrita com a fluent API: cada propriedade, seu tipo SQL, seu comprimento, seu caráter obrigatório ([IsRequired]), a chave primária e a tabela. A propriedade [Phone] está incluída aqui (linhas 42–44). Ao comparar esse modelo com o modelo atual no código, a ferramenta determinará as operações da próxima migração. Este arquivo nunca deve ser modificado manualmente; para desfazer a última migração (se ela não tiver sido aplicada), use [dotnet ef migrations remove], que exclui seus arquivos e restaura o snapshot ao estado anterior.
O comando [dotnet ef migrations list] lista as migrações do projeto e aquelas que ainda não foram aplicadas ao banco de dados:
O comando [dotnet ef migrations script] gera o script SQL de uma migração — ou de uma série de migrações — sem executá-lo. Ele é usado quando o banco de dados de produção não é atualizado pelo desenvolvedor, mas por um administrador que deseja revisar e executar o script SQL por conta própria:
- Linhas 4–10: a migração é executada dentro de uma transação: a modificação do esquema e a adição da migração à tabela de histórico são bem-sucedidas ou falham juntas. Atenção: no MySQL, um comando de modificação de esquema ([ALTER TABLE], [CREATE TABLE]) confirma implicitamente a transação em andamento. Se ocorrer um erro no meio de uma migração, o banco de dados pode permanecer em um estado intermediário;
- Linha 7: a migração é registrada na tabela de histórico, junto com a versão do EF Core que a aplicou.
11.8.6. Aplicando migrações a partir da aplicação
Uma aplicação também pode aplicar migrações por conta própria na inicialização. É o que faz o programa do projeto [Clients]:
- linha 5: o contexto é criado usando a fábrica fornecida pela ferramenta;
- linhas 8–9: as migrações aplicadas ao banco de dados (lidas da tabela de histórico) e aquelas que ainda restam a aplicar;
- linha 12: [Migrate] aplica as migrações pendentes (criando o banco de dados, se necessário). Equivale a [dotnet ef database update];
- Linhas 16–20: a nova coluna é utilizada.
Resultados:
A segunda migração foi aplicada pelo programa. A tabela de histórico agora contém as duas migrações:
Aplicar migrações na inicialização é conveniente para uma aplicação pequena ou durante o desenvolvimento. Para uma aplicação grande, implantada em vários servidores, é preferível aplicá-las em uma etapa separada do processo de implantação (script SQL ou executável de migração gerado por [dotnet ef migrations bundle]). Observe o seguinte:
- [EnsureCreated]: para exemplos, testes e protótipos, quando o banco de dados pode ser excluído e recriado;
- migrações: assim que o banco de dados contiver dados que precisam ser preservados. Os dois não devem ser misturados: um banco de dados criado por [EnsureCreated] não tem tabela de histórico, e não é possível aplicar migrações a ele.
11.9. Assincronia
Uma consulta ao banco de dados é uma operação de E/S: enquanto o servidor trabalha, a thread que aguarda não faz nada. O Capítulo 9 mostrou como liberar essa thread usando [async] e [await]. O EF Core oferece uma versão assíncrona de todos os métodos que acessam o banco de dados: [ToListAsync], [FirstOrDefaultAsync], [SingleAsync], [CountAsync], [SumAsync], [FindAsync], [SaveChangesAsync], etc. Eles são definidos no namespace [Microsoft.EntityFrameworkCore] (não em [System.Linq]). O projeto [Async] os utiliza:
Resultados:
Comentários:
- Linha 7: um [DbContext] implementa [IAsyncDisposable]: [await using] (C# 8, Capítulo 9) o libera de forma assíncrona;
- linha 11: [ToListAsync] executa a consulta e retorna um [Task<List<Article>>]. A consulta em si ([Where], [OrderBy]) é escrita como antes: só muda o método que a executa;
- linhas 14–15: as versões assíncronas de [FirstOrDefault] e [Count];
- linha 21: a gravação assíncrona;
- linha 26: [AsAsyncEnumerable()] retorna a consulta como um fluxo assíncrono ([IAsyncEnumerable<T>], Capítulo 9), que é percorrido com [await foreach]. As entidades são processadas à medida que são lidas, sem formar uma lista: isso é útil para processar um grande número de linhas;
- linhas 33–39: os métodos assíncronos aceitam um [CancellationToken] (Capítulo 9). Aqui, o token é cancelado antes da chamada: [ToListAsync] lança imediatamente uma [OperationCanceledException] (linha 34). Em uma aplicação web, o token da requisição HTTP é repassado: se o cliente abortar a requisição, a operação de leitura em andamento é interrompida.
Uma regra importante: um contexto não é thread-safe e aceita apenas uma operação por vez. Não dispare duas requisições simultâneas no mesmo contexto (por exemplo, com [Task.WhenAll]): é preciso aguardar ([await]) o término de uma operação antes de iniciar outra. O EF Core costuma detectar esse erro e lança uma [InvalidOperationException] (“A second operation was started on this context instance before a previous operation completed”), mas nem sempre. Para requisições realmente paralelas, usa-se um contexto por tarefa.
Em uma aplicação console como nossos exemplos, a assincronia não oferece nenhum benefício visível. Ela se torna especialmente valiosa em uma aplicação de servidor (Capítulos 12 e 13), em que uma thread liberada durante uma requisição SQL pode atender outros clientes. É por isso que as aplicações ASP.NET Core usam sistematicamente os métodos assíncronos do EF Core.
11.10. Transações e concorrência
11.10.1. Transações
O Capítulo 10 apresentou as transações: um conjunto de operações que ou são todas bem-sucedidas, ou todas falham. Com o EF Core, há dois pontos importantes a observar:
- [SaveChanges] é transacional: se envia vários comandos, ele os executa dentro de uma transação. Se um deles falhar, nenhum é confirmado, e [SaveChanges] lança uma [DbUpdateException];
- Para agrupar várias chamadas a [SaveChanges] (ou comandos como [ExecuteUpdate], [ExecuteSql]...) em uma única transação, abre-se uma transação explícita com [context.Database.BeginTransaction()] (ou sua versão assíncrona), confirma-se com [Commit] e desfaz-se com [Rollback].
O projeto [Transactions] ilustra os dois casos:
Resultados:
Comentários:
- Linhas 11–15: dois itens são adicionados, o segundo dos quais tem o mesmo nome de um item existente. [SaveChanges] abre uma transação (linha 3) e envia os dois comandos [INSERT]. O segundo viola o índice único da coluna [Name]: o MySQL rejeita a inserção, e [SaveChanges] lança uma [DbUpdateException], cuja exceção interna é o erro do SGBD (linha 15). A transação não foi confirmada: ela é abandonada, e suas operações são desfeitas pelo MySQL. A raquete, que tinha sido inserida com sucesso, não está no banco de dados (linha 21);
- linha 29: uma transação explícita. O objeto retornado ([IDbContextTransaction]) é liberado por [await using]: se ele não tiver sido confirmado, a transação sofre rollback nesse ponto;
- Linhas 33–35: o primeiro [SaveChangesAsync] registra a venda de duas bicicletas. Como já há uma transação em andamento, [SaveChanges] não inicia outra; em vez disso, ele é incluído na existente. O comando [SET AUTOCOMMIT = 1], que precede o [UPDATE] (linha 28), não confirma a transação em andamento: as linhas seguintes mostram que a venda de fato será cancelada;
- linhas 37–38: a segunda gravação falha (linhas 38–40);
- linha 40: o commit nunca é alcançado;
- linha 46: no [catch], é feito o rollback da transação (linha 41). A venda das bicicletas, embora registrada pelo primeiro [SaveChangesAsync], é cancelada: o estoque de bicicletas permanece em 10 (linha 47);
- Linhas 53–57: uma função local assíncrona que relê um item com um novo contexto para exibir o estado real do banco de dados, e não as entidades rastreadas pelo contexto de trabalho.
11.10.2. Concorrência otimista
Dois usuários leem o mesmo item, cujo estoque é 10. O primeiro usuário vende uma unidade e atualiza o estoque para 9. O segundo usuário, que leu o estoque antes dessa atualização, vende três unidades e atualiza o estoque para 7: a venda do primeiro usuário é perdida. Esse é o problema das atualizações perdidas.
Uma solução seria bloquear a linha durante toda a operação de cada usuário (concorrência “pessimista”): isso bloqueia os demais usuários, às vezes por muito tempo. O EF Core implementa a concorrência otimista: nada é bloqueado, mas, no momento do commit, o sistema verifica se a linha não foi modificada desde que foi lida. Para isso, uma ou mais propriedades são designadas como tokens de concorrência: o EF Core adiciona a condição “o token ainda tem o valor lido” à cláusula [WHERE] dos comandos [UPDATE] e [DELETE] . Se o comando não modificar nenhuma linha, significa que outro usuário já as processou: o EF Core lança uma [DbUpdateConcurrencyException].
O projeto [Concurrency] transforma o estoque em um token de concorrência. Em vez de modificar a entidade [Article] compartilhada pelos outros exemplos, ele deriva o contexto e complementa o modelo com a fluent API:
- linha 11: a configuração da classe pai é mantida;
- linha 13: a propriedade [CurrentStock] torna-se um token de concorrência. A anotação equivalente é o atributo [ConcurrencyCheck] aplicado à propriedade.
O programa simula os dois usuários com dois contextos:
Resultados:
Comentários:
- linhas 12–13: cada usuário lê a bicicleta em seu próprio contexto;
- linhas 17–18: o comando [UPDATE] do primeiro usuário contém a condição [CurrentStock = @p2], com o valor lido, 10 (linhas 13–16). A linha é modificada;
- linhas 23–26: o comando do segundo usuário contém a mesma condição, com o valor que ele leu, 10, enquanto o estoque no banco de dados agora é 9. Nenhuma linha é modificada: [SELECT ROW_COUNT()] retorna 0, e o EF Core lança uma [DbUpdateConcurrencyException] (linha 24);
- linhas 34–36: a propriedade [Entries] da exceção lista as entidades em conflito. A resolução depende da aplicação: abortar, avisar o usuário ou, como aqui, reler a entidade do banco de dados ([Reload]) e repetir a operação. O estoque relido é 9 (linha 31), e a venda das três bicicletas resulta em um estoque de 6, com a condição [CurrentStock = 9] (linha 36).
O token de concorrência mais comum não é um dado de negócio, mas uma coluna dedicada, modificada a cada atualização da linha: um número de versão ou uma data de modificação. No SQL Server, uma propriedade do tipo [byte[]] marcada com o atributo [Timestamp] é associada ao tipo [rowversion], que o SGBD modifica automaticamente; no MySQL, costuma-se usar um inteiro ou uma data que a aplicação — ou um trigger — modifica a cada atualização.
11.11. O SQL bruto
O EF Core gera SQL a partir do LINQ, mas ainda é possível escrever você mesmo o SQL de uma consulta, para usar um recurso específico do SGBD ou para otimizar uma consulta complexa. O projeto [RawSql] apresenta os métodos disponíveis:
Resultados:
Comentários:
- Linhas 11–13: [FromSql] executa uma consulta SQL que retorna linhas da tabela de uma entidade e instancia entidades (rastreadas pelo contexto). Seu parâmetro é uma string interpolada: o EF Core não a converte em texto; em vez disso, recebe um objeto [FormattableString] que contém o texto e os valores a inserir separadamente, e converte cada valor em um parâmetro SQL ([@p0], linha 5). O resultado de [FromSql] é um [IQueryable<T>]: ele pode ser complementado com LINQ. A cláusula [OrderBy] foi adicionada pelo EF Core em torno da nossa consulta, que se tornou uma subconsulta;
- linhas 19–20: uma tentativa de injeção de SQL. O valor de [name] é passado como parâmetro: ele é comparado literalmente com a coluna [Name], e nenhum registro corresponde (linha 18);
- linha 24: a mesma consulta construída por concatenação e passada a [FromSqlRaw], que executa o texto que recebe. O valor de [name] torna-se código SQL, a condição continua verdadeira e a consulta retorna os seis itens (linha 24): é uma injeção de SQL bem-sucedida. [FromSqlRaw] só deve ser usado com texto constante, com os valores passados como parâmetros ([FromSqlRaw("... WHERE Name = {0}", name)]);
- linhas 29–31: [Database.SqlQuery<T>] (EF Core 7 para tipos simples, EF Core 8 para os demais) executa uma consulta que retorna valores de qualquer tipo, neste caso strings. Para um tipo simples, a coluna retornada deve se chamar [Value] (alias [AS Value]): é o nome que o EF Core usa quando monta a consulta com LINQ, como no [Single] a seguir (linhas 28–32). [SqlQuery] também aceita qualquer classe, cujas propriedades recebem as colunas de mesmo nome;
- linhas 40–42: [Database.ExecuteSql] executa um comando de atualização, também parametrizado por interpolação, e retorna o número de linhas modificadas.
Todos esses métodos têm uma versão assíncrona ([ToListAsync] sobre o resultado de [FromSql], [ExecuteSqlAsync]).
11.12. Contexto e injeção de dependência
Os exemplos anteriores criavam seus contextos usando [new]. Em uma aplicação em camadas, e em todas as aplicações ASP.NET Core, os contextos são criados pelo contêiner de injeção de dependência apresentado no Capítulo 6. O EF Core fornece dois métodos de extensão de [IServiceCollection] para essa finalidade:
- [AddDbContext<T>(options => ...)] registra o contexto [T] com um tempo de vida “scoped”: o contêiner cria um contexto por escopo, fornece-o a todos os serviços desse escopo que o solicitarem e o libera ao final do escopo. Em uma aplicação web, um escopo é criado para cada requisição HTTP: cada requisição tem seu próprio contexto, o que corresponde à unidade de trabalho do contexto;
- [AddDbContextFactory<T>(options => ...)] registra uma fábrica de contextos, [IDbContextFactory<T>], cujo método [CreateDbContext] cria um novo contexto a cada chamada. Ela é usada em serviços de longa duração (singletons), que não podem manter o mesmo contexto durante todo o tempo de vida da aplicação, e em processamentos paralelos, que exigem um contexto por tarefa.
Nos dois casos, a lambda recebe um [DbContextOptionsBuilder] e configura o contexto como [OnConfiguring] fazia; o contexto deve ter um construtor que aceite um [DbContextOptions<T>], como o da classe [ArticlesContext] .
O projeto [Injection] referencia o pacote [Microsoft.Extensions.DependencyInjection] (versão 10.0.12, como no Capítulo 6). Ele define dois serviços:
- linha 7: um serviço que recebe o contexto por meio de seu construtor (primário). Ele deve ser registrado com o mesmo tempo de vida do contexto (scoped);
- linha 15: um serviço que recebe uma fábrica de contextos;
- linha 20: cada chamada ao método cria um contexto e o libera imediatamente.
O programa é o seguinte:
Resultados:
Comentários:
- Linhas 11–12: registro do contexto. A configuração fornecida aqui é a que o construtor do contexto recebe: [OnConfiguring] portanto avalia [options.IsConfigured] como verdadeiro e não adiciona o log SQL. Ele poderia ser adicionado aqui com [WithSqlLog];
- linha 13: o serviço [ArticlesDao], que também é scoped;
- linha 17: [CreateScope()] cria um escopo. Os serviços “scoped” são obtidos do provedor de serviços do escopo ([scope.ServiceProvider]);
- linhas 20–22: duas solicitações do contexto dentro do mesmo escopo retornam o mesmo objeto (linha 2);
- linha 24: o contêiner cria o serviço [ArticlesDao] passando a ele o contexto do escopo;
- linhas 27–31: outro escopo recebe um contexto diferente (linha 4);
- linhas 36–38: ao final do seu escopo, o contexto foi liberado pelo contêiner; usá-lo lança uma [ObjectDisposedException]. Esse é o erro clássico de um serviço de longa duração que reteve um contexto recebido dentro de um escopo;
- linhas 45–47: a fábrica de contextos e um serviço singleton que a utiliza. O serviço pode viver tanto quanto a aplicação: ele não retém um contexto; cria um novo a cada cálculo.
Lembre-se das regras para o tempo de vida de um contexto: curto (uma unidade de trabalho), nunca compartilhado entre várias threads e sempre liberado ([using], ou o contêiner).
11.13. Aplicação de exemplo — versão 7
11.13.1. A arquitetura
A versão 6 da aplicação de cálculo de imposto (Capítulo 10) lia as faixas de imposto de um banco de dados MySQL usando ADO.NET. A versão 7 faz o mesmo usando o EF Core. Como na versão 6, apenas a camada [dao] muda: as camadas [business] e [ui] da versão 5 (Capítulo 6) são reutilizadas como estão, por meio de referências de projeto.

A solução inclui dois novos projetos na pasta [11-efcore/TaxV7]:
11.13.2. A camada [dao]
O projeto [Tax.Dao.Ef] referencia a camada [dao] da versão 5, que contém as entidades ([TaxBracket], [TaxException]) e a interface [ITaxDao]:
- linha 11: a referência ao projeto [Tax.Dao] da versão 5, usando um caminho relativo;
- linhas 16–19: o EF Core, o Pomelo e o pacote necessário para a ferramenta [dotnet ef].
A estrutura [Entities.TaxBracket] da versão 5 não pode ser uma entidade do EF Core: ela é um [readonly record struct], que é imutável e não tem chave primária. Ela não é modificada porque faz parte do contrato entre as camadas, compartilhado por todas as versões. Cria-se uma entidade de persistência específica da camada [dao], cujo papel é representar uma linha da tabela:
- linha 6: a tabela [brackets], como na versão 7 do curso de 2008;
- linha 10: a chave primária, que também é usada para ordenar as faixas;
- linhas 12–19: as três colunas, com tipos de dados [decimal] apropriados: o limite e o coeficiente [coeffN] são valores monetários com duas casas decimais, e [coeffR] é uma taxa com quatro casas decimais.
Contexto:
- linha 6: o contexto é configurado por seu construtor: o programa principal escolherá o banco de dados;
- linhas 15–17: os dados iniciais (seed). Para evitar reescrever as faixas de imposto, reutilizamos as da classe [HardwiredTax] da versão 5, que numeramos a partir de 1 com a sobrecarga de [Select], a qual fornece o índice do elemento;
- Linha 18: [HasData] declara linhas que fazem parte do modelo. As migrações as inserem na tabela e, se elas mudarem, a próxima migração conterá os comandos [UPDATE], [INSERT] ou [DELETE] necessários. As chaves primárias devem ser especificadas explicitamente para que a ferramenta possa comparar os dados entre as versões.
A fábrica usada pela ferramenta [dotnet ef]:
Ela é usada apenas pela ferramenta durante o desenvolvimento: a string de conexão do banco de dados de desenvolvimento está fixada ali no código. Em tempo de execução, a string de conexão vem do arquivo de configuração da aplicação.
A classe [EfTax] implementa a interface [ITaxDao]:
- linha 11: os códigos de erro desta implementação, como em [FileTax] e [JsonTax];
- linha 17: a camada [dao] recebe uma fábrica de contextos. Ela será um singleton: lê as faixas de uma vez por todas em seu construtor, usando um contexto de vida curta que é liberado imediatamente (linha 22);
- linhas 24–28: leitura da tabela, sem rastreamento (as faixas não serão modificadas), em ordem de chave primária. A projeção [Select] transforma cada entidade de persistência em um [Entities.TaxBracket]: o restante da aplicação nunca vê a entidade [TaxBracketEntity]. O EF Core solicita ao SGBD apenas as três colunas relevantes;
- linhas 30–35: um erro do SGBD (banco de dados inacessível, tabela ausente etc.) manifesta-se como uma exceção derivada de [DbException], a classe base das exceções dos conectores ADO.NET (Capítulo 10): [MySqlException] para o MySqlConnector. Como nas outras implementações, ela é encapsulada em uma [TaxException];
- linhas 39–41: uma tabela vazia também é um erro: a camada [business] exige pelo menos uma faixa.
11.13.3. O banco de dados
O banco de dados [eftaxes] é criado pela migração [Initial], gerada pelo comando [dotnet ef migrations add Initial] digitado na pasta do projeto [Tax.Dao.Ef]. A ferramenta aceitou uma biblioteca de classes como projeto de inicialização porque ela contém a fábrica [TaxContextFactory] e o pacote [Microsoft.EntityFrameworkCore.Design] (caso contrário, um projeto executável é especificado com a opção [--startup-project]). A migração é a seguinte:
- linhas 19–31: criação da tabela;
- linhas 35–46: inserção dos dados iniciais, uma linha por faixa;
- linha 6: o código gerado desativa um aviso do analisador de código relativo a arrays multidimensionais ([new object[,]]).
O script SQL da migração mostra os comandos que serão executados:
A tabela [__EFMigrationsHistory] é criada se não existir (linhas 4–8), e depois a migração é aplicada em uma transação. Aplique a migração:
e verifica-se o conteúdo da tabela:
As faixas da tabela progressiva estão presentes, e a última tem limite zero (ela não é usada pela camada [business], que seleciona a última faixa quando nenhuma outra é adequada).
Para configurar o banco de dados em sua máquina: a migração [Initial] já está incluída nos códigos do curso, na pasta [11-efcore/TaxV7/Tax.Dao.Ef/Migrations]. Portanto, você não precisa digitar novamente o comando [dotnet ef migrations add Initial] (ele foi usado para gerar a migração, então essa etapa já está concluída). Basta:
- iniciar o MySQL (no Laragon; veja o apêndice; usuário [root] sem senha);
- instalar a ferramenta [dotnet-ef], se ainda não o fez: [dotnet tool install --global dotnet-ef --version 9.0.0];
- acessar a pasta [11-efcore/TaxV7/Tax.Dao.Ef] e digitar o único comando [dotnet ef database update].
O banco de dados [eftaxes] é então criado, com sua tabela [brackets] preenchida com os dados iniciais. Se o comando falhar, verifique se o MySQL está em execução e se a string de conexão da fábrica [TaxContextFactory] corresponde ao seu servidor (porta 3306, nome de usuário [root], senha em branco).
11.13.4. Integração das camadas
O projeto executável [Tax.Ui.Ef] é composto pelas seguintes camadas:
- linhas 12–13: camadas [business] e [ui] da versão 5. O projeto [Tax.Ui] é um executável: ele pode ser referenciado como biblioteca para usar sua classe [Ui.Dialog];
- Linha 15: a nova camada [dao];
- linha 26: os arquivos de configuração. Eles não se chamam [appsettings.json]: o projeto referenciado [Tax.Ui] já copia seus próprios arquivos [appsettings*.json] para a pasta de saída, e dois arquivos com o mesmo nome entrariam em conflito.
O arquivo de configuração [tax-ef.json] contém a string de conexão:
A seção [ConnectionStrings] é o local habitual das strings de conexão na configuração do .NET: o método [config.GetConnectionString("Tax")] lê a chave [ConnectionStrings:Tax]. O arquivo [tax-ef-error.json] refere-se a um banco de dados chamado [eftaxesmissing], que não existe.
O programa principal é o da versão 5, no qual muda apenas a composição da camada [dao]:
- linhas 21–22: a string de conexão lida da configuração. Uma expressão [throw] (C# 7) à direita de [??] lança uma exceção se ela estiver ausente;
- linhas 27–28: uma fábrica de contextos [TaxContext], configurada com a string de conexão da configuração;
- linha 30: a camada [dao] é um [EfTax]: o contêiner passará a fábrica de contextos a ele. Uma camada [dao] singleton não pode receber diretamente um contexto, que é “scoped” — daí a fábrica;
- linha 32: a camada [business] da versão 5;
- linha 46: a caixa de diálogo da versão 5.
11.13.5. Execuções
Os valores de referência das versões anteriores são mantidos: 4.282 euros para um casal com dois filhos e renda conjunta de 60.000 euros, 2.959 euros para uma família com três filhos e 11.519 euros para uma pessoa solteira sem filhos.
Com o arquivo de configuração [tax-ef-error.json], que se refere a um banco de dados inexistente:
- linha 6: a exceção original, lançada pelo conector MySqlConnector, por meio do EF Core;
- linha 4: a camada [dao] a encapsulou em uma [TaxException], que foi exibida pelo programa principal.
O curso de 2008 demonstrava, na versão 7, que a camada [dao] podia trocar de SGBD (do MySQL para o SQL Server Compact) simplesmente modificando o arquivo de configuração, graças ao conector genérico do ADO.NET. Com o EF Core, trocar de SGBD equivale a trocar de provider: substituir o pacote Pomelo pelo de outro SGBD (por exemplo, [Microsoft.EntityFrameworkCore.SqlServer]) e a chamada a [UseMySql] pela chamada correspondente ([UseSqlServer]), e depois regenerar as migrações, que contêm informações específicas do provider. O código da classe [EfTax], escrito em LINQ, permanece inalterado.
11.14. Conclusão: ADO.NET, Dapper ou EF Core?
Agora temos duas maneiras de acessar um banco de dados: o ADO.NET (Capítulo 10) e o EF Core (este capítulo). Há uma terceira, intermediária, amplamente utilizada: o Dapper, uma pequena biblioteca (um “micro-ORM”) que adiciona métodos de extensão à conexão ADO.NET. Esses métodos executam uma consulta SQL escrita à mão e convertem automaticamente as linhas do resultado em objetos: [connection.Query<Article>("SELECT * FROM articles WHERE Price > @price", new { price = 200 })]. Você escreve o SQL, e o Dapper cuida de mapear as colunas para propriedades.
Pontos fortes | Pontos fracos | |
ADO.NET | Controle total sobre o SQL; desempenho; nenhuma dependência | muito código repetitivo (parâmetros, leitura de colunas); SQL em strings, não verificado pelo compilador |
Dapper | SQL escrito à mão, mas sem o código de cópia; desempenho semelhante ao do ADO.NET | Sem rastreamento de alterações nem geração de [INSERT]/[UPDATE]; sem migrações |
EF Core | Consultas LINQ verificadas pelo compilador; rastreamento de alterações; relacionamentos; migrações; independência do SGBD | uma camada adicional a compreender; SQL gerado que precisa ser monitorado; menos adequado para processamentos em lote complexos |
Podem-se propor as seguintes diretrizes:
- O EF Core é adequado para a maioria das aplicações de gestão: um modelo de entidades interligadas, operações de leitura e atualização de entidades e um esquema que evolui com a aplicação. É a escolha padrão para aplicações ASP.NET Core;
- O ADO.NET, ou o Dapper, é adequado quando se deseja controle preciso sobre o SQL executado: consultas complexas de relatórios, procedimentos armazenados, processamento de volumes muito grandes ou um banco de dados existente com um esquema pouco adequado a um modelo orientado a objetos;
- Essas abordagens podem ser combinadas: uma aplicação pode usar o EF Core na maior parte e código SQL escrito à mão — usando [FromSql], [SqlQuery] ou o Dapper — para algumas consultas críticas. O EF Core também dá acesso à conexão ADO.NET que ele utiliza ([context.Database.GetDbConnection()]).
De qualquer modo, conhecer ORM não elimina a necessidade de entender SQL e o funcionamento do SGBD: o log dos comandos SQL executados, que exibimos ao longo deste capítulo, é a principal ferramenta para verificar o que o EF Core realmente faz.
Para mais informações, a documentação da Microsoft é completa: Entity Framework Core. O provider Pomelo é documentado em seu repositório: Pomelo.EntityFrameworkCore.MySql.