Skip to content

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:

Image

  • [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:

> dotnet tool install --global dotnet-ef --version 9.0.0

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:

1
2
3
4
> dotnet new console -n First -o First
> cd First
> dotnet add package Microsoft.EntityFrameworkCore --version 9.0.0
> dotnet add package Pomelo.EntityFrameworkCore.MySql --version 9.0.0

Seu arquivo de projeto é o seguinte:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!-- EF Core e seu provider MySQL (Pomelo) -->
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
  </ItemGroup>

</Project>
  • 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:

namespace First;

// um artigo da loja: uma classe C# comum, sem vínculo com o EF Core
public class Article
{
    // chave primária (por convenção: a propriedade chamada Id)
    public int Id { get; set; }
    // as outras colunas da tabela
    public string Name { get; set; } = "";
    public decimal Price { get; set; }
    public int CurrentStock { get; set; }
    public int MinimumStock { get; set; }

    // exibição
    public override string ToString() => $"[{Id}, {Name}, {Price}, {CurrentStock}, {MinimumStock}]";
}
  • 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]:

using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Logging;

namespace First;

// o contexto: a porta de entrada para o banco de dados [efarticles]
public class ArticlesContext : DbContext
{
    // a tabela de artigos
    public DbSet<Article> Articles => Set<Article>();

    // configuração do contexto: SGBD, string de conexão, log
    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        const string connection = "Server=localhost;Port=3306;Database=efarticles;User=root;Password=";
        options
            // o provider MySQL e a versão do servidor
            .UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36)))
            // exibição das instruções SQL enviadas ao servidor
            .LogTo(Console.WriteLine, [DbLoggerCategory.Database.Command.Name], LogLevel.Information);
    }
}
  • 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

using First;

// um contexto do EF Core: ele será liberado (conexão incluída) no fim do programa
using var context = new ArticlesContext();

// o banco de dados é excluído e depois recriado a partir do modelo C#
context.Database.EnsureDeleted();
context.Database.EnsureCreated();

// adição de três artigos
context.Articles.Add(new Article { Name = "bike", Price = 500, CurrentStock = 10, MinimumStock = 5 });
context.Articles.Add(new Article { Name = "pump", Price = 10, CurrentStock = 10, MinimumStock = 2 });
context.Articles.Add(new Article { Name = "bow", Price = 600, CurrentStock = 4, MinimumStock = 1 });
Console.WriteLine("--- SaveChanges");
int nbRows = context.SaveChanges();
Console.WriteLine($"{nbRows} row(s) inserted");

// leitura da tabela
Console.WriteLine("--- reading the articles");
foreach (Article article in context.Articles.OrderBy(a => a.Name))
{
    Console.WriteLine(article);
}
  • 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:

> dotnet run
info: 03/10/2026 12:24:29.016 RelationalEventId.CommandExecuted[20101] (Microsoft.EntityFrameworkCore.Database.Command) 
      Executed DbCommand (13ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      DROP DATABASE `efarticles`;
info: 03/10/2026 12:24:29.040 RelationalEventId.CommandExecuted[20101] (Microsoft.EntityFrameworkCore.Database.Command) 
      Executed DbCommand (2ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      CREATE DATABASE `efarticles`;
info: 03/10/2026 12:24:29.188 RelationalEventId.CommandExecuted[20101] (Microsoft.EntityFrameworkCore.Database.Command) 
      Executed DbCommand (2ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      ALTER DATABASE CHARACTER SET utf8mb4;
info: 03/10/2026 12:24:29.197 RelationalEventId.CommandExecuted[20101] (Microsoft.EntityFrameworkCore.Database.Command) 
      Executed DbCommand (8ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      CREATE TABLE `Articles` (
          `Id` int NOT NULL AUTO_INCREMENT,
          `Name` longtext CHARACTER SET utf8mb4 NOT NULL,
          `Price` decimal(65,30) NOT NULL,
          `CurrentStock` int NOT NULL,
          `MinimumStock` int NOT NULL,
          CONSTRAINT `PK_Articles` PRIMARY KEY (`Id`)
      ) CHARACTER SET=utf8mb4;
--- SaveChanges
info: 03/10/2026 12:24:29.430 RelationalEventId.CommandExecuted[20101] (Microsoft.EntityFrameworkCore.Database.Command) 
      Executed DbCommand (29ms) [Parameters=[@p0='?' (DbType = Int32), @p1='?' (DbType = Int32), @p2='?' (Size = 4000), @p3='?' (DbType = Decimal), @p4='?' (DbType = Int32), @p5='?' (DbType = Int32), @p6='?' (Size = 4000), @p7='?' (DbType = Decimal), @p8='?' (DbType = Int32), @p9='?' (DbType = Int32), @p10='?' (Size = 4000), @p11='?' (DbType = Decimal)], CommandType='Text', CommandTimeout='30']
      INSERT INTO `Articles` (`CurrentStock`, `MinimumStock`, `Name`, `Price`)
      VALUES (@p0, @p1, @p2, @p3);
      SELECT `Id`
      FROM `Articles`
      WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();

      INSERT INTO `Articles` (`CurrentStock`, `MinimumStock`, `Name`, `Price`)
      VALUES (@p4, @p5, @p6, @p7);
      SELECT `Id`
      FROM `Articles`
      WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();

      INSERT INTO `Articles` (`CurrentStock`, `MinimumStock`, `Name`, `Price`)
      VALUES (@p8, @p9, @p10, @p11);
      SELECT `Id`
      FROM `Articles`
      WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
3 row(s) inserted
--- reading the articles
info: 03/10/2026 12:24:29.690 RelationalEventId.CommandExecuted[20101] (Microsoft.EntityFrameworkCore.Database.Command) 
      Executed DbCommand (5ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
      FROM `Articles` AS `a`
      ORDER BY `a`.`Name`
[1, bike, 500, 10, 5]
[3, bow, 600, 4, 1]
[2, pump, 10, 10, 2]

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:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace Model;

// uma entidade configurada por anotações
[Table("products")]
public class Product
{
    // a chave primária não se chama Id: é preciso designá-la
    [Key]
    public int Code { get; set; }

    // string obrigatória de no máximo 50 caracteres
    [Required, MaxLength(50)]
    public string Name { get; set; } = "";

    // tipo de referência anulável: coluna NULL permitida
    [MaxLength(200)]
    public string? Description { get; set; }

    // nome e tipo SQL da coluna impostos
    [Column("price_excl_tax", TypeName = "decimal(10,2)")]
    public decimal PriceExclTax { get; set; }

    // tipo de valor anulável: coluna NULL permitida
    public DateOnly? WithdrawalDate { get; set; }

    // propriedade calculada: sem coluna
    [NotMapped]
    public decimal PriceInclTax => PriceExclTax * 1.2M;
}
  • 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:

namespace Model;

// uma entidade sem nenhuma anotação: ela é configurada pela fluent API
public class Supplier
{
    public int Number { get; set; }
    public string CompanyName { get; set; } = "";
    public string? Phone { get; set; }
    public DateTime CreationDate { get; set; }
}

Ela é configurada no contexto pela API fluente:

using Microsoft.EntityFrameworkCore;

namespace Model;

// um contexto usado apenas para examinar o modelo: ele nunca se conecta ao servidor
public class ModelContext : DbContext
{
    public DbSet<Product> Products => Set<Product>();
    public DbSet<Supplier> Suppliers => Set<Supplier>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        const string connection = "Server=localhost;Port=3306;Database=efmodel;User=root;Password=";
        options.UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36)));
    }

    // a fluent API: configuração do modelo por código
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Supplier>(supplier =>
        {
            supplier.ToTable("suppliers");
            supplier.HasKey(f => f.Number);
            supplier.Property(f => f.CompanyName).IsRequired().HasMaxLength(60);
            supplier.HasIndex(f => f.CompanyName).IsUnique();
            supplier.Property(f => f.Phone).HasColumnName("tel").HasMaxLength(20);
            supplier.Property(f => f.CreationDate).HasDefaultValueSql("CURRENT_TIMESTAMP");
        });
    }
}
  • 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:

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata;
using Model;

using var context = new ModelContext();

// o modelo construído pelo EF Core: entidades, tabelas, colunas
foreach (IEntityType entity in context.Model.GetEntityTypes())
{
    Console.WriteLine($"entity {entity.ClrType.Name} -> table {entity.GetTableName()}");
    foreach (IProperty property in entity.GetProperties())
    {
        string key = property.IsPrimaryKey() ? " (primary key)" : "";
        string nullable = property.IsNullable ? "NULL" : "NOT NULL";
        Console.WriteLine($"  {property.Name,-14} -> {property.GetColumnName(),-14} {property.GetColumnType(),-16} {nullable}{key}");
    }
}

// o script SQL que cria as tabelas, sem executá-lo
Console.WriteLine("--- creation script");
// (as linhas vazias duplicadas são removidas)
Console.WriteLine(context.Database.GenerateCreateScript().Replace("\n\n\n", "\n\n").Trim());
  • 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:

> dotnet run
entity Product -> table products
  Code           -> Code           int              NOT NULL (primary key)
  Description    -> Description    varchar(200)     NULL
  Name           -> Name           varchar(50)      NOT NULL
  PriceExclTax   -> price_excl_tax decimal(10,2)    NOT NULL
  WithdrawalDate -> WithdrawalDate date             NULL
entity Supplier -> table suppliers
  Number         -> Number         int              NOT NULL (primary key)
  CompanyName    -> CompanyName    varchar(60)      NOT NULL
  CreationDate   -> CreationDate   datetime(6)      NOT NULL
  Phone          -> tel            varchar(20)      NULL
--- creation script
ALTER DATABASE CHARACTER SET utf8mb4;

CREATE TABLE `products` (
    `Code` int NOT NULL AUTO_INCREMENT,
    `Name` varchar(50) CHARACTER SET utf8mb4 NOT NULL,
    `Description` varchar(200) CHARACTER SET utf8mb4 NULL,
    `price_excl_tax` decimal(10,2) NOT NULL,
    `WithdrawalDate` date NULL,
    CONSTRAINT `PK_products` PRIMARY KEY (`Code`)
) CHARACTER SET=utf8mb4;

