Skip to content

11. Entity Framework Core

El capítulo anterior mostró cómo una aplicación .NET se comunica con una base de datos a través de un conector ADO.NET: se abre una conexión, se escriben comandos SQL, se leen las filas del resultado columna por columna y se copian en objetos. Este proceso de copia —de filas a objetos y de objetos a los comandos [INSERT], [UPDATE] y [DELETE] — es repetitivo. Se puede automatizar mediante una herramienta: un ORM (Object-Relational Mapper, mapeador objeto-relacional). Este capítulo presenta Entity Framework Core (EF Core) de Microsoft.

El curso de 2008 no mencionaba los ORM: se limitaba a citar, en la conclusión de su capítulo sobre bases de datos, los “frameworks de acceso a datos de terceros” (NHibernate, iBatis) y LINQ. Entity Framework se lanzó unos meses después (en 2008, con .NET 3.5 SP1) y, en 2012, el autor le dedicó un curso titulado “Introduction to Entity Framework 5 Code First Through Examples”. Este capítulo es completamente nuevo. Se apoya en la base de datos de ejemplo de los artículos del Capítulo 10 y concluye con la versión 7 de la aplicación de cálculo de impuestos, cuya capa [dao] utiliza EF Core.

11.1. ¿Qué es un ORM?

11.1.1. Objetos y tablas

Una aplicación C# trabaja con objetos: un artículo tiene un nombre, un precio y un nivel de existencias; un pedido tiene un cliente y una lista de líneas, cada una de las cuales hace referencia a un artículo. Una base de datos relacional almacena esta misma información en tablas: una fila en la tabla [articles] por artículo, una fila en la tabla [orders] por pedido, con las relaciones entre filas expresadas mediante claves externas. Los dos mundos no coinciden del todo:

  • un objeto hace referencia directamente a otros objetos ([order.Client]); una fila contiene el valor de la clave primaria de otra fila ([ClientId]);
  • un objeto puede contener una colección ([order.Lines]); una tabla solo contiene valores simples; la colección se representa mediante las filas de otra tabla que apuntan al pedido;
  • los tipos de C# ([string], [decimal], [DateOnly], [bool]) y los tipos de SQL ([varchar(30)], [decimal(10,2)], [date], [tinyint(1)]) no son los mismos;
  • los objetos se consultan con C# (y LINQ), y las tablas se consultan con SQL.

Un ORM tiende un puente entre los dos mundos. Se define de una vez por todas la correspondencia entre clases y tablas (el modelo) y el ORM se encarga de:

  • traducir las consultas LINQ escritas en C# a comandos SQL [SELECT];
  • crear objetos a partir de las filas leídas (esto se denomina materialización);
  • almacenar los objetos leídos y detectar cuáles han sido modificados, agregados o eliminados;
  • generar los comandos [INSERT], [UPDATE] y [DELETE] que reflejan esos cambios en la base de datos;
  • y, si es necesario, crear y actualizar el esquema de la base de datos (tablas, columnas, índices) a partir de las clases.

La arquitectura de una aplicación que utiliza EF Core con MySQL es la siguiente:

Image

  • [1]: la aplicación. Su capa [dao] ya no se comunica con un conector ADO.NET sino con EF Core, mediante un objeto [DbContext] y consultas LINQ;
  • [2]: EF Core, independiente del SGBD: modelo, traducción de las consultas LINQ, seguimiento de cambios, migraciones;
  • [3]: el proveedor de EF Core específico del SGBD (aquí Pomelo para MySQL): conoce el dialecto SQL del SGBD y sus tipos de columna;
  • [4]: el conector ADO.NET del SGBD, el del Capítulo 10 (MySqlConnector): EF Core no reemplaza a ADO.NET; lo utiliza;
  • [5]: el SGBD.

11.1.2. EF Core y Entity Framework 6

Existen dos productos llamados Entity Framework:

  • Entity Framework 6 (EF 6), el producto original, diseñado para .NET Framework en Windows (desde la versión 6.3, también funciona en .NET Core y sus sucesores). Todavía recibe mantenimiento, pero ya no está en desarrollo activo;
  • Entity Framework Core, una reescritura completa lanzada en 2016 con .NET Core. Funciona en todas las plataformas .NET (Windows, Linux, macOS) y es la versión que recibe todas las novedades. Su número de versión sigue al de .NET: EF Core 8 con .NET 8, EF Core 9 con .NET 9, EF Core 10 con .NET 10.

Para una aplicación nueva, usamos EF Core. Ambos productos tienen API similares ([DbContext], [DbSet<T>], LINQ, migraciones), por lo que lo que se expone aquí sigue siendo válido en gran parte para EF 6.

11.1.3. Proveedores

EF Core accede a un SGBD a través de un proveedor, distribuido en un paquete NuGet. Microsoft ofrece los proveedores para SQL Server, SQLite y Azure Cosmos DB; los demás los escriben los editores de los SGBD o la comunidad: [Npgsql.EntityFrameworkCore.PostgreSQL] para PostgreSQL, [Oracle.EntityFrameworkCore] para Oracle, [Pomelo.EntityFrameworkCore.MySql] y [MySql.EntityFrameworkCore] (de Oracle) para MySQL. Utilizamos Pomelo, el proveedor de MySQL más utilizado, que se basa en el conector [MySqlConnector] del Capítulo 10.

Un proveedor se compila para una versión específica de EF Core: Pomelo 9 funciona con EF Core 9, y las versiones de Pomelo suelen publicarse varios meses después de las de EF Core. El curso utiliza EF Core 9.0.0 y Pomelo 9.0.0, sobre .NET 10. Esta combinación funciona: EF Core 9 tiene como destino .NET 8 ([net8.0]), y una biblioteca compilada para .NET 8 funciona sin modificaciones en .NET 10. El paso a EF Core 10 se logrará cambiando los números de versión de los paquetes; el código de este capítulo debería funcionar entonces sin modificaciones, salvo por algunos detalles menores en el SQL generado. Sin embargo, en la sección sobre LINQ nos encontraremos con una incompatibilidad menor entre EF Core 9 y el compilador de C# 14.

Los paquetes utilizados en este capítulo son los siguientes:

Paquete
Función
[Microsoft.EntityFrameworkCore] 9.0.0
EF Core propiamente dicho
[Pomelo.EntityFrameworkCore.MySql] 9.0.0
El proveedor de MySQL; incluye [Microsoft.EntityFrameworkCore.Relational] y [MySqlConnector]
[Microsoft.EntityFrameworkCore.Design] 9.0.0
el código utilizado por la herramienta de línea de comandos [dotnet ef] (migraciones)
herramienta [dotnet-ef] 9.0.0
la herramienta de línea de comandos [dotnet ef]

La herramienta [dotnet ef] se instala una sola vez en la máquina de desarrollo:

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

Las herramientas “globales” de .NET se instalan en la carpeta [.dotnet/tools] del directorio personal del usuario, que el instalador del SDK agrega a la ruta de ejecutables (en Linux, debe agregarla usted mismo: [export PATH=$PATH:$HOME/.dotnet/tools]).

11.1.4. Code First y Database First

El modelo de EF Core (la correspondencia entre clases y tablas) puede construirse de dos maneras:

  • Code First: se escriben las clases C# y EF Core deriva de ellas el esquema de la base de datos, que puede crear por sí mismo y luego actualizar a medida que evoluciona la aplicación (migraciones). Este es el enfoque adoptado en este capítulo y en el curso de 2012 del autor;
  • Database First: la base de datos ya existe y se generan las clases a partir de su esquema mediante el comando [dotnet ef dbcontext scaffold]. Este es el enfoque que se utiliza en las aplicaciones que deben trabajar con una base de datos existente. El código generado es similar al que escribiríamos a mano.

11.2. Un primer ejemplo

11.2.1. El proyecto

Cada ejemplo de este capítulo es un proyecto de consola: la herramienta [dotnet ef], utilizada para las migraciones, requiere un archivo de proyecto [.csproj]. Los proyectos están agrupados en la solución [11-efcore/11-efcore.slnx]. El primero, [First], se crea con los siguientes 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

Su archivo de proyecto es el siguiente:

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

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

  <ItemGroup>
    <!-- EF Core y su proveedor de MySQL (Pomelo) -->
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
  </ItemGroup>

</Project>
  • Líneas 12–13: los dos paquetes agregados por [dotnet add package].

La base de datos utilizada es la base [efarticles] del servidor MySQL local, que es el servidor de Laragon (véanse los apéndices). No es necesario que exista: EF Core la creará.

11.2.2. La entidad [Article]

Una clase cuyos objetos se almacenan en una tabla se denomina entidad. Nuestra primera entidad es un artículo de tienda, como en la tabla [articles] del curso de 2008, tratada en el Capítulo 10:

namespace First;

// un artículo de la tienda: una clase C# ordinaria, sin vínculo con EF Core
public class Article
{
    // clave primaria (por convención: la propiedad llamada Id)
    public int Id { get; set; }
    // las demás columnas de la tabla
    public string Name { get; set; } = "";
    public decimal Price { get; set; }
    public int CurrentStock { get; set; }
    public int MinimumStock { get; set; }

    // visualización
    public override string ToString() => $"[{Id}, {Name}, {Price}, {CurrentStock}, {MinimumStock}]";
}
  • Línea 4: una clase C# normal. No hereda de ninguna clase de EF Core y no tiene atributos; esto se conoce como un POCO (Plain Old CLR Object);
  • Línea 7: la propiedad [Id] será la clave primaria de la tabla. Esto es una convención de EF Core: una propiedad llamada [Id] (o [ArticleId], el nombre de la clase seguido de [Id]) es la clave primaria. Como es de tipo entero, sus valores serán generados por el SGBD (columna [AUTO_INCREMENT] de MySQL);
  • líneas 9–12: cada propiedad pública de lectura/escritura se convierte en una columna con el mismo nombre. La propiedad [Name] se inicializa con una cadena vacía para satisfacer al compilador (tipos que admiten valores nulos habilitados: una propiedad de tipo [string] no debe quedar en [null]);
  • línea 15: una presentación cómoda del artículo.

11.2.3. Contexto

El acceso a la base de datos se gestiona mediante un objeto de tipo [DbContext]:

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

namespace First;

// el contexto: la puerta de acceso a la base de datos [efarticles]
public class ArticlesContext : DbContext
{
    // la tabla de artículos
    public DbSet<Article> Articles => Set<Article>();

    // configuración del contexto: DBMS, cadena de conexión, registro
    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        const string connection = "Server=localhost;Port=3306;Database=efarticles;User=root;Password=";
        options
            // el proveedor de MySQL y la versión del servidor
            .UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36)))
            // muestra de las sentencias SQL enviadas al servidor
            .LogTo(Console.WriteLine, [DbLoggerCategory.Database.Command.Name], LogLevel.Information);
    }
}
  • Línea 7: la clase [DbContext] proviene de EF Core. Un objeto [ArticlesContext] representa una sesión de trabajo con la base de datos: abre la conexión cuando es necesario, almacena las entidades que ha leído y puede guardar los cambios realizados en ellas;
  • Línea 10: un [DbSet<Article>] representa la tabla de artículos. Aquí se ejecutan las consultas LINQ y se agregan o eliminan artículos. La propiedad se define como un miembro con cuerpo de expresión que llama a [Set<Article>()]: cada [DbSet<T>] declarado en el contexto introduce el tipo [T] en el modelo;
  • línea 13: EF Core llama al método [OnConfiguring] la primera vez que se utiliza el contexto, para configurarlo;
  • línea 15: la cadena de conexión, la misma que en el Capítulo 10: servidor, puerto, base de datos, nombre de usuario y contraseña (vacía para el usuario [root] de Laragon);
  • línea 18: el contexto utiliza el proveedor Pomelo. El segundo parámetro especifica la versión del servidor MySQL: el SQL generado depende de ella, ya que ciertas funcionalidades solo están disponibles en versiones recientes. Laragon proporciona MySQL 8; especificamos la versión 8.0.36. Pomelo también ofrece [ServerVersion.AutoDetect(connection)], que consulta al servidor para determinar su versión. Esto es cómodo, pero implica una conexión adicional cada vez que se configura un contexto, y el SQL generado pasa a depender del servidor encontrado. Especificar una versión de forma explícita hace que el comportamiento de la aplicación sea reproducible;
  • línea 20: el método [LogTo] indica a EF Core que escriba su registro mediante el método [Console.WriteLine]. Conservamos únicamente la categoría de mensajes [DbLoggerCategory.Database.Command] —la de los comandos SQL ejecutados— en el nivel [LogLevel.Information]. Sin este filtro, el registro es muy detallado. Ver el SQL enviado al servidor es la mejor manera de comprender lo que hace EF Core: lo haremos en todos los ejemplos.

11.2.4. El programa

using First;

// un contexto de EF Core: se liberará (conexión incluida) al final del programa
using var context = new ArticlesContext();

// la base de datos se elimina y luego se vuelve a crear a partir del modelo C#
context.Database.EnsureDeleted();
context.Database.EnsureCreated();