CREATE TABLE `suppliers` (
    `Number` int NOT NULL AUTO_INCREMENT,
    `CompanyName` varchar(60) CHARACTER SET utf8mb4 NOT NULL,
    `tel` varchar(20) CHARACTER SET utf8mb4 NULL,
    `CreationDate` datetime(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT `PK_suppliers` PRIMARY KEY (`Number`)
) CHARACTER SET=utf8mb4;

CREATE UNIQUE INDEX `IX_suppliers_CompanyName` ON `suppliers` (`CompanyName`);
  • 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:

1
2
3
4
// um valor padrão, que satisfaz o compilador
public string Name { get; set; } = "";
// um membro obrigatório (C# 11): o código que cria o objeto deve fornecer um valor
public required string Name { get; set; }

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

using System.Data.Common;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Diagnostics;
using Microsoft.Extensions.Logging;

namespace Ef.Tools;

// um log compacto das instruções SQL executadas pelo EF Core
public static class SqlLog
{
    // um membro de extensão (C# 14) do tipo DbContextOptionsBuilder
    extension(DbContextOptionsBuilder options)
    {
        // options.WithSqlLog(): exibe cada instrução SQL executada
        public DbContextOptionsBuilder WithSqlLog() => options.LogTo(Filter, Display);
    }

    // os eventos selecionados: comando SQL executado ou com falha, início e fim das transações
    private static bool Filter(EventId id, LogLevel level) =>
        id == RelationalEventId.CommandExecuted || id == RelationalEventId.CommandError
        || id == RelationalEventId.TransactionStarted
        || id == RelationalEventId.TransactionCommitted || id == RelationalEventId.TransactionRolledBack;

    // exibição de um evento
    private static void Display(EventData data)
    {
        switch (data)
        {
            case CommandExecutedEventData command:
                DisplayCommand(command.Command);
                break;
            case CommandErrorEventData error:
                DisplayCommand(error.Command);
                Console.WriteLine("    SQL> -- command failed");
                break;
            case TransactionEventData when data.EventId == RelationalEventId.TransactionStarted:
                Console.WriteLine("    SQL> -- start of transaction");
                break;
            case TransactionEventData when data.EventId == RelationalEventId.TransactionCommitted:
                Console.WriteLine("    SQL> -- transaction committed (COMMIT)");
                break;
            case TransactionEventData:
                Console.WriteLine("    SQL> -- transaction rolled back (ROLLBACK)");
                break;
        }
    }

    // exibição da instrução SQL, indentada, e depois de seus parâmetros
    private static void DisplayCommand(DbCommand command)
    {
        // as linhas vazias são ignoradas
        foreach (string line in command.CommandText.Split('\n').Select(l => l.TrimEnd()).Where(l => l != ""))
        {
            Console.WriteLine("    SQL> " + line);
        }
        if (command.Parameters.Count > 0)
        {
            var parameters = command.Parameters.Cast<DbParameter>()
                .Select(p => $"{(p.ParameterName.StartsWith('@') ? "" : "@")}{p.ParameterName}={p.Value}");
            Console.WriteLine($"    SQL> -- parameters: {string.Join(", ", parameters)}");
        }
    }
}
  • 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:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using Microsoft.EntityFrameworkCore;

namespace Articles.Data;

// um artigo da loja, com as anotações que especificam sua tabela
[Table("articles")]
[Index(nameof(Name), IsUnique = true)]
public class Article
{
    // chave primária, gerada pelo SGBD (AUTO_INCREMENT)
    public int Id { get; set; }

    // nome do artigo: obrigatório, no máximo 30 caracteres, único (veja [Index])
    [MaxLength(30)]
    public required string Name { get; set; }

    // preço: 10 dígitos, dos quais 2 após a vírgula decimal
    [Column(TypeName = "decimal(10,2)")]
    public decimal Price { get; set; }

    // estoque atual e estoque mínimo abaixo do qual é preciso reabastecer
    public int CurrentStock { get; set; }
    public int MinimumStock { get; set; }

    // exibição
    public override string ToString() => $"[{Id}, {Name}, {Price}, {CurrentStock}, {MinimumStock}]";
}
  • 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:

using Ef.Tools;
using Microsoft.EntityFrameworkCore;

namespace Articles.Data;

// o contexto do banco de dados [efarticles]
public class ArticlesContext : DbContext
{
    // string de conexão e versão do servidor MySQL
    public const string Connection = "Server=localhost;Port=3306;Database=efarticles;User=root;Password=";
    public static readonly ServerVersion MySqlVersion = new MySqlServerVersion(new Version(8, 0, 36));

    // construtor sem parâmetros: a configuração é feita por OnConfiguring
    public ArticlesContext() { }

    // construtor que recebe uma configuração pronta (injeção de dependência)
    public ArticlesContext(DbContextOptions<ArticlesContext> options) : base(options) { }

    // a tabela de artigos
    public DbSet<Article> Articles => Set<Article>();

    // configuração padrão, se o construtor não recebeu nenhuma
    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        if (!options.IsConfigured)
        {
            // com exibição das instruções SQL (veja o projeto [Ef.Tools])
            options.UseMySql(Connection, MySqlVersion).WithSqlLog();
        }
    }

    // (re)criação do banco de dados com seus seis artigos, sem log
    public static void Initialize()
    {
        var options = new DbContextOptionsBuilder<ArticlesContext>()
            .UseMySql(Connection, MySqlVersion)
            .Options;
        using var context = new ArticlesContext(options);
        context.Database.EnsureDeleted();
        context.Database.EnsureCreated();
        context.Articles.AddRange(
            new Article { Name = "bike", Price = 500, CurrentStock = 10, MinimumStock = 5 },
            new Article { Name = "pump", Price = 10, CurrentStock = 10, MinimumStock = 2 },
            new Article { Name = "bow", Price = 600, CurrentStock = 4, MinimumStock = 1 },
            new Article { Name = "arrows - set of 6", Price = 100, CurrentStock = 12, MinimumStock = 20 },
            new Article { Name = "diving suit", Price = 300, CurrentStock = 8, MinimumStock = 2 },
            new Article { Name = "diver's oxygen tanks", Price = 120, CurrentStock = 10, MinimumStock = 5 });
        context.SaveChanges();
    }
}
  • 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]:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!-- a entidade [Article] e o contexto [ArticlesContext] (EF Core incluído) -->
    <ProjectReference Include="../Articles.Data/Articles.Data.csproj" />
  </ItemGroup>

</Project>

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):

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// o banco de dados é recriado com seus seis artigos
ArticlesContext.Initialize();
using var context = new ArticlesContext();

// 1 - busca pela chave primária
Console.WriteLine("--- Find(1)");
Article? bike = context.Articles.Find(1);
Console.WriteLine(bike);
Console.WriteLine("--- Find(1) a second time");
Article? bike2 = context.Articles.Find(1);
Console.WriteLine($"same object: {ReferenceEquals(bike, bike2)}");

// 2 - adição de um artigo
Console.WriteLine("--- Add");
var x = new Article { Name = "x", Price = 100, CurrentStock = 10, MinimumStock = 1 };
context.Articles.Add(x);
Console.WriteLine($"before SaveChanges: state={context.Entry(x).State}, Id={x.Id}");
context.SaveChanges();
Console.WriteLine($"after SaveChanges: state={context.Entry(x).State}, Id={x.Id}");

// 3 - modificação: basta modificar o objeto
Console.WriteLine("--- modification of the price");
x.Price *= 1.1M;
var price = context.Entry(x).Property(a => a.Price);
Console.WriteLine($"state={context.Entry(x).State}, original price={price.OriginalValue}, current price={price.CurrentValue}");
context.SaveChanges();
Console.WriteLine($"after SaveChanges: state={context.Entry(x).State}");

// 4 - exclusão
Console.WriteLine("--- Remove");
context.Articles.Remove(x);
Console.WriteLine($"before SaveChanges: state={context.Entry(x).State}");
context.SaveChanges();
Console.WriteLine($"after SaveChanges: state={context.Entry(x).State}");

// 5 - as entidades rastreadas pelo contexto
Console.WriteLine("--- the tracked entities");
bike!.CurrentStock--;
context.ChangeTracker.DetectChanges();
Console.WriteLine(context.ChangeTracker.DebugView.LongView);

Resultados:

> dotnet run
--- Find(1)
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Id` = @__p_0
    SQL> LIMIT 1
    SQL> -- parameters: @__p_0=1
[1, bike, 500.00, 10, 5]
--- Find(1) a second time
same object: True
--- Add
before SaveChanges: state=Added, Id=0
    SQL> -- start of transaction
    SQL> INSERT INTO `articles` (`CurrentStock`, `MinimumStock`, `Name`, `Price`)
    SQL> VALUES (@p0, @p1, @p2, @p3);
    SQL> SELECT `Id`
    SQL> FROM `articles`
    SQL> WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
    SQL> -- parameters: @p0=10, @p1=1, @p2=x, @p3=100
    SQL> -- transaction committed (COMMIT)
after SaveChanges: state=Unchanged, Id=7
--- modification of the price
state=Modified, original price=100, current price=110.0
    SQL> SET AUTOCOMMIT = 1;
    SQL> UPDATE `articles` SET `Price` = @p0
    SQL> WHERE `Id` = @p1;
    SQL> SELECT ROW_COUNT();
    SQL> -- parameters: @p1=7, @p0=110.0
after SaveChanges: state=Unchanged
--- Remove
before SaveChanges: state=Deleted
    SQL> SET AUTOCOMMIT = 1;
    SQL> DELETE FROM `articles`
    SQL> WHERE `Id` = @p0;
    SQL> SELECT ROW_COUNT();
    SQL> -- parameters: @p0=7
after SaveChanges: state=Detached
--- the tracked entities
Article {Id: 1} Modified
    Id: 1 PK
    CurrentStock: 9 Modified Originally 10
    MinimumStock: 5
    Name: 'bike'
    Price: 500.00

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:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// o banco de dados é recriado com seus seis artigos
ArticlesContext.Initialize();
using var context = new ArticlesContext();

// 1 - ExecuteUpdate: uma única instrução UPDATE, nenhuma entidade carregada em memória
Console.WriteLine("--- restocking of the out-of-stock articles");
int nbRows = context.Articles
    .Where(a => a.CurrentStock < a.MinimumStock)
    .ExecuteUpdate(s => s.SetProperty(a => a.CurrentStock, a => a.MinimumStock * 2));
Console.WriteLine($"{nbRows} article(s) modified");

Console.WriteLine("--- 10 % increase of the prices below 150 euros");
nbRows = context.Articles
    .Where(a => a.Price < 150)
    .ExecuteUpdate(s => s.SetProperty(a => a.Price, a => a.Price * 1.1M));
Console.WriteLine($"{nbRows} article(s) modified");

// 2 - ExecuteDelete: uma única instrução DELETE
Console.WriteLine("--- deletion of the articles over 550 euros");
nbRows = context.Articles.Where(a => a.Price > 550).ExecuteDelete();
Console.WriteLine($"{nbRows} article(s) deleted");

// 3 - leitura sem rastreamento de alterações
Console.WriteLine("--- AsNoTracking");
List<Article> articles = context.Articles.AsNoTracking().OrderBy(a => a.Id).ToList();
articles.ForEach(Console.WriteLine);
Console.WriteLine($"entities tracked by the context: {context.ChangeTracker.Entries().Count()}");
// a modificação de uma entidade não rastreada é ignorada por SaveChanges
articles[0].Price = 0;
Console.WriteLine($"SaveChanges: {context.SaveChanges()} row(s) modified");

// 4 - ExecuteUpdate não modifica as entidades já carregadas pelo contexto
Console.WriteLine("--- ExecuteUpdate and tracked entities");
Article bike = context.Articles.Single(a => a.Name == "bike");
context.Articles.Where(a => a.Id == bike.Id).ExecuteUpdate(s => s.SetProperty(a => a.Price, 450M));
Console.WriteLine($"price in memory: {bike.Price}");
context.Entry(bike).Reload();
Console.WriteLine($"price after Reload: {bike.Price}");

Resultados:

> dotnet run
--- restocking of the out-of-stock articles
    SQL> UPDATE `articles` AS `a`
    SQL> SET `a`.`CurrentStock` = `a`.`MinimumStock` * 2
    SQL> WHERE `a`.`CurrentStock` < `a`.`MinimumStock`
1 article(s) modified
--- 10 % increase of the prices below 150 euros
    SQL> UPDATE `articles` AS `a`
    SQL> SET `a`.`Price` = `a`.`Price` * 1.1
    SQL> WHERE `a`.`Price` < 150.0
3 article(s) modified
--- deletion of the articles over 550 euros
    SQL> DELETE `a`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Price` > 550.0
1 article(s) deleted
--- AsNoTracking
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> ORDER BY `a`.`Id`
[1, bike, 500.00, 10, 5]
[2, pump, 11.00, 10, 2]
[4, arrows - set of 6, 110.00, 40, 20]
[5, diving suit, 300.00, 8, 2]
[6, diver's oxygen tanks, 132.00, 10, 5]
entities tracked by the context: 0
SaveChanges: 0 row(s) modified
--- ExecuteUpdate and tracked entities
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Name` = 'bike'
    SQL> LIMIT 2
    SQL> UPDATE `articles` AS `a`
    SQL> SET `a`.`Price` = 450.0
    SQL> WHERE `a`.`Id` = @__bike_Id_0
    SQL> -- parameters: @__bike_Id_0=1
price in memory: 500.00
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Id` = @__p_0
    SQL> LIMIT 1
    SQL> -- parameters: @__p_0=1
price after Reload: 450.00

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:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// o banco de dados é recriado com seus seis artigos
ArticlesContext.Initialize();
using var context = new ArticlesContext();

// 1 - filtragem e ordenação
Console.WriteLine("--- the articles to restock, in alphabetical order");
List<Article> toOrder = context.Articles
    .Where(a => a.CurrentStock < a.MinimumStock)
    .OrderBy(a => a.Name)
    .ToList();
toOrder.ForEach(Console.WriteLine);

// 2 - projeção: apenas as colunas úteis são solicitadas
Console.WriteLine("--- stock value of each article");
var values = context.Articles
    .Select(a => new { a.Name, Value = a.Price * a.CurrentStock })
    .OrderByDescending(v => v.Value)
    .ToList();
foreach (var v in values)
{
    Console.WriteLine($"{v.Name} : {v.Value:0.00} euros");
}

// 3 - um único resultado; a variável [minPrice] se torna um parâmetro SQL
Console.WriteLine("--- the first article over 200 euros");
decimal minPrice = 200;
Article? article = context.Articles.OrderBy(a => a.Price).FirstOrDefault(a => a.Price > minPrice);
Console.WriteLine(article?.ToString() ?? "none");

// 4 - agregações: o cálculo é feito pelo SGBD
Console.WriteLine("--- aggregates");
int nbArticles = context.Articles.Count();
decimal stockValue = context.Articles.Sum(a => a.Price * a.CurrentStock);
Console.WriteLine($"{nbArticles} articles, stock value: {stockValue:0.00} euros");

// 5 - métodos .NET traduzidos para SQL
Console.WriteLine("--- StartsWith and Contains");
// uma lista e não um array (veja as explicações)
List<string> names = ["bow", "pump", "racket"];
var results = context.Articles
    .Where(a => a.Name.StartsWith("b") || names.Contains(a.Name))
    .Select(a => a.Name)
    .ToList();
Console.WriteLine(string.Join(", ", results));

// 6 - o SQL de uma consulta, sem executá-la
Console.WriteLine("--- ToQueryString");
IQueryable<Article> query = context.Articles.Where(a => a.Price < 150).OrderBy(a => a.Price);
Console.WriteLine(query.ToQueryString());

// 7 - paginação: a terceira página de dois artigos, por preço crescente
Console.WriteLine("--- Skip and Take");
int pageSize = 2, pageNumber = 3;
List<string> page = context.Articles
    .OrderBy(a => a.Price)
    .Skip((pageNumber - 1) * pageSize)
    .Take(pageSize)
    .Select(a => $"{a.Name} ({a.Price} euros)")
    .ToList();
Console.WriteLine($"page {pageNumber} : {string.Join(", ", page)}");

// 8 - um método C# que o EF Core não consegue traduzir
Console.WriteLine("--- untranslatable method");
try
{
    var list = context.Articles.Where(a => Rules.OutOfStock(a)).ToList();
}
catch (InvalidOperationException e)
{
    // exibimos apenas a primeira frase da mensagem
    int end = e.Message.IndexOf(" Either");
    Console.WriteLine($"{e.GetType().Name} : {(end > 0 ? e.Message[..end] : e.Message)}");
}
// AsEnumerable: o restante da consulta é executado em memória, pelo .NET
var outOfStock = context.Articles.AsEnumerable().Where(a => Rules.OutOfStock(a)).ToList();
outOfStock.ForEach(Console.WriteLine);

// uma regra de negócio escrita em C#
static class Rules
{
    // um artigo está sem estoque se seu estoque for menor que o estoque mínimo
    public static bool OutOfStock(Article a) => a.CurrentStock < a.MinimumStock;
}

Resultados:

> dotnet run
--- the articles to restock, in alphabetical order
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`CurrentStock` < `a`.`MinimumStock`
    SQL> ORDER BY `a`.`Name`
[4, arrows - set of 6, 100.00, 12, 20]
--- stock value of each article
    SQL> SELECT `a`.`Name`, `a`.`Price` * CAST(`a`.`CurrentStock` AS decimal(65,30)) AS `Value`
    SQL> FROM `articles` AS `a`
    SQL> ORDER BY `a`.`Price` * CAST(`a`.`CurrentStock` AS decimal(65,30)) DESC
bike : 5000.00 euros
bow : 2400.00 euros
diving suit : 2400.00 euros
arrows - set of 6 : 1200.00 euros
diver's oxygen tanks : 1200.00 euros
pump : 100.00 euros
--- the first article over 200 euros
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Price` > @__minPrice_0
    SQL> ORDER BY `a`.`Price`
    SQL> LIMIT 1
    SQL> -- parameters: @__minPrice_0=200
[5, diving suit, 300.00, 8, 2]
--- aggregates
    SQL> SELECT COUNT(*)
    SQL> FROM `articles` AS `a`
    SQL> SELECT COALESCE(SUM(`a`.`Price` * CAST(`a`.`CurrentStock` AS decimal(65,30))), 0.0)
    SQL> FROM `articles` AS `a`
6 articles, stock value: 12300.00 euros
--- StartsWith and Contains
    SQL> SELECT `a`.`Name`
    SQL> FROM `articles` AS `a`
    SQL> WHERE (`a`.`Name` LIKE 'b%') OR `a`.`Name` IN ('bow', 'pump', 'racket')
bike, bow, pump
--- ToQueryString
SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
FROM `articles` AS `a`
WHERE `a`.`Price` < 150.0
ORDER BY `a`.`Price`
--- Skip and Take
    SQL> SELECT `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> ORDER BY `a`.`Price`
    SQL> LIMIT @__p_1 OFFSET @__p_0
    SQL> -- parameters: @__p_1=2, @__p_0=4
page 3 : bike (500.00 euros), bow (600.00 euros)
--- untranslatable method
InvalidOperationException : The LINQ expression 'DbSet<Article>()
    .Where(a => Rules.OutOfStock(a))' could not be translated.
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
[4, arrows - set of 6, 100.00, 12, 20]

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:

1
2
3
4
5
6
7
8
IQueryable<Article> query = context.Articles;
if (maxPrice != null)
{
    query = query.Where(a => a.Price <= maxPrice);
}
query = query.OrderBy(a => a.Name);
// uma única instrução SELECT, com ou sem WHERE
List<Article> articles = query.ToList();

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:

namespace Relations;

// uma categoria agrupa vários produtos (relacionamento um-para-muitos)
public class Category
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    // propriedade de navegação: os produtos da categoria
    public List<Product> Products { get; set; } = [];
}

// um produto pertence a uma categoria e possui várias tags
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public decimal Price { get; set; }
    // chave estrangeira e propriedade de navegação para a categoria
    public int CategoryId { get; set; }
    public Category Category { get; set; } = null!;
    // relacionamento muitos-para-muitos com as tags
    public List<Tag> Tags { get; set; } = [];
}

// uma tag (promoção, novidade...) é associada a vários produtos
public class Tag
{
    public int Id { get; set; }
    public string Label { get; set; } = "";
    public List<Product> Products { get; set; } = [];
}

// um cliente faz pedidos
public class Client
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public List<Order> Orders { get; set; } = [];
}