// adición de tres artículos
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");

// lectura de la tabla
Console.WriteLine("--- reading the articles");
foreach (Article article in context.Articles.OrderBy(a => a.Name))
{
    Console.WriteLine(article);
}
  • línea 4: crea el contexto. Una declaración [using] (C# 8) garantiza que se liberará ([Dispose]) al final del programa, lo que cierra cualquier conexión que haya abierto;
  • línea 7: [context.Database.EnsureDeleted()] elimina la base de datos si existe;
  • línea 8: [context.Database.EnsureCreated()] crea la base de datos y sus tablas a partir del esquema. Estos dos métodos son cómodos para ejemplos y pruebas; una aplicación real actualiza su base de datos mediante migraciones, que veremos más adelante;
  • Líneas 11–13: se agregan tres artículos al [DbSet]. Todavía no se ha enviado nada al servidor: el contexto solo recuerda que estos tres objetos deben insertarse. No asignamos ningún valor a la propiedad [Id], que generará el SGBD;
  • línea 15: [SaveChanges] envía al servidor todos los comandos SQL necesarios para guardar los cambios almacenados y devuelve el número de filas afectadas;
  • línea 20: una consulta LINQ sobre [DbSet]: los artículos en orden alfabético. El SGBD la ejecuta cuando el bucle [foreach] comienza a recorrerla.

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]

Comentarios:

  • Cada comando SQL va precedido de un encabezado de dos líneas: el tipo de evento ([CommandExecuted]), el tiempo de ejecución y los parámetros del comando;
  • línea 4: [EnsureDeleted] eliminó la base de datos, que ya existía (el programa ya se había ejecutado);
  • líneas 7–20: [EnsureCreated] creó la base de datos, le asignó el conjunto de caracteres [utf8mb4] (el conjunto Unicode completo de MySQL) y luego creó la tabla [Articles] a partir de la entidad [Article]: el nombre de la tabla es el de la propiedad [DbSet] del contexto, las columnas se nombran según las propiedades y la columna [Id] es la clave primaria con un valor generado ([AUTO_INCREMENT]). Todas las columnas son [NOT NULL]: los tipos [int] y [decimal] no admiten el valor [null], ni tampoco el tipo [string], ya que los tipos que admiten valores nulos están habilitados (volveremos sobre esto más adelante);
  • observe los tipos predeterminados: [longtext] para una cadena (texto de cualquier longitud) y [decimal(65,30)] para un [decimal] (65 dígitos, 30 de ellos después del punto decimal). Rara vez son los que queremos: el párrafo siguiente muestra cómo especificarlos;
  • líneas 21–41: [SaveChanges] envió un único comando que contiene tres comandos [INSERT] parametrizados. Cada uno va seguido de un [SELECT] que lee de nuevo la clave primaria generada por MySQL ([LAST_INSERT_ID()]): EF Core la copia en la propiedad [Id] del objeto insertado. Los valores de los parámetros están enmascarados ('?'): son datos de la aplicación, que pueden ser confidenciales. Durante la depuración, pueden mostrarse agregando la opción [.EnableSensitiveDataLogging()] a la configuración del contexto;
  • líneas 42–50: la consulta LINQ [context.Articles.OrderBy(a => a.Name)] se tradujo en un comando [SELECT ... ORDER BY]. EF Core creó un objeto [Article] por cada fila leída.

No escribimos ningún comando SQL ni ningún código de lectura de columnas: ese es todo el sentido de un ORM. También vemos que esto no elimina la necesidad de comprender SQL: para determinar si el SQL generado es correcto y eficaz, hay que saber leerlo.

11.3. El modelo

EF Core construye su modelo a partir de las entidades en tres pasos:

  • primero, aplica sus convenciones;
  • las complementa o corrige mediante las anotaciones (atributos) aplicadas a las entidades;
  • por último, aplica la configuración escrita en C# en el método [OnModelCreating] del contexto: la API fluida.

11.3.1. Las convenciones

Vimos lo esencial de ellas en el primer ejemplo:

  • toda propiedad pública con un getter [get] y un setter [set] (o [init]) se almacena en una columna del mismo nombre;
  • la propiedad [Id] o [<Entity>Id] es la clave primaria; si es un entero, sus valores los genera el SGBD;
  • el nombre de la tabla es el de la propiedad [DbSet] del contexto (o, en su defecto, el de la clase);
  • una propiedad de un tipo que admite valores nulos ([int?], [DateOnly?], [string?]) da lugar a una columna [NULL]; una propiedad de un tipo que no admite valores nulos ([int], [decimal], [string] cuando los tipos de referencia que admiten valores nulos están habilitados) da lugar a una columna [NOT NULL];
  • una propiedad que hace referencia a otra entidad, o una colección de entidades, define una relación (la trataremos más adelante).

11.3.2. Anotaciones y API fluida

El proyecto [Model] define dos entidades configuradas de dos maneras diferentes. La primera se configura mediante anotaciones:

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

namespace Model;

// una entidad configurada mediante anotaciones
[Table("products")]
public class Product
{
    // la clave primaria no se llama Id: hay que designarla
    [Key]
    public int Code { get; set; }

    // cadena obligatoria de 50 caracteres como máximo
    [Required, MaxLength(50)]
    public string Name { get; set; } = "";

    // tipo de referencia que admite null: columna que admite NULL
    [MaxLength(200)]
    public string? Description { get; set; }

    // nombre y tipo SQL de la columna fijados explícitamente
    [Column("price_excl_tax", TypeName = "decimal(10,2)")]
    public decimal PriceExclTax { get; set; }

    // tipo de valor que admite null: columna que admite NULL
    public DateOnly? WithdrawalDate { get; set; }

    // propiedad calculada: sin columna
    [NotMapped]
    public decimal PriceInclTax => PriceExclTax * 1.2M;
}
  • líneas 1–2: los atributos utilizados pertenecen a estos dos espacios de nombres de .NET. No son específicos de EF Core: los atributos de validación ([Required], [MaxLength]) también se utilizan para validar datos en los formularios de ASP.NET Core;
  • línea 7: el nombre de la tabla;
  • líneas 11–12: la clave primaria no se llama [Id]; el atributo [Key] la identifica;
  • líneas 15–16: una columna obligatoria ([Required]: [NOT NULL]) con un máximo de 50 caracteres ([MaxLength(50)]: [varchar(50)]). [Required] es redundante aquí, ya que el tipo [string] que no admite valores nulos basta para que la columna sea obligatoria; era esencial antes de C# 8;
  • líneas 19–20: el tipo [string?] especifica una descripción opcional: la columna aceptará el valor [NULL];
  • líneas 23–24: [Column] especifica el nombre de la columna y su tipo SQL: [decimal(10,2)], 10 dígitos, incluidos 2 decimales;
  • línea 27: una fecha opcional. El tipo [DateOnly] (.NET 6) representa una fecha sin hora: Pomelo la asocia con el tipo SQL [date];
  • líneas 30–31: [NotMapped] excluye una propiedad del modelo. Aquí es innecesario: una propiedad sin descriptor de acceso ([set]) no se registra. El atributo documenta la intención.

La segunda entidad no tiene atributos:

namespace Model;

// una entidad sin ninguna anotación: se configura mediante la API fluida
public class Supplier
{
    public int Number { get; set; }
    public string CompanyName { get; set; } = "";
    public string? Phone { get; set; }
    public DateTime CreationDate { get; set; }
}

Se configura en el contexto mediante la API fluida:

using Microsoft.EntityFrameworkCore;

namespace Model;

// un contexto que solo se usa para examinar el modelo: nunca se conecta al 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)));
    }

    // la API fluida: configuración del modelo mediante 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");
        });
    }
}
  • Línea 13: la base de datos [efmodel] nunca existirá: este contexto se utiliza únicamente para examinar el modelo, lo que no requiere una conexión (la versión del servidor se especifica de forma explícita);
  • línea 18: el método [OnModelCreating] recibe un objeto [ModelBuilder] que sirve para describir el modelo. Se llama una sola vez por tipo de contexto: EF Core almacena el modelo en caché;
  • línea 20: [Entity<Supplier>(...)] recibe una lambda que configura la entidad [Supplier]. Cada método devuelve el objeto de configuración, lo que permite encadenar las llamadas: de ahí el nombre “API fluida”;
  • línea 22: el nombre de la tabla;
  • línea 23: la clave primaria es la propiedad [Number];
  • línea 24: una columna obligatoria con un máximo de 60 caracteres;
  • línea 25: un índice único sobre el nombre de la empresa: dos proveedores no pueden tener el mismo. No existe un atributo de validación equivalente; EF Core proporciona el atributo [Index], colocado en la clase, que utilizaremos para los artículos;
  • línea 26: la propiedad [Phone] se almacena en la columna [tel];
  • línea 27: la columna [CreationDate] tiene un valor predeterminado, calculado por el SGBD. Durante una inserción, EF Core no enviará un valor para esta columna si la propiedad tiene el valor predeterminado de su tipo, lo que permitirá al SGBD utilizar [CURRENT_TIMESTAMP].

Todo lo que hacen las anotaciones puede hacerse con la API fluida, y la API fluida permite incluso más (índices, valores predeterminados, claves compuestas, relaciones complejas). Las anotaciones tienen la ventaja de colocar la configuración junto a la propiedad; la API fluida permite que las entidades sigan siendo independientes de EF Core y concentra la configuración en un único lugar. A menudo se combinan ambas: en caso de conflicto, prevalece la API fluida.

El programa [Program.cs] muestra el modelo construido por EF Core, seguido del script SQL que crearía las tablas:

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

using var context = new ModelContext();

// el modelo construido por EF Core: entidades, tablas, columnas
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}");
    }
}