// um pedido de um cliente, composto de linhas
public class Order
{
    public int Id { get; set; }
    public DateOnly Date { get; set; }
    public int ClientId { get; set; }
    public Client Client { get; set; } = null!;
    public List<OrderLine> Lines { get; set; } = [];
}

// uma linha de pedido: uma quantidade de um produto
public class OrderLine
{
    public int Id { get; set; }
    public int Quantity { get; set; }
    public int OrderId { get; set; }
    public Order Order { get; set; } = null!;
    public int ProductId { get; set; }
    public Product Product { get; set; } = null!;
}
  • 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:

using Ef.Tools;
using Microsoft.EntityFrameworkCore;

namespace Relations;

// o contexto do banco de dados [efshop]; [log]: exibir ou não as instruções SQL
public class ShopContext(bool log = true) : DbContext
{
    public DbSet<Category> Categories => Set<Category>();
    public DbSet<Product> Products => Set<Product>();
    public DbSet<Tag> Tags => Set<Tag>();
    public DbSet<Client> Clients => Set<Client>();
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        const string connection = "Server=localhost;Port=3306;Database=efshop;User=root;Password=";
        options.UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36)));
        if (log)
        {
            options.WithSqlLog();
        }
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // preços com duas casas decimais
        modelBuilder.Entity<Product>().Property(p => p.Price).HasPrecision(10, 2);
    }
}
  • 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:

> mysql -uroot efshop -e "SHOW TABLES; SHOW CREATE TABLE Products\G SHOW CREATE TABLE ProductTag\G"
+------------------+
| Tables_in_efshop |
+------------------+
| Categories       |
| Clients          |
| OrderLine        |
| Orders           |
| ProductTag       |
| Products         |
| Tags             |
+------------------+
*************************** 1. row ***************************
       Table: Products
Create Table: CREATE TABLE `Products` (
  `Id` int NOT NULL AUTO_INCREMENT,
  `Name` longtext CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL,
  `Price` decimal(10,2) NOT NULL,
  `CategoryId` int NOT NULL,
  PRIMARY KEY (`Id`),
  KEY `IX_Products_CategoryId` (`CategoryId`),
  CONSTRAINT `FK_Products_Categories_CategoryId` FOREIGN KEY (`CategoryId`) REFERENCES `Categories` (`Id`) ON DELETE CASCADE
) ENGINE=InnoDB AUTO_INCREMENT=5 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
*************************** 1. row ***************************
       Table: ProductTag
Create Table: CREATE TABLE `ProductTag` (
  `ProductsId` int NOT NULL,
  `TagsId` int NOT NULL,
  PRIMARY KEY (`ProductsId`,`TagsId`),
  KEY `IX_ProductTag_TagsId` (`TagsId`),
  CONSTRAINT `FK_ProductTag_Products_ProductsId` FOREIGN KEY (`ProductsId`) REFERENCES `Products` (`Id`) ON DELETE CASCADE,
  CONSTRAINT `FK_ProductTag_Tags_TagsId` FOREIGN KEY (`TagsId`) REFERENCES `Tags` (`Id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
  • 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

using Microsoft.EntityFrameworkCore;
using Relations;

// 1 - criação do banco de dados e de um primeiro conjunto de dados, sem log
using (var context = new ShopContext(log: false))
{
    context.Database.EnsureDeleted();
    context.Database.EnsureCreated();
    // duas tags
    var promo = new Tag { Label = "promo" };
    var novelty = new Tag { Label = "new" };
    // três categorias e seus produtos: adicionamos um grafo de objetos
    context.Categories.AddRange(
        new Category
        {
            Name = "cycles",
            Products =
            [
                new Product { Name = "bike", Price = 500, Tags = [promo] },
                new Product { Name = "pump", Price = 10 },
            ]
        },
        new Category
        {
            Name = "archery",
            Products =
            [
                new Product { Name = "bow", Price = 600, Tags = [novelty] },
                new Product { Name = "arrows - set of 6", Price = 100, Tags = [promo, novelty] },
            ]
        },
        new Category { Name = "diving" });
    context.SaveChanges();
    // um cliente e seu pedido
    Product pump = context.Products.Local.Single(p => p.Name == "pump");
    Product bow = context.Products.Local.Single(p => p.Name == "bow");
    context.Clients.Add(new Client
    {
        Name = "Martin",
        Orders =
        [
            new Order
            {
                Date = new DateOnly(2026, 9, 28),
                Lines = [new OrderLine { Product = pump, Quantity = 2 }, new OrderLine { Product = bow, Quantity = 1 }]
            }
        ]
    });
    context.SaveChanges();
}

// 2 - um cliente, seu pedido e suas linhas, adicionados de uma só vez
Console.WriteLine("--- addition of a client, an order and its two lines");
using (var context = new ShopContext())
{
    Product bike = context.Products.Single(p => p.Name == "bike");
    Product arrows = context.Products.Single(p => p.Name == "arrows - set of 6");
    var client = new Client
    {
        Name = "Dupont",
        Orders =
        [
            new Order
            {
                Date = new DateOnly(2026, 10, 1),
                Lines = [new OrderLine { Product = bike, Quantity = 1 }, new OrderLine { Product = arrows, Quantity = 3 }]
            }
        ]
    };
    context.Clients.Add(client);
    context.SaveChanges();
    Console.WriteLine($"client no. {client.Id}, order no. {client.Orders[0].Id}");
}

// 3 - as propriedades de navegação não são carregadas automaticamente
Console.WriteLine("--- an order without Include");
using (var context = new ShopContext())
{
    Order order = context.Orders.First();
    Console.WriteLine($"order no. {order.Id}: client={order.Client?.Name ?? "not loaded"}, {order.Lines.Count} line(s)");
}

// 4 - carregamento dos relacionamentos com Include e ThenInclude
Console.WriteLine("--- Include and ThenInclude");
using (var context = new ShopContext())
{
    List<Order> orders = context.Orders
        .Include(c => c.Client)
        .Include(c => c.Lines).ThenInclude(l => l.Product)
        .ToList();
    foreach (Order order in orders)
    {
        Console.WriteLine($"order no. {order.Id} of {order.Date} for {order.Client.Name}");
        foreach (OrderLine line in order.Lines)
        {
            Console.WriteLine($"  {line.Quantity} x {line.Product.Name} at {line.Product.Price} euros");
        }
    }
}

// 5 - carregamento explícito de uma coleção
Console.WriteLine("--- explicit loading");
using (var context = new ShopContext())
{
    Category category = context.Categories.Single(c => c.Name == "archery");
    context.Entry(category).Collection(c => c.Products).Load();
    Console.WriteLine($"{category.Name} : {string.Join(", ", category.Products.Select(p => p.Name))}");
}

// 6 - o relacionamento muitos-para-muitos, em uma consulta
Console.WriteLine("--- the products on promotion");
using (var context = new ShopContext())
{
    var onPromo = context.Products
        .Where(p => p.Tags.Any(e => e.Label == "promo"))
        .Select(p => new { p.Name, Category = p.Category.Name })
        .ToList();
    onPromo.ForEach(p => Console.WriteLine($"{p.Name} ({p.Category})"));
}

// 7 - um cálculo através dos relacionamentos, feito pelo SGBD
Console.WriteLine("--- amount of the orders");
using (var context = new ShopContext())
{
    var amounts = context.Orders
        .Select(c => new { c.Id, Client = c.Client.Name, Amount = c.Lines.Sum(l => l.Quantity * l.Product.Price) })
        .ToList();
    amounts.ForEach(m => Console.WriteLine($"order no. {m.Id} ({m.Client}) : {m.Amount:0.00} euros"));
}

// 8 - um agrupamento: número de produtos e preço médio por categoria
Console.WriteLine("--- products per category");
using (var context = new ShopContext())
{
    var perCategory = context.Products
        .GroupBy(p => p.Category.Name)
        .Select(g => new { Category = g.Key, Count = g.Count(), AveragePrice = g.Average(p => p.Price) })
        .OrderBy(g => g.Category)
        .ToList();
    perCategory.ForEach(g => Console.WriteLine($"{g.Category} : {g.Count} product(s), average price {g.AveragePrice:0.00} euros"));
}

Resultados:

> dotnet run
--- addition of a client, an order and its two lines
    SQL> SELECT `p`.`Id`, `p`.`CategoryId`, `p`.`Name`, `p`.`Price`
    SQL> FROM `Products` AS `p`
    SQL> WHERE `p`.`Name` = 'bike'
    SQL> LIMIT 2
    SQL> SELECT `p`.`Id`, `p`.`CategoryId`, `p`.`Name`, `p`.`Price`
    SQL> FROM `Products` AS `p`
    SQL> WHERE `p`.`Name` = 'arrows - set of 6'
    SQL> LIMIT 2
    SQL> -- start of transaction
    SQL> INSERT INTO `Clients` (`Name`)
    SQL> VALUES (@p0);
    SQL> SELECT `Id`
    SQL> FROM `Clients`
    SQL> WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
    SQL> -- parameters: @p0=Dupont
    SQL> INSERT INTO `Orders` (`ClientId`, `Date`)
    SQL> VALUES (@p1, @p2);
    SQL> SELECT `Id`
    SQL> FROM `Orders`
    SQL> WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
    SQL> -- parameters: @p1=2, @p2=10/01/2026
    SQL> INSERT INTO `OrderLine` (`OrderId`, `ProductId`, `Quantity`)
    SQL> VALUES (@p3, @p4, @p5);
    SQL> SELECT `Id`
    SQL> FROM `OrderLine`
    SQL> WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
    SQL> INSERT INTO `OrderLine` (`OrderId`, `ProductId`, `Quantity`)
    SQL> VALUES (@p6, @p7, @p8);
    SQL> SELECT `Id`
    SQL> FROM `OrderLine`
    SQL> WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
    SQL> -- parameters: @p3=2, @p4=1, @p5=1, @p6=2, @p7=4, @p8=3
    SQL> -- transaction committed (COMMIT)
client no. 2, order no. 2
--- an order without Include
    SQL> SELECT `o`.`Id`, `o`.`ClientId`, `o`.`Date`
    SQL> FROM `Orders` AS `o`
    SQL> LIMIT 1
order no. 1: client=not loaded, 0 line(s)
--- Include and ThenInclude
    SQL> SELECT `o`.`Id`, `o`.`ClientId`, `o`.`Date`, `c`.`Id`, `c`.`Name`, `s`.`Id`, `s`.`OrderId`, `s`.`ProductId`, `s`.`Quantity`, `s`.`Id0`, `s`.`CategoryId`, `s`.`Name`, `s`.`Price`
    SQL> FROM `Orders` AS `o`
    SQL> INNER JOIN `Clients` AS `c` ON `o`.`ClientId` = `c`.`Id`
    SQL> LEFT JOIN (
    SQL>     SELECT `o0`.`Id`, `o0`.`OrderId`, `o0`.`ProductId`, `o0`.`Quantity`, `p`.`Id` AS `Id0`, `p`.`CategoryId`, `p`.`Name`, `p`.`Price`
    SQL>     FROM `OrderLine` AS `o0`
    SQL>     INNER JOIN `Products` AS `p` ON `o0`.`ProductId` = `p`.`Id`
    SQL> ) AS `s` ON `o`.`Id` = `s`.`OrderId`
    SQL> ORDER BY `o`.`Id`, `c`.`Id`, `s`.`Id`
order no. 1 of 09/28/2026 for Martin
  2 x pump at 10.00 euros
  1 x bow at 600.00 euros
order no. 2 of 10/01/2026 for Dupont
  1 x bike at 500.00 euros
  3 x arrows - set of 6 at 100.00 euros
--- explicit loading
    SQL> SELECT `c`.`Id`, `c`.`Name`
    SQL> FROM `Categories` AS `c`
    SQL> WHERE `c`.`Name` = 'archery'
    SQL> LIMIT 2
    SQL> SELECT `p`.`Id`, `p`.`CategoryId`, `p`.`Name`, `p`.`Price`
    SQL> FROM `Products` AS `p`
    SQL> WHERE `p`.`CategoryId` = @__p_0
    SQL> -- parameters: @__p_0=2
archery : bow, arrows - set of 6
--- the products on promotion
    SQL> SELECT `p`.`Name`, `c`.`Name` AS `Category`
    SQL> FROM `Products` AS `p`
    SQL> INNER JOIN `Categories` AS `c` ON `p`.`CategoryId` = `c`.`Id`
    SQL> WHERE EXISTS (
    SQL>     SELECT 1
    SQL>     FROM `ProductTag` AS `p0`
    SQL>     INNER JOIN `Tags` AS `t` ON `p0`.`TagsId` = `t`.`Id`
    SQL>     WHERE (`p`.`Id` = `p0`.`ProductsId`) AND (`t`.`Label` = 'promo'))
bike (cycles)
arrows - set of 6 (archery)
--- amount of the orders
    SQL> SELECT `o`.`Id`, `c`.`Name` AS `Client`, (
    SQL>     SELECT COALESCE(SUM(CAST(`o0`.`Quantity` AS decimal(65,30)) * `p`.`Price`), 0.0)
    SQL>     FROM `OrderLine` AS `o0`
    SQL>     INNER JOIN `Products` AS `p` ON `o0`.`ProductId` = `p`.`Id`
    SQL>     WHERE `o`.`Id` = `o0`.`OrderId`) AS `Amount`
    SQL> FROM `Orders` AS `o`
    SQL> INNER JOIN `Clients` AS `c` ON `o`.`ClientId` = `c`.`Id`
order no. 1 (Martin) : 620.00 euros
order no. 2 (Dupont) : 800.00 euros
--- products per category
    SQL> SELECT `c`.`Name` AS `Category`, COUNT(*) AS `Count`, AVG(`p`.`Price`) AS `AveragePrice`
    SQL> FROM `Products` AS `p`
    SQL> INNER JOIN `Categories` AS `c` ON `p`.`CategoryId` = `c`.`Id`
    SQL> GROUP BY `c`.`Name`
    SQL> ORDER BY `c`.`Name`
archery : 2 product(s), average price 350.00 euros
cycles : 2 product(s), average price 255.00 euros

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]:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!-- EF Core e seu provider MySQL (Pomelo) -->
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
    <!-- o código usado pela ferramenta [dotnet ef] (migrações): inútil em tempo de execução -->
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>
  • 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:

using System.ComponentModel.DataAnnotations;

namespace Clients;

// um cliente
public class Client
{
    public int Id { get; set; }
    [MaxLength(50)]
    public string Name { get; set; } = "";
    [MaxLength(100)]
    public string Email { get; set; } = "";
    [MaxLength(20)]
    public string? Phone { get; set; }
}

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:

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;

namespace Clients;

// o contexto recebe sua configuração por meio do construtor (construtor primário)
public class ClientsContext(DbContextOptions<ClientsContext> options) : DbContext(options)
{
    public DbSet<Client> Clients => Set<Client>();
}

// a factory de contexto usada pela ferramenta [dotnet ef] (e pelo nosso programa)
public class ClientsContextFactory : IDesignTimeDbContextFactory<ClientsContext>
{
    public ClientsContext CreateDbContext(string[] args)
    {
        const string connection = "Server=localhost;Port=3306;Database=efclients;User=root;Password=";
        var options = new DbContextOptionsBuilder<ClientsContext>()
            .UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36)))
            .Options;
        return new ClientsContext(options);
    }
}
  • 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]:

1
2
3
4
> dotnet ef migrations add Initial
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'

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]:

1
2
3
4
5
6
7
8
9
Clients/
  Clients.csproj
  Client.cs
  ClientsContext.cs
  Program.cs
  Migrations/
    20261003100720_Initial.cs               the migration
    20261003100720_Initial.Designer.cs      the model at the date of the migration
    ClientsContextModelSnapshot.cs          the snapshot of the current model

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:

using Microsoft.EntityFrameworkCore.Metadata;
using Microsoft.EntityFrameworkCore.Migrations;

#nullable disable

namespace Clients.Migrations
{
    /// <inheritdoc />
    public partial class Initial : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.AlterDatabase()
                .Annotation("MySql:CharSet", "utf8mb4");

            migrationBuilder.CreateTable(
                name: "Clients",
                columns: table => new
                {
                    Id = table.Column<int>(type: "int", nullable: false)
                        .Annotation("MySql:ValueGenerationStrategy", MySqlValueGenerationStrategy.IdentityColumn),
                    Name = table.Column<string>(type: "varchar(50)", maxLength: 50, nullable: false)
                        .Annotation("MySql:CharSet", "utf8mb4"),
                    Email = table.Column<string>(type: "varchar(100)", maxLength: 100, nullable: false)
                        .Annotation("MySql:CharSet", "utf8mb4")
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Clients", x => x.Id);
                })
                .Annotation("MySql:CharSet", "utf8mb4");
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropTable(
                name: "Clients");
        }
    }
}
  • 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:

1
2
3
4
5
6
> dotnet ef database update Initial
Build started...
Build succeeded.
Acquiring an exclusive lock for migration application. See https://aka.ms/efcore-docs-migrations-lock for more information if this takes too long.
Applying migration '20261003100720_Initial'.
Done.

O banco de dados [efclients] não existia: ele foi criado. O cliente [mysql] do MySQL mostra suas tabelas:

> mysql -uroot -t efclients -e "SHOW TABLES; DESCRIBE Clients;"
+-----------------------+
| Tables_in_efclients   |
+-----------------------+
| Clients               |
| __EFMigrationsHistory |
+-----------------------+
+-------+--------------+------+-----+---------+----------------+
| Field | Type         | Null | Key | Default | Extra          |
+-------+--------------+------+-----+---------+----------------+
| Id    | int          | NO   | PRI | NULL    | auto_increment |
| Name  | varchar(50)  | NO   |     | NULL    |                |
| Email | varchar(100) | NO   |     | NULL    |                |
+-------+--------------+------+-----+---------+----------------+

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:

1
2
3
4
> dotnet ef migrations add AddPhone
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'

A ferramenta comparou o modelo atual com o snapshot e gerou a seguinte migração:

using Microsoft.EntityFrameworkCore.Migrations;

#nullable disable

namespace Clients.Migrations
{
    /// <inheritdoc />
    public partial class AddPhone : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.AddColumn<string>(
                name: "Phone",
                table: "Clients",
                type: "varchar(20)",
                maxLength: 20,
                nullable: true)
                .Annotation("MySql:CharSet", "utf8mb4");
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropColumn(
                name: "Phone",
                table: "Clients");
        }
    }
}
  • 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:

    [DbContext(typeof(ClientsContext))]
    partial class ClientsContextModelSnapshot : ModelSnapshot
    {
        protected override void BuildModel(ModelBuilder modelBuilder)
        {
#pragma warning disable 612, 618
            modelBuilder
                .HasAnnotation("ProductVersion", "9.0.0")
                .HasAnnotation("Relational:MaxIdentifierLength", 64);

            MySqlModelBuilderExtensions.AutoIncrementColumns(modelBuilder);

            modelBuilder.Entity("Clients.Client", b =>
                {
                    b.Property<int>("Id")
                        .ValueGeneratedOnAdd()
                        .HasColumnType("int");

                    MySqlPropertyBuilderExtensions.UseMySqlIdentityColumn(b.Property<int>("Id"));

                    b.Property<string>("Email")
                        .IsRequired()
                        .HasMaxLength(100)
                        .HasColumnType("varchar(100)");

                    b.Property<string>("Name")
                        .IsRequired()
                        .HasMaxLength(50)
                        .HasColumnType("varchar(50)");

                    b.Property<string>("Phone")
                        .HasMaxLength(20)
                        .HasColumnType("varchar(20)");

                    b.HasKey("Id");

                    b.ToTable("Clients");
                });
  • 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:

1
2
3
4
5
> dotnet ef migrations list
Build started...
Build succeeded.
20261003100720_Initial
20261003100726_AddPhone (Pending)

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:

> dotnet ef migrations script Initial AddPhone
Build started...
Build succeeded.
START TRANSACTION;
ALTER TABLE `Clients` ADD `Phone` varchar(20) CHARACTER SET utf8mb4 NULL;

INSERT INTO `__EFMigrationsHistory` (`MigrationId`, `ProductVersion`)
VALUES ('20261003100726_AddPhone', '9.0.0');

COMMIT;
  • 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]:

using Clients;
using Microsoft.EntityFrameworkCore;

// o contexto é criado pela mesma factory que a da ferramenta [dotnet ef]
using ClientsContext context = new ClientsContextFactory().CreateDbContext(args);

// o estado das migrações
Console.WriteLine($"applied migrations: {string.Join(", ", context.Database.GetAppliedMigrations())}");
Console.WriteLine($"pending migrations: {string.Join(", ", context.Database.GetPendingMigrations())}");

// aplicação das migrações pendentes
context.Database.Migrate();
Console.WriteLine("Migrate(): the database is up to date");

// a nova coluna é utilizável
context.Clients.Add(new Client { Name = "Dupont", Email = "dupont@example.com", Phone = "01 23 45 67 89" });
context.SaveChanges();
foreach (Client client in context.Clients.AsNoTracking())
{
    Console.WriteLine($"[{client.Id}, {client.Name}, {client.Email}, {client.Phone ?? "no phone"}]");
}
  • 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:

1
2
3
4
5
> dotnet run
applied migrations: 20261003100720_Initial
pending migrations: 20261003100726_AddPhone
Migrate(): the database is up to date
[1, Dupont, dupont@example.com, 01 23 45 67 89]

A segunda migração foi aplicada pelo programa. A tabela de histórico agora contém as duas migrações:

1
2
3
4
5
6
7
> mysql -uroot -t efclients -e "SELECT * FROM __EFMigrationsHistory"
+-------------------------+----------------+
| MigrationId             | ProductVersion |
+-------------------------+----------------+
| 20261003100720_Initial  | 9.0.0          |
| 20261003100726_AddPhone | 9.0.0          |
+-------------------------+----------------+

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:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// o banco de dados é recriado com seus seis artigos
ArticlesContext.Initialize();
// o contexto é liberado de forma assíncrona (await using)
await using var context = new ArticlesContext();

// 1 - consultas assíncronas
Console.WriteLine("--- ToListAsync");
List<Article> articles = await context.Articles.Where(a => a.Price < 200).OrderBy(a => a.Price).ToListAsync();
articles.ForEach(Console.WriteLine);
Console.WriteLine("--- FirstOrDefaultAsync and CountAsync");
Article? bow = await context.Articles.FirstOrDefaultAsync(a => a.Name == "bow");
int nbOutOfStock = await context.Articles.CountAsync(a => a.CurrentStock < a.MinimumStock);
Console.WriteLine($"{bow}, {nbOutOfStock} article(s) out of stock");

// 2 - salvamento assíncrono
Console.WriteLine("--- SaveChangesAsync");
bow!.Price = 550;
int nbRows = await context.SaveChangesAsync();
Console.WriteLine($"{nbRows} row(s) modified");

// 3 - um fluxo assíncrono: as linhas são processadas à medida que são lidas
Console.WriteLine("--- await foreach");
await foreach (Article article in context.Articles.AsNoTracking().Where(a => a.Price >= 300).AsAsyncEnumerable())
{
    Console.WriteLine($"read: {article.Name}");
}

// 4 - cancelamento
Console.WriteLine("--- cancellation");
using var cancellation = new CancellationTokenSource();
cancellation.Cancel();
try
{
    await context.Articles.ToListAsync(cancellation.Token);
}
catch (OperationCanceledException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}

Resultados:

> dotnet run
--- ToListAsync
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Price` < 200.0
    SQL> ORDER BY `a`.`Price`
[2, pump, 10.00, 10, 2]
[4, arrows - set of 6, 100.00, 12, 20]
[6, diver's oxygen tanks, 120.00, 10, 5]
--- FirstOrDefaultAsync and CountAsync
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Name` = 'bow'
    SQL> LIMIT 1
    SQL> SELECT COUNT(*)
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`CurrentStock` < `a`.`MinimumStock`
[3, bow, 600.00, 4, 1], 1 article(s) out of stock
--- SaveChangesAsync
    SQL> SET AUTOCOMMIT = 1;
    SQL> UPDATE `articles` SET `Price` = @p0
    SQL> WHERE `Id` = @p1;
    SQL> SELECT ROW_COUNT();
    SQL> -- parameters: @p1=3, @p0=550
1 row(s) modified
--- await foreach
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Price` >= 300.0
read: bike
read: bow
read: diving suit
--- cancellation
OperationCanceledException : The operation was canceled.

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:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// o banco de dados é recriado com seus seis artigos
ArticlesContext.Initialize();

// 1 - SaveChanges é transacional: tudo ou nada
Console.WriteLine("--- SaveChanges: two additions, the second violating the uniqueness of the name");
using (var context = new ArticlesContext())
{
    context.Articles.Add(new Article { Name = "racket", Price = 80, CurrentStock = 5, MinimumStock = 2 });
    context.Articles.Add(new Article { Name = "bike", Price = 450, CurrentStock = 3, MinimumStock = 1 });
    try
    {
        context.SaveChanges();
    }
    catch (DbUpdateException e)
    {
        // o erro do SGBD é a exceção interna
        Console.WriteLine($"{e.GetType().Name} : {e.InnerException?.Message}");
    }
}
await DisplayAsync("racket");

// 2 - uma transação explícita que abrange vários SaveChanges
Console.WriteLine("--- explicit transaction rolled back");
await using (var context = new ArticlesContext())
{
    await using var transaction = await context.Database.BeginTransactionAsync();
    try
    {
        // venda de duas bicicletas
        Article bike = await context.Articles.SingleAsync(a => a.Name == "bike");
        bike.CurrentStock -= 2;
        await context.SaveChangesAsync();
        // adição de um artigo cujo nome já existe: erro
        context.Articles.Add(new Article { Name = "pump", Price = 12, CurrentStock = 5, MinimumStock = 1 });
        await context.SaveChangesAsync();
        // commit do conjunto (não chegamos até aqui)
        await transaction.CommitAsync();
    }
    catch (DbUpdateException e)
    {
        Console.WriteLine($"{e.GetType().Name} : {e.InnerException?.Message}");
        // cancelamento de todas as operações da transação
        await transaction.RollbackAsync();
    }
}
// a venda das bicicletas foi cancelada
await DisplayAsync("bike");

// exibição de um artigo lido do banco de dados, com um novo contexto
static async Task DisplayAsync(string name)
{
    await using var context = new ArticlesContext();
    Article? article = await context.Articles.AsNoTracking().SingleOrDefaultAsync(a => a.Name == name);
    Console.WriteLine($"article [{name}] in the database: {article?.ToString() ?? "missing"}");
}

Resultados:

> dotnet run
--- SaveChanges: two additions, the second violating the uniqueness of the name
    SQL> -- start of transaction
    SQL> INSERT INTO `articles` (`CurrentStock`, `MinimumStock`, `Name`, `Price`)
    SQL> VALUES (@p0, @p1, @p2, @p3);
    SQL> SELECT `Id`
    SQL> FROM `articles`
    SQL> WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
    SQL> INSERT INTO `articles` (`CurrentStock`, `MinimumStock`, `Name`, `Price`)
    SQL> VALUES (@p4, @p5, @p6, @p7);
    SQL> SELECT `Id`
    SQL> FROM `articles`
    SQL> WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
    SQL> -- parameters: @p0=5, @p1=2, @p2=racket, @p3=80, @p4=3, @p5=1, @p6=bike, @p7=450
DbUpdateException : Duplicate entry 'bike' for key 'articles.IX_articles_Name'
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Name` = @__name_0
    SQL> LIMIT 2
    SQL> -- parameters: @__name_0=racket
article [racket] in the database: missing
--- explicit transaction rolled back
    SQL> -- start of transaction
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Name` = 'bike'
    SQL> LIMIT 2
    SQL> SET AUTOCOMMIT = 1;
    SQL> UPDATE `articles` SET `CurrentStock` = @p0
    SQL> WHERE `Id` = @p1;
    SQL> SELECT ROW_COUNT();
    SQL> -- parameters: @p1=1, @p0=8
    SQL> INSERT INTO `articles` (`CurrentStock`, `MinimumStock`, `Name`, `Price`)
    SQL> VALUES (@p0, @p1, @p2, @p3);
    SQL> SELECT `Id`
    SQL> FROM `articles`
    SQL> WHERE ROW_COUNT() = 1 AND `Id` = LAST_INSERT_ID();
    SQL> -- parameters: @p0=5, @p1=1, @p2=pump, @p3=12
    SQL> -- command failed
DbUpdateException : Duplicate entry 'pump' for key 'articles.IX_articles_Name'
    SQL> -- transaction rolled back (ROLLBACK)
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Name` = @__name_0
    SQL> LIMIT 2
    SQL> -- parameters: @__name_0=bike
article [bike] in the database: [1, bike, 500.00, 10, 5]

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:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

namespace Concurrency;

// o contexto de artigos, em que o estoque se torna um token de concorrência
public class ArticlesConcurrencyContext : ArticlesContext
{
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        // o valor lido para o estoque será verificado em cada UPDATE ou DELETE
        modelBuilder.Entity<Article>().Property(a => a.CurrentStock).IsConcurrencyToken();
    }
}
  • 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:

using Articles.Data;
using Concurrency;
using Microsoft.EntityFrameworkCore;

// o banco de dados é recriado com seus seis artigos
ArticlesContext.Initialize();

// dois usuários, dois contextos: cada um lê o mesmo artigo
using var context1 = new ArticlesConcurrencyContext();
using var context2 = new ArticlesConcurrencyContext();
Console.WriteLine("--- both users read the bike");
Article bike1 = context1.Articles.Single(a => a.Name == "bike");
Article bike2 = context2.Articles.Single(a => a.Name == "bike");

// o usuário 1 vende 1 bicicleta
Console.WriteLine("--- user 1 sells 1 bike");
bike1.CurrentStock -= 1;
context1.SaveChanges();
Console.WriteLine($"stock saved by user 1: {bike1.CurrentStock}");

// o usuário 2 vende 3 bicicletas com dados desatualizados (estoque = 10)
Console.WriteLine("--- user 2 sells 3 bikes");
bike2.CurrentStock -= 3;
try
{
    context2.SaveChanges();
}
catch (DbUpdateConcurrencyException e)
{
    // exibimos apenas a primeira frase da mensagem
    Console.WriteLine($"{e.GetType().Name} : {e.Message[..(e.Message.IndexOf('.') + 1)]}");
    // resolução: relemos o artigo do banco de dados e refazemos a venda
    Console.WriteLine("--- user 2 rereads the bike and starts again");
    foreach (var entry in e.Entries)
    {
        entry.Reload();
    }
    Console.WriteLine($"stock reread: {bike2.CurrentStock}");
    bike2.CurrentStock -= 3;
    context2.SaveChanges();
    Console.WriteLine($"stock saved by user 2: {bike2.CurrentStock}");
}

Resultados:

> dotnet run
--- both users read the bike
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Name` = 'bike'
    SQL> LIMIT 2
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Name` = 'bike'
    SQL> LIMIT 2
--- user 1 sells 1 bike
    SQL> SET AUTOCOMMIT = 1;
    SQL> UPDATE `articles` SET `CurrentStock` = @p0
    SQL> WHERE `Id` = @p1 AND `CurrentStock` = @p2;
    SQL> SELECT ROW_COUNT();
    SQL> -- parameters: @p1=1, @p0=9, @p2=10
stock saved by user 1: 9
--- user 2 sells 3 bikes
    SQL> SET AUTOCOMMIT = 1;
    SQL> UPDATE `articles` SET `CurrentStock` = @p0
    SQL> WHERE `Id` = @p1 AND `CurrentStock` = @p2;
    SQL> SELECT ROW_COUNT();
    SQL> -- parameters: @p1=1, @p0=7, @p2=10
DbUpdateConcurrencyException : The database operation was expected to affect 1 row(s), but actually affected 0 row(s); data may have been modified or deleted since entities were loaded.
--- user 2 rereads the bike and starts again
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM `articles` AS `a`
    SQL> WHERE `a`.`Id` = @__p_0
    SQL> LIMIT 1
    SQL> -- parameters: @__p_0=1
stock reread: 9
    SQL> SET AUTOCOMMIT = 1;
    SQL> UPDATE `articles` SET `CurrentStock` = @p0
    SQL> WHERE `Id` = @p1 AND `CurrentStock` = @p2;
    SQL> SELECT ROW_COUNT();
    SQL> -- parameters: @p1=1, @p0=6, @p2=9
stock saved by user 2: 6

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:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// o banco de dados é recriado com seus seis artigos
ArticlesContext.Initialize();
using var context = new ArticlesContext();

// 1 - FromSql: uma consulta SQL escrita à mão que retorna entidades
Console.WriteLine("--- FromSql");
decimal minPrice = 200;
List<Article> expensive = context.Articles
    .FromSql($"SELECT * FROM articles WHERE Price > {minPrice}")
    .OrderBy(a => a.Name)
    .ToList();
expensive.ForEach(Console.WriteLine);

// 2 - a interpolação produz um parâmetro: injeção de SQL impossível
Console.WriteLine("--- SQL injection attempt with FromSql");
string name = "x' OR '1'='1";
int nb = context.Articles.FromSql($"SELECT * FROM articles WHERE Name = {name}").Count();
Console.WriteLine($"{nb} article(s) found");
// a mesma consulta construída por concatenação: nunca faça isso
Console.WriteLine("--- the same attempt with FromSqlRaw and a concatenation");
nb = context.Articles.FromSqlRaw("SELECT * FROM articles WHERE Name = '" + name + "'").Count();
Console.WriteLine($"{nb} article(s) found");

// 3 - SqlQuery: resultados que não são entidades (a coluna se chama Value)
Console.WriteLine("--- SqlQuery");
List<string> names = context.Database
    .SqlQuery<string>($"SELECT Name AS Value FROM articles WHERE CurrentStock < MinimumStock")
    .ToList();
Console.WriteLine($"out of stock: {string.Join(", ", names)}");
decimal value = context.Database
    .SqlQuery<decimal>($"SELECT SUM(Price * CurrentStock) AS Value FROM articles")
    .Single();
Console.WriteLine($"stock value: {value} euros");

// 4 - ExecuteSql: uma instrução de atualização
Console.WriteLine("--- ExecuteSql");
decimal coefficient = 0.9M;
string article = "bow";
int nbRows = context.Database.ExecuteSql($"UPDATE articles SET Price = Price * {coefficient} WHERE Name = {article}");
Console.WriteLine($"{nbRows} row(s) modified");

Resultados:

> dotnet run
--- FromSql
    SQL> SELECT `a`.`Id`, `a`.`CurrentStock`, `a`.`MinimumStock`, `a`.`Name`, `a`.`Price`
    SQL> FROM (
    SQL>     SELECT * FROM articles WHERE Price > @p0
    SQL> ) AS `a`
    SQL> ORDER BY `a`.`Name`
    SQL> -- parameters: @p0=200
[1, bike, 500.00, 10, 5]
[3, bow, 600.00, 4, 1]
[5, diving suit, 300.00, 8, 2]
--- SQL injection attempt with FromSql
    SQL> SELECT COUNT(*)
    SQL> FROM (
    SQL>     SELECT * FROM articles WHERE Name = @p0
    SQL> ) AS `a`
    SQL> -- parameters: @p0=x' OR '1'='1
0 article(s) found
--- the same attempt with FromSqlRaw and a concatenation
    SQL> SELECT COUNT(*)
    SQL> FROM (
    SQL>     SELECT * FROM articles WHERE Name = 'x' OR '1'='1'
    SQL> ) AS `a`
6 article(s) found
--- SqlQuery
    SQL> SELECT Name AS Value FROM articles WHERE CurrentStock < MinimumStock
out of stock: arrows - set of 6
    SQL> SELECT `s`.`Value`
    SQL> FROM (
    SQL>     SELECT SUM(Price * CurrentStock) AS Value FROM articles
    SQL> ) AS `s`
    SQL> LIMIT 2
stock value: 12300.00 euros
--- ExecuteSql
    SQL> UPDATE articles SET Price = Price * @p0 WHERE Name = @p1
    SQL> -- parameters: @p0=0.9, @p1=bow
1 row(s) modified

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:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

namespace Injection;

// um serviço que recebe o contexto por injeção: seu tempo de vida é o do contexto
public class ArticlesDao(ArticlesContext context)
{
    // os artigos a reabastecer
    public List<string> ArticlesOutOfStock() =>
        context.Articles.Where(a => a.CurrentStock < a.MinimumStock).Select(a => a.Name).ToList();
}

// um serviço de longa duração: ele recebe uma factory de contexto
public class StatisticsService(IDbContextFactory<ArticlesContext> factory)
{
    // cada chamada usa um novo contexto, liberado imediatamente
    public async Task<decimal> StockValueAsync()
    {
        await using ArticlesContext context = await factory.CreateDbContextAsync();
        return await context.Articles.SumAsync(a => a.Price * a.CurrentStock);
    }
}
  • 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:

using Articles.Data;
using Injection;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;

// o banco de dados é recriado com seus seis artigos
ArticlesContext.Initialize();

// 1 - AddDbContext: o contexto é registrado com tempo de vida "scoped"
var services = new ServiceCollection();
services.AddDbContext<ArticlesContext>(options =>
    options.UseMySql(ArticlesContext.Connection, ArticlesContext.MySqlVersion));
services.AddScoped<ArticlesDao>();
using ServiceProvider provider = services.BuildServiceProvider();

ArticlesContext contextOfScope1;
using (IServiceScope scope = provider.CreateScope())
{
    // dentro de um mesmo escopo, sempre obtemos o mesmo contexto
    contextOfScope1 = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
    var context = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
    Console.WriteLine($"scope 1: same context = {ReferenceEquals(context, contextOfScope1)}");
    // o serviço [ArticlesDao] recebeu este contexto
    var dao = scope.ServiceProvider.GetRequiredService<ArticlesDao>();
    Console.WriteLine($"scope 1: out of stock = {string.Join(", ", dao.ArticlesOutOfStock())}");
}
using (IServiceScope scope = provider.CreateScope())
{
    // outro escopo: outro contexto
    var context = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
    Console.WriteLine($"scope 2: same context as in scope 1 = {ReferenceEquals(context, contextOfScope1)}");
}
// no fim de seu escopo, o contexto foi liberado
try
{
    contextOfScope1.Articles.Count();
}
catch (ObjectDisposedException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message[..(e.Message.IndexOf('.') + 1)]}");
}

// 2 - AddDbContextFactory: uma factory de contexto para um serviço de longa duração
var services2 = new ServiceCollection();
services2.AddDbContextFactory<ArticlesContext>(options =>
    options.UseMySql(ArticlesContext.Connection, ArticlesContext.MySqlVersion));
services2.AddSingleton<StatisticsService>();
using ServiceProvider provider2 = services2.BuildServiceProvider();
var statistics = provider2.GetRequiredService<StatisticsService>();
Console.WriteLine($"stock value: {await statistics.StockValueAsync():0.00} euros");

Resultados:

1
2
3
4
5
6
> dotnet run
scope 1: same context = True
scope 1: out of stock = arrows - set of 6
scope 2: same context as in scope 1 = False
ObjectDisposedException : Cannot access a disposed context instance.
stock value: 12300.00 euros

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.

Image

A solução inclui dois novos projetos na pasta [11-efcore/TaxV7]:

TaxV7/
  Tax.Dao.Ef/                    library: the EF Core [dao] layer
    Tax.Dao.Ef.csproj
    TaxBracketEntity.cs          the persistence entity
    TaxContext.cs                the context, with the seed data
    TaxContextFactory.cs         the factory used by [dotnet ef]
    EfTax.cs                     the implementation of ITaxDao
    Migrations/
      20261003100850_Initial.cs
      20261003100850_Initial.Designer.cs
      TaxContextModelSnapshot.cs
  Tax.Ui.Ef/                     executable: integration of the layers
    Tax.Ui.Ef.csproj
    Program.cs
    tax-ef.json
    tax-ef-error.json

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]:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!-- a camada [dao] da versão 5: entidades, interface ITaxDao, HardwiredTax -->
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Dao/Tax.Dao.csproj" />
  </ItemGroup>

  <ItemGroup>
    <!-- EF Core e seu provider MySQL -->
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
    <!-- para a ferramenta [dotnet ef] (migrações) -->
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>
  • 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:

using System.ComponentModel.DataAnnotations.Schema;

namespace Dao;

// uma faixa de imposto como é armazenada no banco de dados: uma entidade do EF Core
[Table("brackets")]
public class TaxBracketEntity
{
    // a chave primária, que não existe em Entities.TaxBracket
    public int Id { get; set; }

    [Column("limits", TypeName = "decimal(10,2)")]
    public decimal Limit { get; set; }

    [Column("coeffr", TypeName = "decimal(6,4)")]
    public decimal CoeffR { get; set; }

    [Column("coeffn", TypeName = "decimal(10,2)")]
    public decimal CoeffN { get; set; }
}
  • 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:

using Microsoft.EntityFrameworkCore;

namespace Dao;

// o contexto do banco de dados [eftaxes]: ele recebe sua configuração por meio do construtor
public class TaxContext(DbContextOptions<TaxContext> options) : DbContext(options)
{
    // a tabela das faixas de imposto
    public DbSet<TaxBracketEntity> Brackets => Set<TaxBracketEntity>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // dados iniciais (seed): as faixas da classe HardwiredTax (versão 5),
        // numeradas a partir de 1; elas serão inseridas pela migração
        TaxBracketEntity[] brackets = new HardwiredTax().TaxBrackets
            .Select((t, i) => new TaxBracketEntity { Id = i + 1, Limit = t.Limit, CoeffR = t.CoeffR, CoeffN = t.CoeffN })
            .ToArray();
        modelBuilder.Entity<TaxBracketEntity>().HasData(brackets);
    }
}
  • 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]:

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;

namespace Dao;

// a factory usada pela ferramenta [dotnet ef] para criar o contexto (migrações)
public class TaxContextFactory : IDesignTimeDbContextFactory<TaxContext>
{
    public TaxContext CreateDbContext(string[] args)
    {
        // o banco de dados de desenvolvimento; em tempo de execução, a string vem da configuração
        const string connection = "Server=localhost;Port=3306;Database=eftaxes;User=root;Password=";
        var options = new DbContextOptionsBuilder<TaxContext>()
            .UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36)))
            .Options;
        return new TaxContext(options);
    }
}

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]:

using System.Data.Common;
using Entities;
using Microsoft.EntityFrameworkCore;

namespace Dao;

// uma camada [dao] que lê as faixas de imposto de um banco de dados com EF Core
public class EfTax : ITaxDao
{
    // códigos de erro específicos desta implementação
    public enum ErrorCodes { Access = 1, EmptyTable = 2 }

    // faixas de imposto
    public TaxBracket[] TaxBrackets { get; }

    // construtor: a factory de contexto é injetada
    public EfTax(IDbContextFactory<TaxContext> factory)
    {
        try
        {
            // um contexto de curta duração, o tempo de ler a tabela
            using TaxContext context = factory.CreateDbContext();
            // as entidades de persistência são projetadas nas entidades da aplicação
            TaxBrackets = context.Brackets
                .AsNoTracking()
                .OrderBy(t => t.Id)
                .Select(t => new TaxBracket(t.Limit, t.CoeffR, t.CoeffN))
                .ToArray();
        }
        catch (DbException e)
        {
            // erro do SGBD: o encapsulamos em uma TaxException
            throw new TaxException("Error while reading the tax brackets from the database", e)
            {
                Code = (int)ErrorCodes.Access
            };
        }
        // a camada [business] precisa de pelo menos uma faixa
        if (TaxBrackets.Length == 0)
        {
            throw new TaxException("The tax brackets table is empty") { Code = (int)ErrorCodes.EmptyTable };
        }
    }
}
  • 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:

using Microsoft.EntityFrameworkCore.Metadata;
using Microsoft.EntityFrameworkCore.Migrations;

#nullable disable

#pragma warning disable CA1814 // Prefira arrays irregulares (jagged) a multidimensionais

namespace Tax.Dao.Ef.Migrations
{
    /// <inheritdoc />
    public partial class Initial : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.AlterDatabase()
                .Annotation("MySql:CharSet", "utf8mb4");

            migrationBuilder.CreateTable(
                name: "brackets",
                columns: table => new
                {
                    Id = table.Column<int>(type: "int", nullable: false)
                        .Annotation("MySql:ValueGenerationStrategy", MySqlValueGenerationStrategy.IdentityColumn),
                    limits = table.Column<decimal>(type: "decimal(10,2)", nullable: false),
                    coeffr = table.Column<decimal>(type: "decimal(6,4)", nullable: false),
                    coeffn = table.Column<decimal>(type: "decimal(10,2)", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_brackets", x => x.Id);
                })
                .Annotation("MySql:CharSet", "utf8mb4");

            migrationBuilder.InsertData(
                table: "brackets",
                columns: new[] { "Id", "coeffn", "coeffr", "limits" },
                values: new object[,]
                {
                    { 1, 0m, 0m, 4962m },
                    { 2, 291.09m, 0.068m, 8382m },
                    { 3, 1322.92m, 0.191m, 14753m },
                    { 4, 2668.39m, 0.283m, 23888m },
                    { 5, 4846.98m, 0.374m, 38868m },
                    { 6, 6883.66m, 0.426m, 47932m },
                    { 7, 9505.54m, 0.481m, 0m }
                });
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropTable(
                name: "brackets");
        }
    }
}
  • 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:

> dotnet ef migrations script
Build started...
Build succeeded.
CREATE TABLE IF NOT EXISTS `__EFMigrationsHistory` (
    `MigrationId` varchar(150) CHARACTER SET utf8mb4 NOT NULL,
    `ProductVersion` varchar(32) CHARACTER SET utf8mb4 NOT NULL,
    CONSTRAINT `PK___EFMigrationsHistory` PRIMARY KEY (`MigrationId`)
) CHARACTER SET=utf8mb4;

START TRANSACTION;
ALTER DATABASE CHARACTER SET utf8mb4;

CREATE TABLE `brackets` (
    `Id` int NOT NULL AUTO_INCREMENT,
    `limits` decimal(10,2) NOT NULL,
    `coeffr` decimal(6,4) NOT NULL,
    `coeffn` decimal(10,2) NOT NULL,
    CONSTRAINT `PK_brackets` PRIMARY KEY (`Id`)
) CHARACTER SET=utf8mb4;

INSERT INTO `brackets` (`Id`, `coeffn`, `coeffr`, `limits`)
VALUES (1, 0.0, 0.0, 4962.0),
(2, 291.09, 0.068, 8382.0),
(3, 1322.92, 0.191, 14753.0),
(4, 2668.39, 0.283, 23888.0),
(5, 4846.98, 0.374, 38868.0),
(6, 6883.66, 0.426, 47932.0),
(7, 9505.54, 0.481, 0.0);

INSERT INTO `__EFMigrationsHistory` (`MigrationId`, `ProductVersion`)
VALUES ('20261003100850_Initial', '9.0.0');

COMMIT;

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:

1
2
3
4
5
6
> dotnet ef database update
Build started...
Build succeeded.
Acquiring an exclusive lock for migration application. See https://aka.ms/efcore-docs-migrations-lock for more information if this takes too long.
Applying migration '20261003100850_Initial'.
Done.

e verifica-se o conteúdo da tabela:

> mysql -uroot -t eftaxes -e "SELECT * FROM brackets"
+----+----------+--------+---------+
| Id | limits   | coeffr | coeffn  |
+----+----------+--------+---------+
|  1 |  4962.00 | 0.0000 |    0.00 |
|  2 |  8382.00 | 0.0680 |  291.09 |
|  3 | 14753.00 | 0.1910 | 1322.92 |
|  4 | 23888.00 | 0.2830 | 2668.39 |
|  5 | 38868.00 | 0.3740 | 4846.98 |
|  6 | 47932.00 | 0.4260 | 6883.66 |
|  7 |     0.00 | 0.4810 | 9505.54 |
+----+----------+--------+---------+

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:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!-- as camadas [business] e [ui] da versão 5, inalteradas -->
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Business/Tax.Business.csproj" />
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Ui/Tax.Ui.csproj" />
    <!-- a nova camada [dao] -->
    <ProjectReference Include="../Tax.Dao.Ef/Tax.Dao.Ef.csproj" />
  </ItemGroup>

  <ItemGroup>
    <!-- contêiner de injeção de dependência e configuração JSON -->
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.12" />
  </ItemGroup>

  <ItemGroup>
    <!-- os arquivos de configuração são copiados ao lado do executável -->
    <None Update="tax-ef*.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

</Project>
  • 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:

1
2
3
4
5
{
  "ConnectionStrings": {
    "Tax": "Server=localhost;Port=3306;Database=eftaxes;User=root;Password="
  }
}

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]:

using Dao;
using Entities;
using Business;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Ui;

// o arquivo de configuração: tax-ef.json por padrão, ou o passado como argumento
string configFile = args.Length > 0 ? args[0] : "tax-ef.json";

// integração das camadas
ITaxBusiness business;
try
{
    // leitura da configuração, ao lado do executável
    IConfiguration config = new ConfigurationBuilder()
        .SetBasePath(AppContext.BaseDirectory)
        .AddJsonFile(configFile, optional: false)
        .Build();
    string connection = config.GetConnectionString("Tax")
        ?? throw new TaxException($"Connection string [Tax] missing from the file {configFile}");

    // registro das camadas no contêiner
    var services = new ServiceCollection();
    // uma factory de contexto do EF Core, configurada para MySQL
    services.AddDbContextFactory<TaxContext>(options =>
        options.UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36))));
    // a camada [dao]: EfTax receberá a factory
    services.AddSingleton<ITaxDao, EfTax>();
    // a camada [business]: ela receberá a camada [dao]
    services.AddSingleton<ITaxBusiness, TaxBusiness>();

    // criação do contêiner, depois da camada [business] (e portanto da camada [dao])
    ServiceProvider provider = services.BuildServiceProvider();
    business = provider.GetRequiredService<ITaxBusiness>();
}
catch (Exception e)
{
    // exibição do erro e fim do programa
    Dialog.DisplayError(e);
    return 1;
}

// o diálogo com o usuário, o da versão 5
Dialog.Run(business);
return 0;
  • 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

1
2
3
4
5
6
7
8
> dotnet run
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

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:

1
2
3
4
5
6
7
> dotnet run -- tax-ef-error.json
Exception chain:
----------------------------------------
Entities.TaxException: Error while reading the tax brackets from the database
----------------------------------------
MySqlConnector.MySqlException: Unknown database 'eftaxesmissing'
----------------------------------------
  • 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.