// el script SQL que crea las tablas, sin ejecutarlo
Console.WriteLine("--- creation script");
// (se eliminan las líneas vacías duplicadas)
Console.WriteLine(context.Database.GenerateCreateScript().Replace("\n\n\n", "\n\n").Trim());
  • línea 8: la propiedad [Model] del contexto da acceso al modelo: sus entidades ([IEntityType]) y, para cada una, sus propiedades ([IProperty]);
  • línea 10: [ClrType] es el tipo C# de la entidad, y [GetTableName()] es el nombre de su tabla;
  • líneas 13–15: para cada propiedad, se muestran el nombre de la columna, su tipo SQL, si acepta el valor [NULL], y si forma parte de la clave primaria;
  • línea 22: [Database.GenerateCreateScript()] devuelve el script SQL de creación de tablas sin ejecutarlo. Es el script que [EnsureCreated] ejecutaría.

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`);
  • líneas 8–12: la entidad [Supplier] y sus columnas. Los tipos SQL provienen de la configuración ([varchar(60)], [varchar(20)]) o de las decisiones del proveedor para un tipo C#: [int] para [int], [datetime(6)] (precisión de microsegundos) para [DateTime];
  • líneas 2–7: la entidad [Product]. Las propiedades que admiten valores nulos ([DateOnly?], [string?]) dan lugar a columnas [NULL]; la propiedad [PriceInclTax] no aparece en el modelo;
  • líneas 16–33: el script de creación. Contiene toda la configuración: nombres de tablas y columnas, tipos de datos ([NOT NULL]), valores predeterminados, claves primarias (con [AUTO_INCREMENT] para las claves enteras) e índices únicos. Las columnas de texto utilizan el conjunto de caracteres [utf8mb4].

11.3.3. Tipos que admiten valores nulos y columnas NULL

Los tipos de referencia que admiten valores nulos (C# 8, habilitados mediante [<Nullable>enable</Nullable>] en los proyectos del curso) tienen un impacto en el modelo: EF Core lee las anotaciones de nulabilidad generadas por el compilador. Una propiedad [string] da lugar a una columna [NOT NULL], y una propiedad [string?] da lugar a una columna [NULL]. En un proyecto donde los tipos que admiten valores nulos no están habilitados, todas las columnas de texto aceptan [NULL], salvo las marcadas con [Required].

Por lo tanto, hay que elegir con cuidado el tipo de cada propiedad: expresa a la vez una regla del código C# (“este valor puede faltar”) y una restricción de la base de datos. Para una propiedad obligatoria, son comunes dos notaciones:

1
2
3
4
// un valor predeterminado, que satisface al compilador
public string Name { get; set; } = "";
// un miembro obligatorio (C# 11): el código que crea el objeto debe darle un valor
public required string Name { get; set; }

La segunda es más segura: el compilador rechaza [new Article { Price = 10 }], donde se ha omitido el nombre. EF Core puede crear entidades con miembros [required]: no pasa por el inicializador de objetos del código C#. Para las propiedades de navegación hacia otra entidad, que EF Core rellena por sí mismo, nos encontramos con la notación [= null!]: la veremos al tratar las relaciones.

11.4. Los ejemplos siguientes: dos bibliotecas compartidas

Los ejemplos de los párrafos siguientes utilizan todos la base de datos [efarticles] y su tabla [articles], poblada con los seis artículos del Capítulo 10. En lugar de repetir la entidad y el contexto en cada proyecto, los colocamos en una biblioteca de clases, [Articles.Data], a la que hacen referencia los proyectos. También reemplazamos el registro de EF Core, demasiado detallado para nuestros ejemplos, por un registro más compacto, colocado en una segunda biblioteca, [Ef.Tools].

11.4.1. El registro SQL compacto

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

namespace Ef.Tools;

// un registro compacto de las sentencias SQL ejecutadas por EF Core
public static class SqlLog
{
    // un miembro de extensión (C# 14) del tipo DbContextOptionsBuilder
    extension(DbContextOptionsBuilder options)
    {
        // options.WithSqlLog(): muestra cada sentencia SQL ejecutada
        public DbContextOptionsBuilder WithSqlLog() => options.LogTo(Filter, Display);
    }

    // los eventos seleccionados: comando SQL ejecutado o fallido, inicio y fin de las transacciones
    private static bool Filter(EventId id, LogLevel level) =>
        id == RelationalEventId.CommandExecuted || id == RelationalEventId.CommandError
        || id == RelationalEventId.TransactionStarted
        || id == RelationalEventId.TransactionCommitted || id == RelationalEventId.TransactionRolledBack;

    // muestra de un 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;
        }
    }

    // muestra de la sentencia SQL, con sangría, y luego de sus parámetros
    private static void DisplayCommand(DbCommand command)
    {
        // las líneas vacías se ignoran
        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)}");
        }
    }
}
  • líneas 12–15: un miembro de extensión (C# 14, véase el Capítulo 4) del tipo [DbContextOptionsBuilder], el tipo del parámetro de [OnConfiguring]. Escribiremos [options.UseMySql(...).WithSqlLog()], como si el método hubiera sido escrito por EF Core. Llama a otra sobrecarga de [LogTo], que recibe dos funciones: un filtro, que selecciona los eventos que se registrarán, y un método de visualización, que recibe el propio evento ([EventData]) en lugar de texto preformateado;
  • líneas 19–22: los eventos seleccionados. Cada evento de EF Core tiene un identificador; los de las operaciones relacionales son constantes de la clase [RelationalEventId]. Registramos los comandos SQL ejecutados o fallidos, así como el inicio, la confirmación (commit) y la reversión (rollback) de las transacciones;
  • líneas 27–43: cada tipo de evento corresponde a una clase derivada de [EventData], que proporciona detalles sobre él: [CommandExecutedEventData] contiene el comando ADO.NET ejecutado ([DbCommand], véase el Capítulo 10). La selección se realiza mediante un [switch] con filtrado por patrón de tipo y cláusulas [when];
  • líneas 52–54: el texto del comando, línea por línea, con sangría y precedido de [SQL>], con las líneas vacías eliminadas;
  • líneas 56–60: los parámetros del comando y sus valores. Los leemos directamente del comando; por lo tanto, nuestro registro siempre los muestra, mientras que el registro de EF Core los oculta de forma predeterminada. Esto es aceptable para un curso, pero no para una aplicación en producción.

11.4.2. La entidad y el contexto de los artículos

La entidad [Article] de la biblioteca [Articles.Data] utiliza las anotaciones del párrafo anterior:

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

namespace Articles.Data;

// un artículo de la tienda, con las anotaciones que especifican su tabla
[Table("articles")]
[Index(nameof(Name), IsUnique = true)]
public class Article
{
    // clave primaria, generada por el DBMS (AUTO_INCREMENT)
    public int Id { get; set; }

    // nombre del artículo: obligatorio, 30 caracteres como máximo, único (véase [Index])
    [MaxLength(30)]
    public required string Name { get; set; }

    // precio: 10 dígitos, de los cuales 2 después del punto decimal
    [Column(TypeName = "decimal(10,2)")]
    public decimal Price { get; set; }

    // existencias actuales y existencias mínimas por debajo de las cuales hay que reponer
    public int CurrentStock { get; set; }
    public int MinimumStock { get; set; }

    // visualización
    public override string ToString() => $"[{Id}, {Name}, {Price}, {CurrentStock}, {MinimumStock}]";
}
  • línea 8: la tabla se llama [articles], como en el Capítulo 10;
  • línea 9: el atributo [Index] de EF Core (espacio de nombres [Microsoft.EntityFrameworkCore]) crea un índice único sobre la columna [Name]: dos artículos no pueden tener el mismo nombre, como en la base de datos del curso de 2008;
  • líneas 16–17: un nombre obligatorio de no más de 30 caracteres. El miembro es [required]: el código que crea un artículo debe especificar su nombre;
  • líneas 20–21: un precio en [decimal(10,2)].

El contexto es el siguiente:

using Ef.Tools;
using Microsoft.EntityFrameworkCore;

namespace Articles.Data;

// el contexto de la base de datos [efarticles]
public class ArticlesContext : DbContext
{
    // cadena de conexión y versión del 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));

    // constructor sin parámetros: la configuración la hace OnConfiguring
    public ArticlesContext() { }

    // constructor que recibe una configuración ya preparada (inyección de dependencias)
    public ArticlesContext(DbContextOptions<ArticlesContext> options) : base(options) { }

    // la tabla de artículos
    public DbSet<Article> Articles => Set<Article>();

    // configuración predeterminada, si el constructor no ha recibido ninguna
    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        if (!options.IsConfigured)
        {
            // con muestra de las sentencias SQL (véase el proyecto [Ef.Tools])
            options.UseMySql(Connection, MySqlVersion).WithSqlLog();
        }
    }

    // (re)creación de la base de datos con sus seis artículos, sin registro
    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();
    }
}
  • líneas 10–11: la cadena de conexión y la versión del servidor, que son públicas para que otros proyectos puedan utilizarlas;
  • línea 14: un primer constructor, sin parámetros: la configuración la gestionará [OnConfiguring];
  • línea 17: un segundo constructor, que recibe un objeto preconfigurado ([DbContextOptions<ArticlesContext>]) y lo pasa al constructor de la clase [DbContext]. Este es el constructor que utiliza la inyección de dependencias (la veremos más adelante);
  • línea 25: [OnConfiguring] se llama en ambos casos. [IsConfigured] comprueba si el contexto recibió una configuración mediante su constructor. Si no, se utiliza la configuración predeterminada: MySQL, con el registro compacto;
  • líneas 33–48: un método estático que vuelve a crear la base de datos con sus seis artículos. Crea un contexto con una configuración que no incluye un registro: no queremos ver el SQL de esta inicialización en los resultados de los ejemplos. [DbContextOptionsBuilder<T>] es la versión genérica del objeto que recibe [OnConfiguring]; su propiedad [Options] devuelve la configuración construida. [AddRange] agrega varias entidades a la vez.

Los proyectos de ejemplo hacen referencia a la biblioteca [Articles.Data], que a su vez hace referencia a [Ef.Tools]:

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

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

  <ItemGroup>
    <!-- la entidad [Article] y el contexto [ArticlesContext] (EF Core incluido) -->
    <ProjectReference Include="../Articles.Data/Articles.Data.csproj" />
  </ItemGroup>

</Project>

Los paquetes de EF Core y Pomelo, a los que hace referencia [Articles.Data], son heredados por los proyectos que hacen referencia a ella.

11.5. Operaciones básicas: agregar, leer, modificar, eliminar

11.5.1. El programa [Crud]

El proyecto [Crud] muestra las cuatro operaciones básicas (CRUD: Create, Read, Update, Delete):

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// la base de datos se vuelve a crear con sus seis artículos
ArticlesContext.Initialize();
using var context = new ArticlesContext();

// 1 - búsqueda por clave primaria
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 - adición de un artículo
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 - modificación: basta con modificar el 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 - eliminación
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 - las entidades rastreadas por el 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

Comentarios:

  • línea 10: [Find(1)] busca el registro con clave primaria 1. El tipo devuelto es [Article?]: [Find] devuelve [null] si la clave no existe. El SQL generado (líneas 2–7) es un [SELECT] parametrizado, limitado a una fila;
  • línea 13: la segunda llamada a [Find(1)] no envía ningún comando SQL y devuelve el mismo objeto (línea 10). El contexto almacena las entidades que ha leído o agregado: antes de consultar la base de datos, [Find] comprueba si la entidad solicitada ya está bajo seguimiento. Un contexto nunca contiene dos objetos para la misma fila de la base de datos;
  • líneas 18–19: agregar un artículo. Antes de [SaveChanges], el artículo está en el estado [Added] y su valor [Id] es 0 (línea 12). [SaveChanges] envía un comando [INSERT], recupera la clave generada y la coloca en [x.Id] (línea 21). El artículo pasa al estado [Unchanged]: es idéntico a la fila de la base de datos;
  • línea 26: para modificar una fila de la base de datos, basta con modificar el objeto. No se requiere ningún método [Update]: el contexto ha conservado una copia de los valores leídos (los valores originales) y compara con ellos los valores actuales. El artículo pasa al estado [Modified] (línea 23);
  • línea 27: [context.Entry(x)] da acceso a la información de seguimiento de la entidad [x]: su estado ([State]) y, para cada propiedad, su valor original ([OriginalValue]) y su valor actual ([CurrentValue]);
  • línea 29: el comando [UPDATE] generado (líneas 25–28) modifica únicamente la columna que ha cambiado, [Price]. Le sigue un [SELECT ROW_COUNT()]: EF Core verifica que el comando haya modificado efectivamente una fila;
  • líneas 34–36: la eliminación. [Remove] cambia el estado del artículo a [Deleted]; [SaveChanges] envía el comando [DELETE]. A partir de entonces, el contexto ya no sigue al objeto: está en el estado [Detached];
  • líneas 41–43: el objeto [context.ChangeTracker] (el “seguimiento de cambios”) administra las entidades bajo seguimiento. [DetectChanges] compara los valores actuales de las entidades con sus valores originales (EF Core lo llama automáticamente en [SaveChanges], [Entry], y algunos otros métodos). La propiedad [DebugView.LongView] devuelve una descripción de todas las entidades bajo seguimiento (líneas 38–44): el contexto ahora sigue únicamente la bicicleta, cuyo inventario ha disminuido de 10 a 9. El operador [!] en [bike!] indica al compilador que [bike], de tipo [Article?], no es [null] en este punto.

Dos detalles del SQL generado por Pomelo:

  • el comando [INSERT], seguido de un [SELECT] de la clave generada, está encerrado dentro de una transacción (líneas 13–20): el comando contiene dos comandos SQL que deben tener éxito juntos. Volveremos sobre las transacciones más adelante;
  • los comandos aislados [UPDATE] y [DELETE] no están encerrados dentro de una transacción. Van precedidos de [SET AUTOCOMMIT = 1], un ajuste de sesión de MySQL (cada comando se confirma en cuanto se ejecuta) que el proveedor restablece como precaución. Este ajuste no tiene efecto sobre una transacción abierta de forma explícita, como veremos.

11.5.2. Los estados de una entidad

El seguimiento de cambios se basa en el estado de cada entidad, un valor de la enumeración [EntityState]:

Estado
Significado
[Detached]
El contexto no sigue al objeto (creado con [new] y aún no agregado, o eliminado de la base de datos)
[Added]
El objeto se ha agregado al contexto ([Add]): [SaveChanges] lo insertará en la base de datos
[Unchanged]
El objeto se leyó de la base de datos (o se guardó) y no se ha modificado desde entonces
[Modified]
Se ha modificado al menos una propiedad: [SaveChanges] enviará un comando [UPDATE]
[Deleted]
El objeto se ha marcado para su eliminación ([Remove]): [SaveChanges] enviará un comando [DELETE]

Observe el ciclo de trabajo con EF Core: se leen entidades, se modifican como objetos ordinarios, se agregan y se eliminan, y luego se llama a [SaveChanges], que envía todos los comandos necesarios a la base de datos en un solo lote. El contexto actúa como una “unidad de trabajo”. Un contexto es un objeto ligero diseñado para tener una vida corta: una unidad de trabajo, como una solicitud HTTP en una aplicación web. No se utiliza el mismo contexto durante toda la vida de una aplicación, ya que acumularía entidades bajo seguimiento.

11.5.3. Actualizaciones masivas y lectura sin seguimiento

El seguimiento de cambios tiene un costo: para aumentar el precio de 100 artículos, hay que leer los 100 artículos, modificarlos uno por uno, y [SaveChanges] enviará 100 comandos [UPDATE]. EF Core 7 introdujo dos métodos que envían directamente un comando SQL que abarca todas las filas seleccionadas por una consulta: [ExecuteUpdate] y [ExecuteDelete]. El proyecto [BulkUpdate] los describe, así como las operaciones de solo lectura:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// la base de datos se vuelve a crear con sus seis artículos
ArticlesContext.Initialize();
using var context = new ArticlesContext();

// 1 - ExecuteUpdate: una sola sentencia UPDATE, ninguna entidad cargada en memoria
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: una sola sentencia 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 - lectura sin seguimiento de cambios
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()}");
// SaveChanges ignora la modificación de una entidad no rastreada
articles[0].Price = 0;
Console.WriteLine($"SaveChanges: {context.SaveChanges()} row(s) modified");

// 4 - ExecuteUpdate no modifica las entidades ya cargadas por el 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

Comentarios:

  • Líneas 10–12: [ExecuteUpdate] se aplica a una consulta ([Where]) y recibe una lambda que describe las columnas que se van a modificar: [SetProperty(property, new value)]. El nuevo valor puede depender de la propia fila ([a => a.MinimumStock * 2]). La instrucción SQL (líneas 3–5) se ejecuta de inmediato, sin [SaveChanges], y devuelve el número de filas modificadas;
  • líneas 16–18: un aumento del 10 % en los precios bajos. Observe que las constantes del código C# ([150], [1.1M]) se escriben dentro del texto del comando SQL ([150.0], [1.1]);
  • línea 23: [ExecuteDelete] elimina las filas seleccionadas por la consulta —en este caso, el arco, el único artículo con un precio superior a 550 euros—;
  • línea 28: [AsNoTracking()] solicita una lectura sin seguimiento: el contexto no almacena las entidades leídas (línea 26). Esto es más rápido y consume menos memoria: se utiliza para datos que se leen sin modificarse (visualización, cálculos). La contrapartida es que [SaveChanges] ignora los cambios realizados en estas entidades (línea 27);
  • líneas 37–41: una trampa. [ExecuteUpdate] opera directamente sobre la base de datos: no modifica las entidades ya cargadas por el contexto. La bicicleta que sigue el contexto conserva su precio anterior (línea 37) hasta que se vuelve a leer con [context.Entry(bike).Reload()]. [Single] devuelve el único elemento de la consulta y lanza una excepción si hay cero o más de un elemento: por eso el SQL generado solicita dos filas ([LIMIT 2]).

11.6. LINQ se traduce a SQL

11.6.1. Consultas

El Capítulo 5 presentó LINQ para colecciones en memoria. Los mismos operadores ([Where], [OrderBy], [Select], [First], [Count], [Sum]...) se aplican a un [DbSet<T>], pero .NET no los ejecuta: EF Core los traduce a SQL y es el SGBD quien los ejecuta. El proyecto [Linq] ofrece varios ejemplos:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// la base de datos se vuelve a crear con sus seis artículos
ArticlesContext.Initialize();
using var context = new ArticlesContext();

// 1 - filtrado y ordenación
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 - proyección: solo se solicitan las columnas útiles
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 - un solo resultado; la variable [minPrice] se convierte en un 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 - agregados: el cálculo lo hace el DBMS
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 de .NET traducidos a SQL
Console.WriteLine("--- StartsWith and Contains");
// una lista y no un arreglo (véanse las explicaciones)
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 - el SQL de una consulta, sin ejecutarla
Console.WriteLine("--- ToQueryString");
IQueryable<Article> query = context.Articles.Where(a => a.Price < 150).OrderBy(a => a.Price);
Console.WriteLine(query.ToQueryString());

// 7 - paginación: la tercera página de dos artículos, por precio creciente
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 - un método C# que EF Core no puede traducir
Console.WriteLine("--- untranslatable method");
try
{
    var list = context.Articles.Where(a => Rules.OutOfStock(a)).ToList();
}
catch (InvalidOperationException e)
{
    // solo mostramos la primera oración del mensaje
    int end = e.Message.IndexOf(" Either");
    Console.WriteLine($"{e.GetType().Name} : {(end > 0 ? e.Message[..end] : e.Message)}");
}
// AsEnumerable: el resto de la consulta se ejecuta en memoria, por .NET
var outOfStock = context.Articles.AsEnumerable().Where(a => Rules.OutOfStock(a)).ToList();
outOfStock.ForEach(Console.WriteLine);

// una regla de negocio escrita en C#
static class Rules
{
    // un artículo está agotado si sus existencias son inferiores a las existencias mínimas
    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]

Comentarios:

  • Líneas 10–13: [Where] y [OrderBy] se convierten en las cláusulas [WHERE] y [ORDER BY] (líneas 5–6). La consulta solo se ejecuta cuando se solicitan sus resultados, en este caso mediante [ToList]: esta es la ejecución diferida de LINQ (Capítulo 5);
  • líneas 18–20: una proyección. [Select] crea un objeto de tipo anónimo para cada artículo, que contiene solo el nombre y el valor del inventario. El SQL generado (línea 9) recupera únicamente las columnas pertinentes y realiza el cálculo por sí mismo. Los objetos del tipo anónimo no son entidades: el contexto no los sigue. El proveedor convierte las existencias, que son un entero, a [decimal(65,30)] antes de la multiplicación, lo que explica los numerosos decimales del resultado, que luego se formatea con [{v.Value:0.00}];
  • línea 30: [FirstOrDefault] se convierte en [LIMIT 1]. La variable del programa [minPrice] se convierte en un parámetro del comando SQL ([@__minPrice_0], línea 21), mientras que una constante escrita en la lambda se copia en el texto SQL. Por lo tanto, no hay que preocuparse por las inyecciones SQL: los valores que provienen del exterior del programa siempre se pasan como parámetros. Es la regla que el Capítulo 10 aplicó manualmente con consultas parametrizadas;
  • líneas 35–36: los agregados [Count] y [Sum] los calcula el SGBD ([COUNT(*)], [SUM(...)]): solo se transfiere el resultado, no las filas. [COALESCE(..., 0.0)] devuelve 0 si la tabla está vacía, igual que [Sum] de LINQ;
  • líneas 42–45: los métodos de .NET que EF Core conoce se traducen a SQL: [a.Name.StartsWith("b")] se convierte en [LIKE 'b%'], y [names.Contains(a.Name)], que hace referencia a una lista en memoria, se convierte en [IN ('bow', 'pump', 'racket')] (línea 35). Hay muchos métodos traducidos: operaciones sobre cadenas, fechas y funciones matemáticas;
  • líneas 51–52: [ToQueryString()] devuelve el texto SQL de una consulta sin ejecutarla (líneas 37–41). Es útil para la depuración;
  • líneas 57–60: la paginación, para mostrar una lista larga página por página. [Skip] omite los artículos de las páginas anteriores, mientras que [Take] conserva los de la página solicitada: se convierten en las cláusulas [OFFSET] y [LIMIT] (línea 46). La paginación solo tiene sentido sobre una lista ordenada ([OrderBy]);
  • línea 61: esta proyección contiene una cadena interpolada, que EF Core no traduce a SQL. Esto no es un error: cuando la operación no traducible es el [Select] final, EF Core solicita al SGBD las columnas necesarias ([Name] y [Price]) y realiza la proyección en memoria sobre cada fila leída. Observe que el precio se formatea según la configuración regional en-US, con un punto decimal;
  • líneas 69–71: EF Core no puede traducir la llamada a ningún método del programa: no conoce su código y, aunque lo conociera, no necesariamente sabría cómo escribirlo en SQL. Ejecutar la consulta desencadena una [InvalidOperationException] (líneas 50–51). El mensaje (en inglés, como todos los mensajes de excepción de .NET), del cual el programa muestra solo la primera oración, ofrece entonces dos soluciones: reescribir la consulta o pasar explícitamente a una evaluación en memoria;
  • línea 78: [AsEnumerable()] transfiere la consulta de [IQueryable<T>] a [IEnumerable<T>]: la parte anterior se traduce a SQL (aquí, la lectura de toda la tabla) y la parte siguiente la ejecuta LINQ en memoria. El resultado es correcto, pero se cargó toda la tabla: con una tabla grande, esto debe evitarse. Es mejor escribir la condición en la lambda ([a.CurrentStock < a.MinimumStock]), como se muestra en la línea 11.

11.6.2. IQueryable y árboles de expresión

¿Cómo puede ejecutarse la misma lambda en C# sobre una lista y traducirse a SQL sobre un [DbSet]? El Capítulo 7 dio la respuesta: un [DbSet<T>] implementa la interfaz [IQueryable<T>], cuyos métodos [Where], [OrderBy], [Select]... no reciben delegados ([Func<T, bool>]) sino árboles de expresión ([Expression<Func<T, bool>>]). El compilador transforma la lambda [a => a.CurrentStock < a.MinimumStock] en una estructura de datos que la describe (“ comparación [<] de la propiedad [CurrentStock] y la propiedad [MinimumStock] del parámetro [a]”); EF Core recorre esta estructura y produce el SQL equivalente. Un método como [Rules.OutOfStock] aparece en el árbol solo como una llamada a método, cuyo código no puede analizarse: de ahí el error.

Los operadores se componen: una consulta puede construirse por etapas, devolviendo cada etapa un nuevo [IQueryable<T>], y solo la ejecución final ([ToList], [First], [Count], [foreach]...) envía un 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);
// una sola sentencia SELECT, con o sin WHERE
List<Article> articles = query.ToList();

11.6.3. Una incompatibilidad entre EF Core 9 y C# 14

En el programa [Linq], la lista [names] se declaró de tipo [List<string>] en lugar de [string[]], con un comentario que hace referencia a este párrafo. Con un arreglo, la consulta [context.Articles.Where(a => names.Contains(a.Name))] se compila, pero falla en tiempo de ejecución con un error [InvalidOperationException] (“An exception was thrown while attempting to evaluate a LINQ query parameter expression”). En efecto, C# 14 ha convertido la conversión de un arreglo a [ReadOnlySpan<T>] (el tipo presentado en el Capítulo 5) en una conversión implícita del lenguaje, que se aplica también al objeto sobre el que se llama a un método de extensión. Para un arreglo, la llamada [names.Contains(...)] ahora hace referencia, por lo tanto, al método de extensión [MemoryExtensions.Contains(ReadOnlySpan<T>, T)] en lugar de a [Enumerable.Contains(IEnumerable<T>, T)]: esto se evidencia al examinar el árbol de expresión de la lambda, y el mismo programa compilado en C# 13 ([<LangVersion>13</LangVersion>]) encuentra [Enumerable.Contains] y funciona. EF Core 9, publicado antes que C# 14, no reconoce este método: intenta evaluar la conversión del arreglo a [ReadOnlySpan<string>] para convertirla en un parámetro SQL, lo que falla (la excepción interna es una [ArgumentException] lanzada por el intérprete de árboles de expresión). EF Core 10, publicado junto con C# 14, admite esta sintaxis. Con EF Core 9, se puede sortear el problema utilizando una lista, como se muestra aquí, o escribiendo [((IEnumerable<string>)names).Contains(a.Name)]. Este es el único problema encontrado en este capítulo al usar EF Core 9 con .NET 10.

11.7. Relaciones

11.7.1. El modelo de la tienda

Las tablas de una base de datos están vinculadas entre sí. EF Core representa estos vínculos mediante propiedades de navegación: propiedades que hacen referencia a otra entidad o a una colección de entidades. El proyecto [Relations] utiliza una base de datos [efshop] que describe una pequeña tienda:

namespace Relations;

// una categoría agrupa varios productos (relación uno a muchos)
public class Category
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    // propiedad de navegación: los productos de la categoría
    public List<Product> Products { get; set; } = [];
}

// un producto pertenece a una categoría y tiene varias etiquetas
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public decimal Price { get; set; }
    // clave externa y propiedad de navegación hacia la categoría
    public int CategoryId { get; set; }
    public Category Category { get; set; } = null!;
    // relación muchos a muchos con las etiquetas
    public List<Tag> Tags { get; set; } = [];
}

// una etiqueta (promoción, novedad...) es llevada por varios productos
public class Tag
{
    public int Id { get; set; }
    public string Label { get; set; } = "";
    public List<Product> Products { get; set; } = [];
}

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

// un pedido de un cliente, compuesto por líneas
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; } = [];
}

// una línea de pedido: una cantidad de un producto
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!;
}
  • una relación de uno a muchos entre [Category] y [Product]: una categoría contiene varios productos (línea 9) y un producto pertenece a una categoría (líneas 19–20). La propiedad [CategoryId] es la clave externa: por convención, el nombre de la propiedad de navegación seguido de [Id]. Es opcional en el código (EF Core la crearía en la tabla si no existiera en la clase), pero resulta cómoda: permite determinar la categoría de un producto sin cargarla;
  • una relación de muchos a muchos entre [Product] y [Tag]: un producto tiene varias etiquetas (línea 22) y una etiqueta está asociada a varios productos (línea 30). No hay clave externa: la relación se almacenará en una tabla de asociación creada por EF Core;
  • las relaciones de uno a muchos [Client] - [Order] y [Order] - [OrderLine], y la relación de muchos a uno [OrderLine] - [Product]: una línea de pedido representa una cantidad de un producto;
  • las colecciones se inicializan con una colección vacía ([= []], una expresión de colección de C# 12). Las propiedades de navegación que apuntan a una sola entidad se inicializan con [null!]: el valor [null], acompañado del operador [!], que indica al compilador que no señale que una propiedad que no admite valores nulos recibe [null]. Esta es la notación convencional para una propiedad que EF Core rellena por sí mismo durante las operaciones de lectura y que nunca es [null] en una entidad cargada correctamente. Una propiedad de este tipo define una relación obligatoria (clave externa [NOT NULL]); una propiedad de tipo [Category?] y una clave de tipo [int?] definirían una relación opcional.

El contexto es el siguiente:

using Ef.Tools;
using Microsoft.EntityFrameworkCore;

namespace Relations;

// el contexto de la base de datos [efshop]; [log]: mostrar o no las sentencias 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)
    {
        // precios con dos decimales
        modelBuilder.Entity<Product>().Property(p => p.Price).HasPrecision(10, 2);
    }
}
  • línea 7: el contexto tiene un constructor primario (C# 12) cuyo parámetro opcional [log] permite omitir el SQL;
  • líneas 9–13: cinco [DbSet]. Una entidad no necesita un [DbSet] para formar parte del modelo: [OrderLine], a la que se llega mediante la propiedad de navegación [Order.Lines], forma parte de él de hecho;
  • línea 19: el registro compacto se agrega si se solicita;
  • línea 28: la API fluida establece la precisión del precio.

Las tablas creadas por [EnsureCreated] son las siguientes:

> 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
  • Líneas 5–11: una tabla por entidad. La tabla [OrderLine] lleva el nombre de la clase, al no existir la propiedad [DbSet]; la tabla [ProductTag] es la tabla de asociación de la relación de muchos a muchos;
  • Línea 22: la clave externa [CategoryId] de la tabla [Products] hace referencia a la tabla [Categories]. La opción [ON DELETE CASCADE] elimina los productos de una categoría cuando esta se elimina: este es el comportamiento predeterminado de EF Core para una relación obligatoria. EF Core también crea un índice sobre cada clave externa (línea 21);
  • líneas 26–32: la tabla de asociación tiene dos columnas, claves externas hacia las dos tablas vinculadas, que juntas forman su clave primaria;
  • línea 17: no hemos limitado la longitud de los nombres, de ahí el tipo [longtext].

11.7.2. El programa

using Microsoft.EntityFrameworkCore;
using Relations;

// 1 - creación de la base de datos y de un primer conjunto de datos, sin registro
using (var context = new ShopContext(log: false))
{
    context.Database.EnsureDeleted();
    context.Database.EnsureCreated();
    // dos etiquetas
    var promo = new Tag { Label = "promo" };
    var novelty = new Tag { Label = "new" };
    // tres categorías y sus productos: agregamos un 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();
    // un cliente y su 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 - un cliente, su pedido y sus líneas, agregados de una sola 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 - las propiedades de navegación no se cargan automáticamente
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 - carga de las relaciones con Include y 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 - carga explícita de una colección
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 - la relación muchos a muchos, en una 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 - un cálculo a través de las relaciones, hecho por el DBMS
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 - una agrupación: número de productos y precio promedio por categoría
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

Comentarios:

  • Líneas 13–32: se agregan tres categorías, junto con sus productos y las etiquetas de los productos: un grafo de objetos. EF Core recorre las propiedades de navegación y agrega al contexto todas las entidades que encuentra. [SaveChanges] las inserta en el orden correcto (las categorías antes de los productos que hacen referencia a ellas) y rellena las claves externas y la tabla de asociación. Esta inicialización se realiza sin registro;
  • líneas 35–36: la propiedad [Local] de un [DbSet] da acceso a las entidades que el contexto ya sigue, sin consultar la base de datos;
  • líneas 56–71: un cliente, su pedido y las dos líneas del pedido se agregan en una sola llamada a [Add]. El SQL (líneas 11–35) muestra el orden de las inserciones: el cliente, luego el pedido —cuya clave externa ([ClientId]) recibe la clave generada para el cliente ([@p1=2])— y, por último, las líneas del pedido, cuya clave externa ([OrderId]) recibe la clave del pedido;
  • líneas 79–80: de forma predeterminada, EF Core carga solo la entidad solicitada. Las propiedades de navegación [Client] y [Lines] del pedido leído no se rellenaron (línea 41): [Client] es igual a [null] (a pesar de la declaración que no admite valores nulos, de ahí el operador [?.]), y la lista de líneas está vacía. EF Core admite la carga diferida (lazy loading): la propiedad de navegación se carga automáticamente en su primera lectura. Debe habilitarse explícitamente (paquete [Microsoft.EntityFrameworkCore.Proxies], propiedades de navegación [virtual]); no la utilizamos porque oculta los accesos a la base de datos;
  • líneas 87–89: carga anticipada (eager loading). [Include(c => c.Client)] indica al sistema que cargue el cliente de cada pedido; [Include(c => c.Lines)] carga las líneas del pedido, y [ThenInclude(l => l.Product)] carga el producto de cada línea. Todo se carga mediante una sola consulta [SELECT], con combinaciones (joins) (líneas 45–51). La salida muestra ambos pedidos y sus líneas;
  • línea 106: la carga explícita. Cargamos la colección de productos de una categoría que ya se ha leído: una segunda consulta, [SELECT], lee los productos cuya clave externa coincide con la de la categoría. Para una propiedad de navegación hacia una sola entidad, escribimos [context.Entry(product).Reference(p => p.Category).Load()];
  • líneas 114–116: las propiedades de navegación se utilizan en consultas LINQ, sin [Include]: [p.Tags.Any(...)] se convierte en una subconsulta [EXISTS] sobre la tabla de asociación (líneas 72–76), y [p.Category.Name] se convierte en una combinación (join);
  • líneas 125–126: un cálculo a través de dos relaciones —el importe de cada pedido— realizado íntegramente por el SGBD mediante una subconsulta (líneas 81–84);
  • líneas 135–138: una agrupación. [GroupBy] agrupa los productos por nombre de categoría; para cada grupo ([g]), el SGBD calcula la clave ([g.Key]), el número de productos ([Count]) y el precio promedio ([Average]): la consulta se convierte en un [GROUP BY] (líneas 90–93). La categoría [diving], que no tiene productos, no aparece: la combinación con la tabla de categorías es una combinación interna ([INNER JOIN]).

El llamado problema de las “consultas N+1” es un riesgo para cualquier usuario de un ORM. Supongamos que queremos mostrar el nombre del cliente de cada pedido y leemos los pedidos sin [Include], y luego recuperamos el cliente de cada uno mediante una carga explícita (o una carga diferida, que equivale a lo mismo sin que nos demos cuenta): ejecutamos una consulta para los N pedidos y luego N consultas, una por pedido. Con mil pedidos, esto da como resultado mil un viajes de ida y vuelta al servidor, cuando uno solo habría bastado. Las soluciones son las que se muestran en el ejemplo: [Include] o, mejor aún, una proyección ([Select]) que recupere únicamente los datos pertinentes. El registro SQL ayuda a identificar el problema: la misma consulta repetida numerosas veces.

11.8. Migraciones

11.8.1. El principio

Hasta ahora, la base de datos se ha creado con [EnsureCreated], tras ser eliminada con [EnsureDeleted]. Esto es imposible en una aplicación en producción: su base de datos contiene datos que deben conservarse cuando el modelo evoluciona (una nueva columna, una nueva tabla). Además, [EnsureCreated] solo puede crear una base de datos que no existe: si la base de datos ya existe con tablas, no hace nada, aunque el modelo haya cambiado.

Las migraciones responden a esta necesidad. Una migración es una clase C#, generada por la herramienta [dotnet ef], que describe la transición de una versión del modelo a la siguiente: su método [Up] aplica el cambio (crear una tabla, agregar una columna), mientras que su método [Down] lo revierte. La base de datos contiene una tabla llamada [__EFMigrationsHistory], en la que EF Core registra las migraciones que se le han aplicado; esto le permite saber cuáles faltan por aplicar.

11.8.2. El proyecto

El proyecto [Clients] utiliza la base de datos [efclients]. Su archivo de proyecto agrega el paquete [Microsoft.EntityFrameworkCore.Design], que requiere la herramienta [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 y su proveedor de MySQL (Pomelo) -->
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
    <!-- el código utilizado por la herramienta [dotnet ef] (migraciones): inútil en tiempo de ejecución -->
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>
  • Líneas 15–18: el elemento [PrivateAssets] (“all”) indica que este paquete está destinado únicamente al desarrollo: no se distribuye a los proyectos que hacen referencia a este y no es necesario para la ejecución. Esto es lo que produce el comando [dotnet add package Microsoft.EntityFrameworkCore.Design].

La entidad es un cliente:

using System.ComponentModel.DataAnnotations;

namespace Clients;

// un 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; }
}

En la primera versión de la aplicación, el cliente no tiene número de teléfono: las líneas 13–14 todavía no existen. Las agregaremos en la segunda versión.

La herramienta [dotnet ef] debe poder crear un contexto para determinar el modelo y, para ciertos comandos, conectarse a la base de datos. Para ello utiliza, en orden: una clase del proyecto que implemente la interfaz [IDesignTimeDbContextFactory<T>], o el contenedor de inyección de dependencias de una aplicación ASP.NET Core o, en su defecto, un constructor sin parámetros del contexto. Escribimos una fábrica:

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

namespace Clients;

// el contexto recibe su configuración a través de su constructor (constructor primario)
public class ClientsContext(DbContextOptions<ClientsContext> options) : DbContext(options)
{
    public DbSet<Client> Clients => Set<Client>();
}

// la fábrica de contextos utilizada por la herramienta [dotnet ef] (y por nuestro 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);
    }
}
  • línea 7: el contexto recibe su configuración mediante un constructor primario (C# 12), que pasa al constructor de [DbContext]. No tiene un método [OnConfiguring]: no conoce su base de datos; el código que lo crea la elige;
  • Líneas 13–21: la fábrica. Su método [CreateDbContext] construye la configuración ([DbContextOptionsBuilder<T>]) y crea el contexto. El parámetro [args] recibe los argumentos que se pasan a la herramienta; no lo usamos.

11.8.3. La primera migración

Los comandos de la herramienta [dotnet ef] se escriben en la carpeta del proyecto. La primera migración, que llamamos [Initial], se crea con el 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'

La herramienta compiló el proyecto, creó un contexto con la fábrica, comparó el modelo con el de la última migración (todavía no hay ninguna) y generó tres archivos en una carpeta llamada [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

Los nombres de los archivos comienzan con la fecha y la hora de creación de la migración (año, mes, día, hora, minuto, segundo): las migraciones se aplican en ese orden. El archivo [ClientsContextModelSnapshot.cs] contiene una descripción de el modelo tal como queda después de la última migración: la herramienta usa este archivo para compararlo con el modelo actual y así generar la siguiente migración. Estos archivos forman parte del código fuente de la aplicación: se almacenan y gestionan junto con el resto del código (por ejemplo, en un repositorio Git).

La migración generada es la siguiente:

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");
        }
    }
}
  • línea 9: una migración deriva de la clase [Migration];
  • líneas 12–32: el método [Up] describe las operaciones que se deben realizar, mediante un objeto [MigrationBuilder]: modificar el juego de caracteres de la base de datos ([AlterDatabase]), crear la tabla [Clients] ([CreateTable]) con sus columnas y su clave primaria. Las anotaciones [MySql:...] contienen información específica del proveedor Pomelo;
  • líneas 36–39: el método [Down] revierte la migración eliminando la tabla.

El código de una migración puede modificarse manualmente, por ejemplo, para agregar operaciones que la herramienta no puede deducir del modelo ([migrationBuilder.Sql("...")] ejecuta cualquier comando SQL).

11.8.4. Aplicar una migración

El comando [dotnet ef database update] aplica a la base de datos las migraciones que todavía no se han aplicado o, si se le da el nombre de una migración, todas las migraciones hasta esa 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.

La base de datos [efclients] no existía: se creó. El cliente [mysql] de MySQL muestra sus tablas:

> 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    |                |
+-------+--------------+------+-----+---------+----------------+

Contiene la tabla del modelo [Clients] y la tabla [__EFMigrationsHistory], que contiene una fila por cada migración aplicada.

11.8.5. Una segunda migración

La aplicación evoluciona: la propiedad [Phone], de tipo [string?] y limitada a 20 caracteres, se agrega a la entidad [Client] (esta es la versión del archivo [Client.cs] mostrada anteriormente). Se crea una nueva migración:

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

La herramienta comparó el modelo actual con la instantánea y generó la siguiente migración:

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");
        }
    }
}
  • Líneas 13–18: [Up] agrega la columna [Phone], que es opcional puesto que la propiedad es de tipo [string?]. A las filas existentes de la tabla se les asignará el valor [NULL]. Si la propiedad hubiera sido obligatoria ([string]), habría sido necesario asignar un valor a las filas existentes: la migración lo habría hecho con la cadena vacía, que es el valor predeterminado de la columna ([defaultValue: ""]);
  • líneas 25–27: [Down] elimina la columna.

La instantánea del modelo también se actualizó. Estos son los cambios principales:

    [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");
                });
  • línea 12: el atributo [DbContext] asocia la instantánea con el contexto [ClientsContext];
  • líneas 24–48: la descripción de la entidad [Client], escrita con la API fluida: cada propiedad, su tipo SQL, su longitud, su carácter obligatorio ([IsRequired]), la clave primaria y la tabla. La propiedad [Phone] está incluida aquí (líneas 42–44). Al comparar este modelo con el modelo actual del código, la herramienta determinará las operaciones de la siguiente migración. Este archivo nunca debe modificarse manualmente; para deshacer la última migración (si no se ha aplicado), use [dotnet ef migrations remove], que elimina sus archivos y restaura la instantánea a su estado anterior.

El comando [dotnet ef migrations list] enumera las migraciones del proyecto y las que todavía no se han aplicado a la base de datos:

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

El comando [dotnet ef migrations script] genera el script SQL de una migración (o de una serie de migraciones) sin ejecutarlo. Se usa cuando la base de datos de producción no la actualiza el desarrollador, sino un administrador que desea revisar y ejecutar por sí mismo el script SQL:

> 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;
  • Líneas 4–10: la migración se ejecuta dentro de una transacción: la modificación del esquema y la adición de la migración a la tabla de historial se completan o fallan juntas. Advertencia: en MySQL, un comando de modificación del esquema ([ALTER TABLE], [CREATE TABLE]) confirma implícitamente la transacción en curso. Si ocurre un error en medio de una migración, la base de datos puede quedar en un estado intermedio;
  • Línea 7: la migración se registra en la tabla de historial, junto con la versión de EF Core que la aplicó.

11.8.6. Aplicar las migraciones desde la aplicación

Una aplicación también puede aplicar las migraciones por sí misma al iniciarse. Esto es lo que hace el programa del proyecto [Clients]:

using Clients;
using Microsoft.EntityFrameworkCore;

// el contexto es creado por la misma fábrica que el de la herramienta [dotnet ef]
using ClientsContext context = new ClientsContextFactory().CreateDbContext(args);

// el estado de las migraciones
Console.WriteLine($"applied migrations: {string.Join(", ", context.Database.GetAppliedMigrations())}");
Console.WriteLine($"pending migrations: {string.Join(", ", context.Database.GetPendingMigrations())}");

// aplicación de las migraciones pendientes
context.Database.Migrate();
Console.WriteLine("Migrate(): the database is up to date");

// la nueva columna es utilizable
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"}]");
}
  • línea 5: el contexto se crea mediante la fábrica proporcionada por la herramienta;
  • líneas 8–9: las migraciones aplicadas a la base de datos (leídas de la tabla de historial) y las que quedan por aplicar;
  • línea 12: [Migrate] aplica las migraciones pendientes (creando la base de datos si es necesario). Esto equivale a [dotnet ef database update];
  • Líneas 16–20: se usa la nueva columna.

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]

El programa aplicó la segunda migración. La tabla de historial ahora contiene ambas migraciones:

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 las migraciones al inicio es cómodo para una aplicación pequeña o durante el desarrollo. Para una aplicación grande desplegada en varios servidores, es preferible aplicarlas como un paso separado del proceso de despliegue (script SQL o ejecutable de migración generado por [dotnet ef migrations bundle]). Tenga en cuenta lo siguiente:

  • [EnsureCreated]: para ejemplos, pruebas y prototipos, cuando la base de datos puede eliminarse y volver a crearse;
  • migraciones: en cuanto la base de datos contiene datos que deben conservarse. No deben mezclarse: una base de datos creada con [EnsureCreated] no tiene tabla de historial, y no se le pueden aplicar migraciones.

11.9. Asincronía

Una consulta a la base de datos es una operación de E/S: mientras el servidor trabaja, el hilo que espera no hace nada. El capítulo 9 mostró cómo liberar este hilo mediante [async] y [await]. EF Core ofrece una versión asíncrona de todos los métodos que acceden a la base de datos: [ToListAsync], [FirstOrDefaultAsync], [SingleAsync], [CountAsync], [SumAsync], [FindAsync], [SaveChangesAsync], etc. Están definidos en el espacio de nombres [Microsoft.EntityFrameworkCore] (no en [System.Linq]). El proyecto [Async] los utiliza:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// la base de datos se vuelve a crear con sus seis artículos
ArticlesContext.Initialize();
// el contexto se libera de forma asíncrona (await using)
await using var context = new ArticlesContext();

// 1 - consultas así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 - guardado asíncrono
Console.WriteLine("--- SaveChangesAsync");
bow!.Price = 550;
int nbRows = await context.SaveChangesAsync();
Console.WriteLine($"{nbRows} row(s) modified");

// 3 - un flujo asíncrono: las filas se procesan a medida que se leen
Console.WriteLine("--- await foreach");
await foreach (Article article in context.Articles.AsNoTracking().Where(a => a.Price >= 300).AsAsyncEnumerable())
{
    Console.WriteLine($"read: {article.Name}");
}

// 4 - cancelación
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.

Comentarios:

  • Línea 7: un [DbContext] implementa [IAsyncDisposable]: [await using] (C# 8, capítulo 9) lo libera de forma asíncrona;
  • línea 11: [ToListAsync] ejecuta la consulta y devuelve un [Task<List<Article>>]. La consulta en sí ([Where], [OrderBy]) se escribe como antes: solo cambia el método que la ejecuta;
  • líneas 14–15: las versiones asíncronas de [FirstOrDefault] y [Count];
  • línea 21: el guardado asíncrono;
  • línea 26: [AsAsyncEnumerable()] devuelve la consulta como un flujo asíncrono ([IAsyncEnumerable<T>], capítulo 9), que se recorre con [await foreach]. Las entidades se procesan a medida que se leen, sin formar una lista: esto es útil para procesar un gran número de filas;
  • líneas 33–39: los métodos asíncronos aceptan un [CancellationToken] (capítulo 9). Aquí, el token se cancela antes de la llamada: [ToListAsync] lanza de inmediato una [OperationCanceledException] (línea 34). En una aplicación web, se pasa el token de la solicitud HTTP: si el cliente aborta la solicitud, la operación de lectura en curso se interrumpe.

Una regla importante: un contexto no es seguro para hilos y acepta solo una operación a la vez. No inicie dos solicitudes simultáneas en el mismo contexto (por ejemplo, con [Task.WhenAll]): hay que esperar ([await]) a que termine una operación antes de comenzar otra. EF Core suele detectar este error y lanza una [InvalidOperationException] («A second operation was started on this context instance before a previous operation completed»), pero no siempre. Para solicitudes realmente paralelas, se usa un contexto por tarea.

En una aplicación de consola como nuestros ejemplos, la asincronía no ofrece ningún beneficio visible. Resulta especialmente valiosa en una aplicación de servidor (capítulos 12 y 13), donde un hilo liberado durante una solicitud SQL puede atender a otros clientes. Por eso las aplicaciones ASP.NET Core usan sistemáticamente los métodos asíncronos de EF Core.

11.10. Transacciones y concurrencia

11.10.1. Transacciones

El capítulo 10 presentó las transacciones: un conjunto de operaciones que se completan todas o fallan todas. Con EF Core, hay dos puntos clave que tener en cuenta:

  • [SaveChanges] es transaccional: si envía varios comandos, los ejecuta dentro de una transacción. Si alguno falla, ninguno se confirma, y [SaveChanges] lanza una [DbUpdateException];
  • Para agrupar varias llamadas a [SaveChanges] (o comandos como [ExecuteUpdate], [ExecuteSql]...) en una sola transacción, se abre una transacción explícita con [context.Database.BeginTransaction()] (o su versión asíncrona), se confirma con [Commit] y se revierte con [Rollback].

El proyecto [Transactions] ilustra ambos casos:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// la base de datos se vuelve a crear con sus seis artículos
ArticlesContext.Initialize();

// 1 - SaveChanges es transaccional: todo o 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)
    {
        // el error del DBMS es la excepción interna
        Console.WriteLine($"{e.GetType().Name} : {e.InnerException?.Message}");
    }
}
await DisplayAsync("racket");

// 2 - una transacción explícita que abarca varios SaveChanges
Console.WriteLine("--- explicit transaction rolled back");
await using (var context = new ArticlesContext())
{
    await using var transaction = await context.Database.BeginTransactionAsync();
    try
    {
        // venta de dos bicicletas
        Article bike = await context.Articles.SingleAsync(a => a.Name == "bike");
        bike.CurrentStock -= 2;
        await context.SaveChangesAsync();
        // adición de un artículo cuyo nombre ya existe: error
        context.Articles.Add(new Article { Name = "pump", Price = 12, CurrentStock = 5, MinimumStock = 1 });
        await context.SaveChangesAsync();
        // confirmación del conjunto (aquí no se llega a este punto)
        await transaction.CommitAsync();
    }
    catch (DbUpdateException e)
    {
        Console.WriteLine($"{e.GetType().Name} : {e.InnerException?.Message}");
        // cancelación de todas las operaciones de la transacción
        await transaction.RollbackAsync();
    }
}
// la venta de las bicicletas se ha cancelado
await DisplayAsync("bike");

// muestra de un artículo leído de la base de datos, con un nuevo 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]

Comentarios:

  • Líneas 11–15: se agregan dos artículos, el segundo de los cuales tiene el mismo nombre que un artículo existente. [SaveChanges] abre una transacción (línea 3) y envía ambas instrucciones [INSERT]. La segunda viola el índice único de la columna [Name]: MySQL rechaza la inserción, y [SaveChanges] lanza una [DbUpdateException], cuya excepción interna es el error del SGBD (línea 15). La transacción no se confirmó: se abandona y MySQL revierte sus operaciones. La raqueta, que se había insertado correctamente, no está en la base de datos (línea 21);
  • línea 29: una transacción explícita. El objeto devuelto ([IDbContextTransaction]) se libera con [await using]: si no se ha confirmado, la transacción se revierte en ese punto;
  • Líneas 33–35: el primer [SaveChangesAsync] registra la venta de dos bicicletas. Como ya hay una transacción en curso, [SaveChanges] no inicia una nueva; en cambio, se incluye en la existente. El comando [SET AUTOCOMMIT = 1], que precede a [UPDATE] (línea 28), no confirma la transacción en curso: las líneas siguientes muestran que la venta efectivamente se cancelará;
  • líneas 37–38: el segundo guardado falla (líneas 38–40);
  • línea 40: nunca se llega a la confirmación;
  • línea 46: en el [catch], la transacción se revierte (línea 41). La venta de las bicicletas, aunque registrada por el primer [SaveChangesAsync], se cancela: el inventario de bicicletas sigue en 10 (línea 47);
  • Líneas 53–57: una función local asíncrona que vuelve a leer un artículo con un contexto nuevo para ver el estado real de la base de datos en lugar de las entidades rastreadas por el contexto de trabajo.

11.10.2. Concurrencia optimista

Dos usuarios leen el mismo artículo, que tiene un stock de 10. El primer usuario vende uno y actualiza el stock a 9. El segundo usuario, que leyó el stock antes de esta actualización, vende tres y actualiza el stock a 7: la venta del primer usuario se pierde. Este es el problema de las actualizaciones perdidas.

Una solución sería bloquear la fila durante toda la operación de cada usuario (concurrencia «pesimista»): esto bloquea a los demás usuarios, a veces durante mucho tiempo. EF Core implementa la concurrencia optimista: no se bloquea nada, pero en el momento de la confirmación, el sistema verifica que la fila no haya sido modificada desde que se leyó. Para ello, se designan una o más propiedades como tokens de concurrencia: EF Core agrega la condición «el token todavía tiene el valor leído» a la cláusula [WHERE] de las instrucciones [UPDATE] y [DELETE] . Si el comando no modifica ninguna fila, significa que otro usuario ya las procesó: EF Core lanza una [DbUpdateConcurrencyException].

El proyecto [Concurrency] convierte el stock en un token de concurrencia. En lugar de modificar la entidad [Article] compartida por los demás ejemplos, deriva el contexto y complementa el modelo con la API fluida:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

namespace Concurrency;

// el contexto de artículos, donde las existencias se convierten en un token de concurrencia
public class ArticlesConcurrencyContext : ArticlesContext
{
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        // el valor leído para las existencias se verificará en cada UPDATE o DELETE
        modelBuilder.Entity<Article>().Property(a => a.CurrentStock).IsConcurrencyToken();
    }
}
  • línea 11: se conserva la configuración de la clase padre;
  • línea 13: la propiedad [CurrentStock] se convierte en un token de concurrencia. La anotación equivalente es el atributo [ConcurrencyCheck] aplicado a la propiedad.

El programa simula a los dos usuarios con dos contextos:

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

// la base de datos se vuelve a crear con sus seis artículos
ArticlesContext.Initialize();

// dos usuarios, dos contextos: cada uno lee el mismo artículo
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");

// el usuario 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}");

// el usuario 2 vende 3 bicicletas con datos obsoletos (existencias = 10)
Console.WriteLine("--- user 2 sells 3 bikes");
bike2.CurrentStock -= 3;
try
{
    context2.SaveChanges();
}
catch (DbUpdateConcurrencyException e)
{
    // solo mostramos la primera oración del mensaje
    Console.WriteLine($"{e.GetType().Name} : {e.Message[..(e.Message.IndexOf('.') + 1)]}");
    // resolución: se vuelve a leer el artículo desde la base de datos y se rehace la venta
    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

Comentarios:

  • líneas 12–13: cada usuario lee la bicicleta en su propio contexto;
  • líneas 17–18: el comando [UPDATE] del primer usuario contiene la condición [CurrentStock = @p2], con el valor leído, 10 (líneas 13–16). La fila se modifica;
  • líneas 23–26: el comando del segundo usuario contiene la misma condición, con el valor que leyó, 10, mientras que el inventario en la base de datos ahora es 9. No se modifica ninguna fila: [SELECT ROW_COUNT()] devuelve 0, y EF Core lanza una [DbUpdateConcurrencyException] (línea 24);
  • líneas 34–36: la propiedad [Entries] de la excepción enumera las entidades en conflicto. La resolución depende de la aplicación: abortar, advertir al usuario o, como aquí, volver a leer la entidad desde la base de datos ([Reload]) y repetir la operación. El inventario releído es 9 (línea 31), y la venta de las tres bicicletas da como resultado un inventario de 6, con la condición [CurrentStock = 9] (línea 36).

El token de concurrencia más común no son datos de negocio, sino una columna dedicada que se modifica con cada actualización de la fila: un número de versión o una fecha de modificación. En SQL Server, una propiedad de tipo [byte[]] marcada con el atributo [Timestamp] se asocia al tipo [rowversion], que el SGBD modifica automáticamente; en MySQL, a menudo se usa un entero o una fecha que la aplicación (o un trigger) modifica con cada actualización.

11.11. El SQL sin procesar

EF Core genera SQL a partir de LINQ, pero también es posible escribir uno mismo el SQL de una consulta, para usar una característica específica del SGBD o para optimizar una consulta compleja. El proyecto [RawSql] presenta los métodos disponibles:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

// la base de datos se vuelve a crear con sus seis artículos
ArticlesContext.Initialize();
using var context = new ArticlesContext();

// 1 - FromSql: una consulta SQL escrita a mano que devuelve 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 - la interpolación produce un parámetro: no es posible la inyección SQL
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");
// la misma consulta construida por concatenación: nunca hacer esto
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 no son entidades (la columna se llama 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: una sentencia de actualización
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

Comentarios:

  • Líneas 11–13: [FromSql] ejecuta una consulta SQL que devuelve filas de la tabla de una entidad e instancia entidades (rastreadas por el contexto). Su parámetro es una cadena interpolada: EF Core no la convierte en texto; en cambio, recibe un objeto [FormattableString] que contiene por separado el texto y los valores que se deben insertar, y convierte cada valor en un parámetro SQL ([@p0], línea 5). El resultado de [FromSql] es un [IQueryable<T>]: puede completarse con LINQ. La cláusula [OrderBy] fue agregada por EF Core alrededor de nuestra consulta, que se convirtió en una subconsulta;
  • líneas 19–20: un intento de inyección SQL. El valor de [name] se pasa como parámetro: se compara tal cual con la columna [Name], y ningún registro coincide (línea 18);
  • línea 24: la misma consulta construida por concatenación y pasada a [FromSqlRaw], que ejecuta el texto que se le proporciona. El valor de [name] se convierte en código SQL, la condición sigue siendo verdadera y la consulta devuelve los seis artículos (línea 24): es una inyección SQL exitosa. [FromSqlRaw] solo debe usarse con texto constante, con los valores pasados como parámetros ([FromSqlRaw("... WHERE Name = {0}", name)]);
  • líneas 29–31: [Database.SqlQuery<T>] (EF Core 7 para tipos simples, EF Core 8 para los demás) ejecuta una consulta que devuelve valores de cualquier tipo, en este caso cadenas. Para un tipo simple, la columna devuelta debe llamarse [Value] (alias [AS Value]): este es el nombre que usa EF Core cuando construye la consulta con LINQ, como con el siguiente [Single] (líneas 28–32). [SqlQuery] también acepta cualquier clase, a cuyas propiedades se asignan las columnas del mismo nombre;
  • líneas 40–42: [Database.ExecuteSql] ejecuta un comando de actualización, también parametrizado mediante interpolación, y devuelve el número de filas modificadas.

Todos estos métodos tienen una versión asíncrona ([ToListAsync] sobre el resultado de [FromSql], [ExecuteSqlAsync]).

11.12. Contexto e inyección de dependencias

Los ejemplos anteriores creaban sus contextos con [new]. En una aplicación por capas, y en todas las aplicaciones ASP.NET Core, los contextos los crea el contenedor de inyección de dependencias presentado en el capítulo 6. EF Core ofrece dos métodos de extensión de [IServiceCollection] para este fin:

  • [AddDbContext<T>(options => ...)] registra el contexto [T] con un ciclo de vida «con ámbito» (scoped): el contenedor crea un contexto por ámbito, lo proporciona a todos los servicios de ese ámbito que lo soliciten y lo libera al final del ámbito. En una aplicación web, se crea un ámbito por cada solicitud HTTP: cada solicitud tiene su propio contexto, lo que corresponde a la unidad de trabajo del contexto;
  • [AddDbContextFactory<T>(options => ...)] registra una fábrica de contextos, [IDbContextFactory<T>], cuyo método [CreateDbContext] crea un contexto nuevo en cada llamada. Se usa en servicios de larga duración (singletons), que no pueden mantener el mismo contexto durante toda la vida de la aplicación, y en el procesamiento en paralelo, que requiere un contexto por tarea.

En ambos casos, la lambda recibe un [DbContextOptionsBuilder] y configura el contexto como lo hacía [OnConfiguring]; el contexto debe tener un constructor que acepte un [DbContextOptions<T>], como el de la clase [ArticlesContext] .

El proyecto [Injection] hace referencia al paquete [Microsoft.Extensions.DependencyInjection] (versión 10.0.12, como en el capítulo 6). Define dos servicios:

using Articles.Data;
using Microsoft.EntityFrameworkCore;

namespace Injection;

// un servicio que recibe el contexto por inyección: su tiempo de vida es el del contexto
public class ArticlesDao(ArticlesContext context)
{
    // los artículos por reponer
    public List<string> ArticlesOutOfStock() =>
        context.Articles.Where(a => a.CurrentStock < a.MinimumStock).Select(a => a.Name).ToList();
}

// un servicio de larga duración: recibe una fábrica de contextos
public class StatisticsService(IDbContextFactory<ArticlesContext> factory)
{
    // cada llamada usa un nuevo contexto, liberado de inmediato
    public async Task<decimal> StockValueAsync()
    {
        await using ArticlesContext context = await factory.CreateDbContextAsync();
        return await context.Articles.SumAsync(a => a.Price * a.CurrentStock);
    }
}
  • línea 7: un servicio que recibe el contexto mediante su constructor (primario). Debe registrarse con el mismo ciclo de vida que el contexto (con ámbito);
  • línea 15: un servicio que recibe una fábrica de contextos;
  • línea 20: cada llamada al método crea un contexto y lo libera de inmediato.

El programa es el siguiente:

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

// la base de datos se vuelve a crear con sus seis artículos
ArticlesContext.Initialize();

// 1 - AddDbContext: el contexto se registra con un tiempo 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 un mismo ámbito, siempre obtenemos el mismo contexto
    contextOfScope1 = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
    var context = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
    Console.WriteLine($"scope 1: same context = {ReferenceEquals(context, contextOfScope1)}");
    // el servicio [ArticlesDao] ha recibido este contexto
    var dao = scope.ServiceProvider.GetRequiredService<ArticlesDao>();
    Console.WriteLine($"scope 1: out of stock = {string.Join(", ", dao.ArticlesOutOfStock())}");
}
using (IServiceScope scope = provider.CreateScope())
{
    // otro ámbito: otro contexto
    var context = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
    Console.WriteLine($"scope 2: same context as in scope 1 = {ReferenceEquals(context, contextOfScope1)}");
}
// al final de su ámbito, el contexto se ha liberado
try
{
    contextOfScope1.Articles.Count();
}
catch (ObjectDisposedException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message[..(e.Message.IndexOf('.') + 1)]}");
}

// 2 - AddDbContextFactory: una fábrica de contextos para un servicio de larga duración
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

Comentarios:

  • Líneas 11–12: registro del contexto. La configuración dada aquí es la que recibe el constructor del contexto: [OnConfiguring] por lo tanto evalúa [options.IsConfigured] como verdadero y no agrega el registro de SQL. Podría agregarse aquí con [WithSqlLog];
  • línea 13: el servicio [ArticlesDao], que también tiene ámbito;
  • línea 17: [CreateScope()] crea un ámbito. Los servicios «con ámbito» se obtienen del proveedor de servicios del ámbito ([scope.ServiceProvider]);
  • líneas 20–22: dos solicitudes del contexto dentro del mismo ámbito devuelven el mismo objeto (línea 2);
  • línea 24: el contenedor crea el servicio [ArticlesDao] pasándole el contexto del ámbito;
  • líneas 27–31: otro ámbito recibe un contexto distinto (línea 4);
  • líneas 36–38: al final de su ámbito, el contenedor liberó el contexto; usarlo lanza una [ObjectDisposedException]. Este es el error clásico de un servicio de larga duración que retuvo un contexto recibido dentro de un ámbito;
  • líneas 45–47: la fábrica de contextos y un servicio singleton que la utiliza. El servicio puede vivir tanto como la aplicación: no conserva un contexto; crea uno nuevo para cada cálculo.

Tenga presentes las reglas sobre el ciclo de vida de un contexto: de corta duración (una unidad de trabajo), nunca compartido entre varios hilos y siempre liberado ([using], o el contenedor).

11.13. Aplicación de ejemplo: versión 7

11.13.1. La arquitectura

La versión 6 de la aplicación de cálculo del impuesto (capítulo 10) leía los tramos del impuesto desde una base de datos MySQL mediante ADO.NET. La versión 7 hace lo mismo con EF Core. Como en la versión 6, solo cambia la capa [dao]: las capas [business] y [ui] de la versión 5 (capítulo 6) se reutilizan tal cual mediante referencias de proyecto.

Image

La solución incluye dos proyectos nuevos en la carpeta [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. La capa [dao]

El proyecto [Tax.Dao.Ef] hace referencia a la capa [dao] de la versión 5, que contiene las entidades ([TaxBracket], [TaxException]) y la interfaz [ITaxDao]:

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

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

  <ItemGroup>
    <!-- la capa [dao] de la versión 5: entidades, interfaz ITaxDao, HardwiredTax -->
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Dao/Tax.Dao.csproj" />
  </ItemGroup>

  <ItemGroup>
    <!-- EF Core y su proveedor de MySQL -->
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
    <!-- para la herramienta [dotnet ef] (migraciones) -->
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>
  • línea 11: la referencia al proyecto [Tax.Dao] de la versión 5, mediante una ruta relativa;
  • líneas 16–19: EF Core, Pomelo y el paquete necesario para la herramienta [dotnet ef].

La estructura [Entities.TaxBracket] de la versión 5 no puede ser una entidad de EF Core: es un [readonly record struct], que es inmodificable y no tiene clave primaria. No se modifica porque forma parte del contrato entre las capas, compartido por todas las versiones. Se crea una entidad de persistencia específica de la capa [dao], cuyo papel es representar una fila de la tabla:

using System.ComponentModel.DataAnnotations.Schema;

namespace Dao;

// un tramo del impuesto tal como se almacena en la base de datos: una entidad de EF Core
[Table("brackets")]
public class TaxBracketEntity
{
    // la clave primaria, que no existe en 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; }
}
  • línea 6: la tabla [brackets], como en la versión 7 del curso de 2008;
  • línea 10: la clave primaria, que también se usa para ordenar los tramos;
  • líneas 12–19: las tres columnas, con tipos de datos [decimal] apropiados: el límite y el coeficiente [coeffN] son importes con dos decimales, y [coeffR] es una tasa con cuatro decimales.

Contexto:

using Microsoft.EntityFrameworkCore;

namespace Dao;

// el contexto de la base de datos [eftaxes]: recibe su configuración a través de su constructor
public class TaxContext(DbContextOptions<TaxContext> options) : DbContext(options)
{
    // la tabla de los tramos del impuesto
    public DbSet<TaxBracketEntity> Brackets => Set<TaxBracketEntity>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // datos iniciales: los tramos de la clase HardwiredTax (versión 5),
        // numerados desde 1; los insertará la migración
        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);
    }
}
  • línea 6: el contexto se configura mediante su constructor: el programa principal elegirá la base de datos;
  • líneas 15–17: los datos iniciales. Para evitar reescribir los tramos del impuesto, reutilizamos los de la clase [HardwiredTax] de la versión 5, que numeramos a partir de 1 con la sobrecarga de [Select], que proporciona el índice del elemento;
  • Línea 18: [HasData] declara filas que forman parte del modelo. Las migraciones las insertan en la tabla y, si cambian, la siguiente migración contendrá los comandos [UPDATE], [INSERT] o [DELETE] necesarios. Las claves primarias deben especificarse explícitamente para que la herramienta pueda comparar los datos entre versiones.

La fábrica que usa la herramienta [dotnet ef]:

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

namespace Dao;

// la fábrica utilizada por la herramienta [dotnet ef] para crear el contexto (migraciones)
public class TaxContextFactory : IDesignTimeDbContextFactory<TaxContext>
{
    public TaxContext CreateDbContext(string[] args)
    {
        // la base de datos de desarrollo; en tiempo de ejecución, la cadena proviene de la configuración
        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);
    }
}

Solo la utiliza la herramienta durante el desarrollo: la cadena de conexión de la base de datos de desarrollo está escrita directamente en ella. En tiempo de ejecución, la cadena de conexión proviene del archivo de configuración de la aplicación.

La clase [EfTax] implementa la interfaz [ITaxDao]:

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

namespace Dao;

// una capa [dao] que lee los tramos del impuesto desde una base de datos con EF Core
public class EfTax : ITaxDao
{
    // códigos de error específicos de esta implementación
    public enum ErrorCodes { Access = 1, EmptyTable = 2 }

    // tramos del impuesto
    public TaxBracket[] TaxBrackets { get; }

    // constructor: se inyecta la fábrica de contextos
    public EfTax(IDbContextFactory<TaxContext> factory)
    {
        try
        {
            // un contexto de vida corta, el tiempo de leer la tabla
            using TaxContext context = factory.CreateDbContext();
            // las entidades de persistencia se proyectan sobre las entidades de la aplicación
            TaxBrackets = context.Brackets
                .AsNoTracking()
                .OrderBy(t => t.Id)
                .Select(t => new TaxBracket(t.Limit, t.CoeffR, t.CoeffN))
                .ToArray();
        }
        catch (DbException e)
        {
            // error del DBMS: lo envolvemos en una TaxException
            throw new TaxException("Error while reading the tax brackets from the database", e)
            {
                Code = (int)ErrorCodes.Access
            };
        }
        // la capa [business] necesita al menos un tramo
        if (TaxBrackets.Length == 0)
        {
            throw new TaxException("The tax brackets table is empty") { Code = (int)ErrorCodes.EmptyTable };
        }
    }
}
  • línea 11: los códigos de error de esta implementación, como para [FileTax] y [JsonTax];
  • línea 17: la capa [dao] recibe una fábrica de contextos. Será un singleton: lee los tramos de una vez por todas en su constructor, usando un contexto de corta duración que se libera de inmediato (línea 22);
  • líneas 24–28: lectura de la tabla, sin seguimiento (los tramos no se modificarán), en orden de clave primaria. La proyección [Select] transforma cada entidad de persistencia en un [Entities.TaxBracket]: el resto de la aplicación nunca ve la entidad [TaxBracketEntity]. EF Core solicita al SGBD únicamente las tres columnas pertinentes;
  • líneas 30–35: un error del SGBD (base de datos inaccesible, tabla inexistente, etc.) se manifiesta como una excepción derivada de [DbException], la clase base de las excepciones de los conectores ADO.NET (capítulo 10): [MySqlException] para MySqlConnector. Como en otras implementaciones, se encapsula en una [TaxException];
  • líneas 39–41: una tabla vacía también es un error: la capa [business] requiere al menos un tramo.

11.13.3. La base de datos

La base de datos [eftaxes] se crea con la migración [Initial], generada por el comando [dotnet ef migrations add Initial] escrito en la carpeta del proyecto [Tax.Dao.Ef]. La herramienta aceptó una biblioteca de clases como proyecto de inicio porque contiene la fábrica [TaxContextFactory] y el paquete [Microsoft.EntityFrameworkCore.Design] (de lo contrario, se especifica un proyecto ejecutable mediante la opción [--startup-project]). La migración es la siguiente:

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

#nullable disable

#pragma warning disable CA1814 // Preferir arreglos escalonados en lugar de multidimensionales

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");
        }
    }
}
  • líneas 19–31: creación de la tabla;
  • líneas 35–46: inserción de los datos iniciales, una fila por tramo;
  • línea 6: el código generado desactiva una advertencia del analizador de código relativa a las matrices multidimensionales ([new object[,]]).

El script de migración SQL muestra los comandos que se ejecutarán:

> 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;

La tabla [__EFMigrationsHistory] se crea si no existe (líneas 4–8) y luego la migración se aplica en una transacción. Aplique la migración:

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.

y se verifica el contenido de la tabla:

> 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 |
+----+----------+--------+---------+

Los tramos de la escala están presentes, y el último tiene un límite igual a cero (la capa [business] no lo utiliza; esta selecciona el último tramo cuando ningún otro es adecuado).

Para configurar la base de datos en su equipo: la migración [Initial] ya está incluida con los códigos del curso en la carpeta [11-efcore/TaxV7/Tax.Dao.Ef/Migrations]. Por lo tanto, no es necesario volver a escribir el comando [dotnet ef migrations add Initial] (se usó para generar la migración, así que ese paso ya está completo). Simplemente:

  • inicie MySQL (en Laragon; consulte el apéndice; usuario [root] sin contraseña);
  • instale la herramienta [dotnet-ef] si todavía no lo ha hecho: [dotnet tool install --global dotnet-ef --version 9.0.0];
  • vaya a la carpeta [11-efcore/TaxV7/Tax.Dao.Ef] y escriba el único comando [dotnet ef database update].

Entonces se crea la base de datos [eftaxes], con su tabla [brackets] poblada con los datos iniciales. Si el comando falla, verifique que MySQL esté en ejecución y que la cadena de conexión de la fábrica [TaxContextFactory] coincida con su servidor (puerto 3306, nombre de usuario [root], contraseña en blanco).

11.13.4. Integración de las capas

El proyecto ejecutable [Tax.Ui.Ef] consta de las siguientes capas:

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

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

  <ItemGroup>
    <!-- las capas [business] y [ui] de la versión 5, sin cambios -->
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Business/Tax.Business.csproj" />
    <ProjectReference Include="../../../06-architectures/TaxV5/Tax.Ui/Tax.Ui.csproj" />
    <!-- la nueva capa [dao] -->
    <ProjectReference Include="../Tax.Dao.Ef/Tax.Dao.Ef.csproj" />
  </ItemGroup>

  <ItemGroup>
    <!-- contenedor de inyección de dependencias y configuración JSON -->
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.12" />
  </ItemGroup>

  <ItemGroup>
    <!-- los archivos de configuración se copian junto al ejecutable -->
    <None Update="tax-ef*.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

</Project>
  • líneas 12–13: las capas [business] y [ui] de la versión 5. El proyecto [Tax.Ui] es un ejecutable: puede referenciarse como biblioteca para usar su clase [Ui.Dialog];
  • Línea 15: la nueva capa [dao];
  • línea 26: los archivos de configuración. No se llaman [appsettings.json]: el proyecto referenciado [Tax.Ui] ya copia sus propios archivos [appsettings*.json] a la carpeta de salida, y dos archivos con el mismo nombre entrarían en conflicto.

El archivo de configuración [tax-ef.json] contiene la cadena de conexión:

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

La sección [ConnectionStrings] es la ubicación habitual de las cadenas de conexión en la configuración de .NET: el método [config.GetConnectionString("Tax")] lee la clave [ConnectionStrings:Tax]. El archivo [tax-ef-error.json] hace referencia a una base de datos llamada [eftaxesmissing], que no existe.

El programa principal es el de la versión 5, en el que solo cambia la composición de la capa [dao]:

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

// el archivo de configuración: tax-ef.json de forma predeterminada, o el que se pasa como argumento
string configFile = args.Length > 0 ? args[0] : "tax-ef.json";

// integración de las capas
ITaxBusiness business;
try
{
    // lectura de la configuración, junto al ejecutable
    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 de las capas en el contenedor
    var services = new ServiceCollection();
    // una fábrica de contextos de EF Core, configurada para MySQL
    services.AddDbContextFactory<TaxContext>(options =>
        options.UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36))));
    // la capa [dao]: EfTax recibirá la fábrica
    services.AddSingleton<ITaxDao, EfTax>();
    // la capa [business]: recibirá la capa [dao]
    services.AddSingleton<ITaxBusiness, TaxBusiness>();

    // creación del contenedor, luego de la capa [business] (y por lo tanto de la capa [dao])
    ServiceProvider provider = services.BuildServiceProvider();
    business = provider.GetRequiredService<ITaxBusiness>();
}
catch (Exception e)
{
    // muestra del error y fin del programa
    Dialog.DisplayError(e);
    return 1;
}

// el diálogo con el usuario, el de la versión 5
Dialog.Run(business);
return 0;
  • líneas 21–22: la cadena de conexión leída de la configuración. Una expresión [throw] (C# 7) a la derecha de [??] lanza una excepción si falta;
  • líneas 27–28: una fábrica de contextos [TaxContext], configurada con la cadena de conexión de la configuración;
  • línea 30: la capa [dao] es un [EfTax]: el contenedor le pasará la fábrica de contextos. Una capa [dao] singleton no puede recibir directamente un contexto, que tiene ámbito (scoped); de ahí la fábrica;
  • línea 32: la capa [business] de la versión 5;
  • línea 46: el cuadro de diálogo de la versión 5.

11.13.5. Ejecuciones

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: 

Se conservan los valores de referencia de las versiones anteriores: 4282 euros para una pareja casada con dos hijos y un ingreso conjunto de 60 000 euros, 2959 euros para una familia con tres hijos y 11 519 euros para una persona soltera sin hijos.

Con el archivo de configuración [tax-ef-error.json], que hace referencia a una base de datos 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'
----------------------------------------
  • línea 6: la excepción original, lanzada por el conector MySqlConnector, a través de EF Core;
  • línea 4: la capa [dao] la encapsuló dentro de una [TaxException], que el programa principal mostró.

El curso de 2008 demostraba, en la versión 7, que la capa [dao] podía cambiar de SGBD (de MySQL a SQL Server Compact) simplemente modificando el archivo de configuración, gracias al conector genérico de ADO.NET. Con EF Core, cambiar de SGBD equivale a cambiar de proveedor: reemplazar el paquete Pomelo por el de otro SGBD (por ejemplo, [Microsoft.EntityFrameworkCore.SqlServer]) y la llamada a [UseMySql] por la llamada correspondiente ([UseSqlServer]), y luego regenerar las migraciones, que contienen información específica del proveedor. El código de la clase [EfTax], escrito en LINQ, permanece sin cambios.

11.14. Conclusión: ¿ADO.NET, Dapper o EF Core?

Ahora tenemos dos maneras de acceder a una base de datos: ADO.NET (capítulo 10) y EF Core (este capítulo). Existe una tercera, intermedia y muy utilizada: Dapper, una pequeña biblioteca (un «micro-ORM») que agrega métodos de extensión a la conexión ADO.NET. Estos métodos ejecutan una consulta SQL escrita a mano y convierten automáticamente las filas del resultado en objetos: [connection.Query<Article>("SELECT * FROM articles WHERE Price > @price", new { price = 200 })]. Usted escribe el SQL y Dapper se encarga de asignar las columnas a las propiedades.

 
Fortalezas
Debilidades
ADO.NET
Control total sobre el SQL; rendimiento; sin dependencias
mucho código repetitivo (parámetros, lectura de columnas); SQL en cadenas, no verificado por el compilador
Dapper
SQL escrito a mano, pero sin el código de copia; rendimiento similar al de ADO.NET
Sin seguimiento de cambios ni generación de [INSERT]/[UPDATE]; sin migraciones
EF Core
Consultas LINQ verificadas por el compilador; seguimiento de cambios; relaciones; migraciones; independiente del SGBD
una capa adicional que comprender; SQL generado que hay que monitorear; menos adecuado para procesamientos masivos complejos

Se pueden proponer las siguientes pautas:

  • EF Core es adecuado para la mayoría de las aplicaciones de gestión: un modelo de entidades interrelacionadas, operaciones de lectura y actualización de entidades y un esquema que evoluciona con la aplicación. Es la opción predeterminada para las aplicaciones ASP.NET Core;
  • ADO.NET, o Dapper, es adecuado cuando se desea un control preciso sobre el SQL ejecutado: consultas de informes complejas, procedimientos almacenados, procesamiento de volúmenes muy grandes o una base de datos existente con un esquema poco adecuado para un modelo orientado a objetos;
  • Estos enfoques pueden combinarse: una aplicación puede usar EF Core para la mayor parte y código SQL escrito a mano (con [FromSql], [SqlQuery] o Dapper) para unas pocas consultas críticas. EF Core también da acceso a la conexión ADO.NET que utiliza ([context.Database.GetDbConnection()]).

En cualquier caso, conocer el ORM no elimina la necesidad de entender SQL y el funcionamiento del SGBD: el registro de los comandos SQL ejecutados, que hemos mostrado a lo largo de este capítulo, es la herramienta principal para verificar lo que EF Core realmente hace.

Para obtener más información, la documentación de Microsoft es completa: Entity Framework Core. El proveedor Pomelo está documentado en su repositorio: Pomelo.EntityFrameworkCore.MySql.