11. Entity Framework Core
上一章展示了 .NET 应用程序如何通过 ADO.NET 连接器与数据库通信:打开连接,编写 SQL 命令,逐列读取结果行,并将它们复制到对象中。这种复制过程——从行到对象,以及从对象到 [INSERT]、[UPDATE] 和 [DELETE] 命令——是重复性的。可以借助工具将其自动化:ORM (对象关系映射器)。本章介绍 Microsoft 的 Entity Framework Core (EF Core)。
2008 年的课程没有提到 ORM:它只是在数据库一章的结尾提到了“第三方数据访问框架”(NHibernate、iBatis)和 LINQ。Entity Framework 在几个月后发布(2008 年,随 .NET 3.5 SP1),2012 年作者为它专门编写了一门课程,题为“通过示例介绍 Entity Framework 5 Code First”。本章是全新的内容。它以第 10 章中的商品示例数据库为基础,最后给出税额计算应用程序的第 7 版,其 [dao] 层使用 EF Core。
11.1. 什么是 ORM?
11.1.1. 对象与表
C# 应用程序处理的是 对象:商品有名称、价格和库存量;订单有客户和订单行列表,每个订单行都引用一件商品。关系数据库则将同样的信息存储在 表 中:每件商品对应 [articles] 表中的一行,每个订单对应 [orders] 表中的一行,行与行之间的关系由外键表示。这两个世界并不完全吻合:
- 对象直接引用其他对象([order.Client]);行则包含另一行的主键值([ClientId]);
- 对象可以包含集合([order.Lines]);表只包含单个值;集合由另一个表中指向该订单的行来表示;
- C# 类型([string]、[decimal]、[DateOnly]、[bool])与 SQL 类型([varchar(30)]、[decimal(10,2)]、[date]、[tinyint(1)])并不相同;
- 对象用 C#(以及 LINQ)查询,而表用 SQL 查询。
ORM 在这两个世界之间架起桥梁。我们一劳永逸地定义类与表之间的映射(模型),之后由它负责:
- 将用 C# 编写的 LINQ 查询翻译成 SQL 和 [SELECT] 命令;
- 根据读取的行创建对象(这称为 实例化);
- 保存读取到的对象,并检测其中被修改、添加或删除的对象;
- 生成 [INSERT]、[UPDATE]、和 [DELETE] 命令,将这些更改反映到数据库中;
- 并在必要时,根据类创建和更新数据库架构(表、列、索引)。
使用 EF Core 和 MySQL 的应用程序的架构如下:

- [1]:应用程序。它的 [dao] 层不再与 ADO.NET 连接器通信,而是通过 [DbContext] 对象和 LINQ 查询与 EF Core 通信;
- [2]:EF Core,与 DBMS 无关:模型、LINQ 查询的翻译、变更跟踪、迁移;
- [3]:特定于 DBMS 的 EF Core 提供程序 (此处是用于 MySQL 的 Pomelo):它了解该 DBMS 的 SQL 方言及其列类型;
- [4]:该 DBMS 的 ADO.NET 连接器,即第 10 章中的那个(MySqlConnector):EF Core 并不取代 ADO.NET,而是使用它;
- [5]:DBMS。
11.1.2. EF Core 与 Entity Framework 6
有两个名为 Entity Framework 的产品:
- Entity Framework 6 (EF 6),最初的产品,为 Windows 上的 .NET Framework 设计(自 6.3 版起,它也可在 .NET Core 及其后续版本上运行)。它仍在维护,但不再积极开发;
- Entity Framework Core,一次完全重写的版本,于 2016 年随 .NET Core 发布。它可在所有 .NET 平台(Windows、Linux、macOS)上运行,所有新功能都在这个版本中提供。它的版本号与 .NET 保持一致:EF Core 8 对应 .NET 8,EF Core 9 对应 .NET 9,EF Core 10 对应 .NET 10。
对于新应用程序,我们使用 EF Core。这两个产品的 API 相似([DbContext]、[DbSet<T>]、LINQ、迁移),因此这里所述内容在很大程度上对 EF 6 同样适用。
11.1.3. 提供程序
EF Core 通过提供程序访问 DBMS,提供程序以 NuGet 包的形式分发。Microsoft 提供了 SQL Server、SQLite 和 Azure Cosmos DB 的提供程序;其他的由 DBMS 厂商或社区编写:用于 PostgreSQL 的 [Npgsql.EntityFrameworkCore.PostgreSQL] ,用于 Oracle 的 [Oracle.EntityFrameworkCore] ,用于 MySQL 的 [Pomelo.EntityFrameworkCore.MySql] 和 [MySql.EntityFrameworkCore] (来自 Oracle)。我们使用 Pomelo,这是使用最广泛的 MySQL 提供程序,它基于第 10 章中的 [MySqlConnector] 连接器。
提供程序是针对特定版本的 EF Core 编译的:Pomelo 9 适用于 EF Core 9,而 Pomelo 的版本通常比 EF Core 晚发布几个月。本课程使用 EF Core 9.0.0 和 Pomelo 9.0.0,运行在 .NET 10 上。这种组合是可行的:EF Core 9 面向 .NET 8([net8.0]),而为 .NET 8 编译的库 无需修改即可在 .NET 10 上运行。升级到 EF Core 10 只需修改包的版本号;除了生成的 SQL 中的一些细枝末节外,本章的代码应当无需修改即可运行。不过,在 LINQ 一节中,我们会遇到 EF Core 9 与 C# 14 编译器之间的一个小的不兼容问题。
本章使用的包如下:
包 | 作用 |
[Microsoft.EntityFrameworkCore] 9.0.0 | EF Core 本身 |
[Pomelo.EntityFrameworkCore.MySql] 9.0.0 | MySQL 提供程序;它包含 [Microsoft.EntityFrameworkCore.Relational] 和 [MySqlConnector] |
[Microsoft.EntityFrameworkCore.Design] 9.0.0 | 命令行工具 [dotnet ef] (迁移)所使用的代码 |
工具 [dotnet-ef] 9.0.0 | 命令行工具 [dotnet ef] |
[dotnet ef] 工具在开发机上一次性安装:
| > dotnet tool install --global dotnet-ef --version 9.0.0
|
.NET 的“全局”工具安装在用户主目录下的 [.dotnet/tools] 文件夹中,SDK 安装程序会将该文件夹添加到可执行文件路径中(在 Linux 上,必须自己添加:[export PATH=$PATH:$HOME/.dotnet/tools])。
11.1.4. Code First 与 Database First
EF Core 模型(类与表之间的映射)可以通过两种方式构建:
- Code First:编写 C# 类,由 EF Core 据此推导出数据库架构,它可以自行创建数据库,并随着应用程序的演进对其进行更新(迁移)。这是本章以及作者 2012 年的课程所采用的方法;
- Database First:数据库已经存在,使用 [dotnet ef dbcontext scaffold] 命令根据其架构生成类。这是需要与现有数据库协同工作的应用程序所采用的方法。生成的代码与我们手工编写的代码类似。
11.2. 第一个示例
11.2.1. 项目
本章中的每个示例都是一个控制台项目:用于迁移的 [dotnet ef] 工具需要 [.csproj] 项目文件。这些项目被归入 [11-efcore/11-efcore.slnx] 解决方案。第一个项目 [First] 使用以下命令创建:
| > 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
|
其项目文件如下:
| <Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<!-- EF Core 及其 MySQL 提供程序(Pomelo) -->
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
</ItemGroup>
</Project>
|
- 第 12–13 行:由 [dotnet add package] 添加的两个包。
所用的数据库是本地 MySQL 服务器上的 [efarticles] 数据库,该服务器就是 Laragon 服务器(见附录)。它不需要预先存在:EF Core 会创建它。
11.2.2. [Article] 实体
其对象存储在表中的类称为 实体。我们的第一个实体是一件商品,就像第 10 章中介绍的 2008 年课程里的 [articles] 表一样:
| namespace First;
// 商店的一篇文章:一个普通的 C# 类,与 EF Core 没有任何关联
public class Article
{
// 主键(按约定:名为 Id 的属性)
public int Id { get; set; }
// 表的其他列
public string Name { get; set; } = "";
public decimal Price { get; set; }
public int CurrentStock { get; set; }
public int MinimumStock { get; set; }
// 显示
public override string ToString() => $"[{Id}, {Name}, {Price}, {CurrentStock}, {MinimumStock}]";
}
|
- 第 4 行:一个普通的 C# 类。它不继承 EF Core 中的任何类,也没有任何特性;这称为 POCO (Plain Old CLR Object);
- 第 7 行:[Id] 属性将成为表的主键。这是 EF Core 的一项 约定 :名为 [Id] (或 [ArticleId],即类名后跟 [Id])的属性就是主键。由于它是整数类型,其值将由 DBMS 生成(MySQL 的 [AUTO_INCREMENT] 列);
- 第 9–12 行:每个公共读/写属性都会成为同名的列。[Name] 属性用空字符串初始化,以满足编译器的要求(启用了可为 null 的类型:[string] 类型的属性不得保持为 [null]);
- 第 15 行:商品的便捷显示方式。
11.2.3. 上下文
对数据库的访问通过 [DbContext] 类型的对象处理:
| using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Logging;
namespace First;
// 上下文:访问数据库 [efarticles] 的入口
public class ArticlesContext : DbContext
{
// 文章表
public DbSet<Article> Articles => Set<Article>();
// 上下文的配置:DBMS、连接字符串、日志
protected override void OnConfiguring(DbContextOptionsBuilder options)
{
const string connection = "Server=localhost;Port=3306;Database=efarticles;User=root;Password=";
options
// MySQL 提供程序和服务器版本
.UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36)))
// 显示发送到服务器的 SQL 语句
.LogTo(Console.WriteLine, [DbLoggerCategory.Database.Command.Name], LogLevel.Information);
}
}
|
- 第 7 行:[DbContext] 类派生自 EF Core。[ArticlesContext] 对象表示与数据库的 工作会话 :它在需要时打开连接,存储它读取的实体,并可以保存对这些实体的更改;
- 第 10 行:[DbSet<Article>] 表示 articles 表。LINQ 查询在这里执行,商品也在这里添加或删除。该属性被定义为表达式主体成员,调用 [Set<Article>()]:上下文中声明的每个 [DbSet<T>] 都会将类型 [T] 引入模型;
- 第 13 行:[OnConfiguring] 方法在首次使用上下文时由 EF Core 调用,用于配置上下文;
- 第 15 行:连接字符串,与第 10 章中的相同:服务器、端口、数据库、用户名和密码(Laragon 用户 [root] 的密码为空);
- 第 18 行:上下文使用 Pomelo 提供程序。第二个参数指定 MySQL 服务器版本:生成的 SQL 取决于它,因为某些功能只在较新的版本中可用。Laragon 提供 MySQL 8;我们指定版本 8.0.36。Pomelo 还提供 [ServerVersion.AutoDetect(connection)],它会查询服务器以确定其版本。这很方便,但每次配置上下文时都会额外产生一次连接,而且生成的 SQL 会取决于所遇到的服务器。显式指定版本可使应用程序的行为具有可重现性;
- 第 20 行:[LogTo] 方法指示 EF Core 使用 [Console.WriteLine] 方法写入日志。我们只保留 [DbLoggerCategory.Database.Command] 消息类别(即已执行的 SQL 命令的类别),级别为 [LogLevel.Information]。如果没有这个过滤器,日志会非常冗长。查看发送到服务器的 SQL 是理解 EF Core 行为的最佳方式:我们将在所有示例中这样做。
11.2.4. 程序
| using First;
// 一个 EF Core 上下文:它将在程序结束时被释放(连接也一并释放)
using var context = new ArticlesContext();
// 数据库被删除,然后根据 C# 模型重新创建
context.Database.EnsureDeleted();
context.Database.EnsureCreated();
// 添加三篇文章
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");
// 读取表
Console.WriteLine("--- reading the articles");
foreach (Article article in context.Articles.OrderBy(a => a.Name))
{
Console.WriteLine(article);
}
|
- 第 4 行:创建上下文。[using] 声明(C# 8)确保它在程序结束时被释放([Dispose]),从而关闭它可能已打开的所有连接;
- 第 7 行:[context.Database.EnsureDeleted()] 删除数据库(如果它存在);
- 第 8 行:[context.Database.EnsureCreated()] 根据架构创建数据库及其表。这两个方法便于用于示例和测试;真实的应用程序使用迁移来更新数据库,我们稍后会介绍;
- 第 11–13 行:向 [DbSet] 添加三件商品。此时还没有向服务器发送任何内容:上下文只是记住这三个对象需要被插入。我们没有为 [Id] 属性赋值,它将由 DBMS 生成;
- 第 15 行:[SaveChanges] 向服务器发送保存所存储更改所需的全部 SQL 命令,并返回受影响的行数;
- 第 20 行:对 [DbSet] 的 LINQ 查询:按字母顺序排列的商品。当 [foreach] 循环开始遍历它时,由 DBMS 执行该查询。
结果:
| > 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]
|
说明:
- 每条 SQL 命令前都有一个两行的标头:事件类型([CommandExecuted])、执行时间和命令参数;
- 第 4 行:[EnsureDeleted] 删除了数据库,该数据库此前已经存在(程序已经运行过);
- 第 7–20 行:[EnsureCreated] 创建了数据库,为其指定字符集 [utf8mb4](MySQL 的完整 Unicode 字符集),然后创建了表 [Articles] ,对应实体 [Article]:表名取自上下文属性 [DbSet] 的名称,列以属性命名,而列 [Id] 是带有生成值的主键([AUTO_INCREMENT])。所有列都是 [NOT NULL]:类型 [int] 和 [decimal] 不允许值 [null],类型 [string] 也不允许,因为启用了可为 null 的类型(稍后会再谈到这一点);
- 请注意默认类型:字符串对应 [longtext] (任意长度的文本),而 [decimal(65,30)] 对应 [decimal] (65 位数字,其中 30 位在小数点之后)。这些很少是我们想要的类型:下一段将说明如何指定类型;
- 第 21–41 行:[SaveChanges] 发送了一条包含三个参数化 [INSERT] 命令的单一命令。每个命令之后都跟着一个 [SELECT] ,用于读回 MySQL 生成的主键([LAST_INSERT_ID()]):EF Core 将其复制到被插入对象的 [Id] 属性中。参数值被屏蔽('?'):这些是应用程序数据,可能是机密的。调试时,可以通过在上下文配置中添加 [.EnableSensitiveDataLogging()] 选项来显示它们;
- 第 42–50 行:LINQ 查询 [context.Articles.OrderBy(a => a.Name)] 被翻译成 [SELECT ... ORDER BY] 命令。EF Core 为读取的每一行创建了一个 [Article] 对象。
我们没有编写任何 SQL 命令,也没有编写任何读取列的代码:这正是 ORM 的意义所在。我们同样可以看到,这并没有消除理解 SQL 的必要性:要判断生成的 SQL 是否正确、是否高效,就必须会阅读它。
11.3. 模型
EF Core 分三步根据实体构建其模型:
- 首先,应用其 约定;
- 然后使用应用于实体的 注解 (特性)对其进行补充或修正;
- 最后,应用在上下文的 [OnModelCreating] 方法中用 C# 编写的配置:即流式 API。
11.3.1. 约定
我们在第一个示例中已经看到了其中的要点:
- 任何带有 [get] 取值器和 [set] (或 [init])赋值器的公共属性,都存储在同名的列中;
- 属性 [Id] 或 [<Entity>Id] 是主键;如果它是整数,其值由 DBMS 生成;
- 表名取自上下文的 [DbSet] 属性的名称(若没有,则取类的名称);
- 可为 null 类型([int?]、[DateOnly?]、[string?])的属性会生成 [NULL] 列;不可为 null 类型([int]、[decimal],以及启用可为 null 引用类型时的 [string] )的属性会生成 [NOT NULL] 列;
- 引用另一个实体的属性,或实体集合属性,定义了一种关系(稍后会介绍)。
11.3.2. 注解与流式 API
[Model] 项目定义了两个以两种不同方式配置的实体。第一个使用注解进行配置:
| using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
namespace Model;
// 通过注解配置的实体
[Table("products")]
public class Product
{
// 主键不叫 Id:必须显式指定
[Key]
public int Code { get; set; }
// 必填字符串,最多 50 个字符
[Required, MaxLength(50)]
public string Name { get; set; } = "";
// 可空引用类型:允许 NULL 列
[MaxLength(200)]
public string? Description { get; set; }
// 强制指定列的名称和 SQL 类型
[Column("price_excl_tax", TypeName = "decimal(10,2)")]
public decimal PriceExclTax { get; set; }
// 可空值类型:允许 NULL 列
public DateOnly? WithdrawalDate { get; set; }
// 计算属性:没有对应的列
[NotMapped]
public decimal PriceInclTax => PriceExclTax * 1.2M;
}
|
- 第 1–2 行:所用的特性属于 .NET 的这两个命名空间。它们并非 EF Core 所特有:验证特性([Required]、[MaxLength])也用于验证 ASP.NET Core 表单中的数据;
- 第 7 行:表名;
- 第 11–12 行:主键不叫 [Id];由 [Key] 特性标识它;
- 第 15–16 行:一个必填列([Required]:[NOT NULL]),最多 50 个字符([MaxLength(50)]:[varchar(50)])。[Required] 在这里是多余的,因为不可为 null 的 [string] 类型就足以使该列成为必填;在 C# 8 之前它是必不可少的;
- 第 19–20 行:类型 [string?] 指定了一个可选的描述:该列将接受值 [NULL];
- 第 23–24 行:[Column] 指定列名及其 SQL 类型:[decimal(10,2)],10 位数字,其中包括 2 位小数;
- 第 27 行:一个可选日期。类型 [DateOnly] (.NET 6)表示不含时间的日期:Pomelo 将它与 SQL 类型 [date] 关联;
- 第 30–31 行:[NotMapped] 将属性排除在模型之外。这里并无必要:没有访问器([set])的属性不会被注册。该特性起到说明意图的作用。
第二个实体没有任何特性:
| namespace Model;
// 没有任何注解的实体:通过 Fluent API 配置
public class Supplier
{
public int Number { get; set; }
public string CompanyName { get; set; } = "";
public string? Phone { get; set; }
public DateTime CreationDate { get; set; }
}
|
它在上下文中通过流式 API 进行配置:
| using Microsoft.EntityFrameworkCore;
namespace Model;
// 一个仅用于检查模型的上下文:它从不连接服务器
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)));
}
// Fluent API:通过代码配置模型
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");
});
}
}
|
- 第 13 行:[efmodel] 数据库永远不会存在:此上下文仅用于检查模型,这不需要连接(服务器版本是显式指定的);
- 第 18 行:[OnModelCreating] 方法接收一个用于描述模型的 [ModelBuilder] 对象。每种上下文类型只调用它一次:EF Core 会缓存模型;
- 第 20 行:[Entity<Supplier>(...)] 接收一个用于配置 [Supplier] 实体的 lambda 表达式。每个方法都返回配置对象,因此调用可以链接起来:“流式 API”由此得名;
- 第 22 行:表名;
- 第 23 行:主键是属性 [Number];
- 第 24 行:一个必填列,最多 60 个字符;
- 第 25 行:公司名称上的唯一索引:任何两个供应商都不能同名。没有与之等效的验证特性;EF Core 提供了放在类上的 [Index] 特性,我们将在商品中使用它;
- 第 26 行:属性 [Phone] 存储在列 [tel] 中;
- 第 27 行:[CreationDate] 列有一个由 DBMS 计算的默认值。插入时,如果属性的值是其类型的默认值,EF Core 就不会为该列发送值,这样 DBMS 就可以使用 [CURRENT_TIMESTAMP]。
注解能做的一切都可以用流式 API 完成,而且流式 API 能做的更多(索引、默认值、复合键、复杂关系)。注解的优点是把配置放在属性旁边;流式 API 则让实体保持独立于 EF Core,并将配置集中在一处。两者经常混合使用:发生冲突时,流式 API 优先。
[Program.cs] 程序显示 EF Core 构建的模型,然后显示用于创建这些表的 SQL 脚本:
| using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata;
using Model;
using var context = new ModelContext();
// EF Core 构建的模型:实体、表、列
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}");
}
}
// 创建表的 SQL 脚本,不执行它
Console.WriteLine("--- creation script");
// (连续的空行已被移除)
Console.WriteLine(context.Database.GenerateCreateScript().Replace("\n\n\n", "\n\n").Trim());
|
- 第 8 行:上下文的 [Model] 属性提供对模型的访问:其实体([IEntityType]),以及每个实体的属性([IProperty]);
- 第 10 行:[ClrType] 是实体的 C# 类型,而 [GetTableName()] 是 其表的名称;
- 第 13–15 行:对于每个属性,显示列名、其 SQL 类型、它是否接受值 [NULL],以及它是否属于主键;
- 第 22 行:[Database.GenerateCreateScript()] 返回创建表的 SQL 脚本,但不执行它。这就是 [EnsureCreated] 将要执行的脚本。
结果:
| > 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`);
|
- 第 8–12 行:[Supplier] 实体及其列。SQL 类型来自配置([varchar(60)]、[varchar(20)]),或来自提供程序为 C# 类型所做的选择:[int] 对应 [int],[datetime(6)] (微秒精度)对应 [DateTime];
- 第 2–7 行:实体 [Product]。可为 null 的属性([DateOnly?]、[string?])生成 [NULL] 列;属性 [PriceInclTax] 没有出现在模型中;
- 第 16–33 行:创建脚本。它包含全部配置:表名和列名、数据类型([NOT NULL])、默认值、主键(整数键带有 [AUTO_INCREMENT] )以及唯一索引。文本列使用 [utf8mb4] 字符集。
11.3.3. 可为 null 的类型与 NULL 列
可为 null 的引用类型(C# 8,课程项目中通过 [<Nullable>enable</Nullable>] 启用)会影响模型:EF Core 会读取编译器生成的可为 null 性注解。[string] 属性 会生成 [NOT NULL] 列,而 [string?] 属性会生成 [NULL] 列。在未启用可为 null 类型的项目中,所有文本列都接受 [NULL],除了标有 [Required] 的列。
因此,必须谨慎地选择每个属性的类型:它既表达了 C# 代码规则(“该值可能缺失”),也表达了数据库约束。对于必填属性,有两种常见写法:
| // 一个默认值,用于满足编译器
public string Name { get; set; } = "";
// 必需成员(C# 11):创建对象的代码必须为其赋值
public required string Name { get; set; }
|
第二种更安全:编译器会拒绝 [new Article { Price = 10 }],因为其中遗漏了名称。EF Core 可以创建带有 [required] 成员的实体:它不经过 C# 代码的对象初始值设定项。对于指向另一个实体的导航属性(由 EF Core 自行填充),我们会遇到 [= null!] 这种写法:我们将在讨论关系时再看它。
11.4. 后续示例:两个共享库
以下各段中的示例都使用 [efarticles] 数据库及其 [articles] 表,表中填充了第 10 章中的六件商品。我们不在每个项目中重复定义实体和上下文,而是把它们放在类库 [Articles.Data] 中,由各项目引用。我们还将对示例而言过于冗长的 EF Core 日志替换为更紧凑的日志,放在第二个库 [Ef.Tools] 中。
11.4.1. 紧凑的 SQL 日志
| using System.Data.Common;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Diagnostics;
using Microsoft.Extensions.Logging;
namespace Ef.Tools;
// EF Core 所执行 SQL 语句的紧凑日志
public static class SqlLog
{
// DbContextOptionsBuilder 类型的扩展成员(C# 14)
extension(DbContextOptionsBuilder options)
{
// options.WithSqlLog():显示每条执行的 SQL 语句
public DbContextOptionsBuilder WithSqlLog() => options.LogTo(Filter, Display);
}
// 选定的事件:SQL 命令执行成功或失败、事务的开始和结束
private static bool Filter(EventId id, LogLevel level) =>
id == RelationalEventId.CommandExecuted || id == RelationalEventId.CommandError
|| id == RelationalEventId.TransactionStarted
|| id == RelationalEventId.TransactionCommitted || id == RelationalEventId.TransactionRolledBack;
// 显示一个事件
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;
}
}
// 显示 SQL 语句(带缩进),然后显示其参数
private static void DisplayCommand(DbCommand command)
{
// 忽略空行
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)}");
}
}
}
|
- 第 12–15 行:一个 扩展成员 (C# 14,见第 4 章),其目标类型为 [DbContextOptionsBuilder],也就是 [OnConfiguring] 参数的类型。我们将写成 [options.UseMySql(...).WithSqlLog()],就好像该方法是由 EF Core 编写的一样。它调用 [LogTo] 的另一个重载,该重载接受两个函数:一个用于选择要记录事件的过滤器,以及一个显示方法,后者接收事件本身([EventData])而不是预先格式化的文本;
- 第 19–22 行:所选择的事件。EF Core 中的每个事件都有一个标识符;与关系操作相关的标识符是 [RelationalEventId] 类的常量。我们记录已执行或失败的 SQL 命令,以及事务的开始、提交和回滚;
- 第 27–43 行:每种事件类型对应一个派生自 [EventData] 的类,该类提供有关事件的详细信息:[CommandExecutedEventData] 包含已执行的 ADO.NET 命令([DbCommand],见第 10 章)。选择通过 [switch] 完成,使用类型模式过滤和 [when] 子句;
- 第 52–54 行:命令文本,逐行缩进,并以 [SQL>] 开头,空行被移除;
- 第 56–60 行:命令的参数及其值。我们直接从命令中读取这些内容;因此,我们的日志总是显示它们,而 EF Core 的日志默认会隐藏它们。这对课程来说可以接受,但对生产应用程序则不然。
11.4.2. 商品的实体和上下文
[Articles.Data] 库中的 [Article] 实体使用上一段中的注解:
| using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using Microsoft.EntityFrameworkCore;
namespace Articles.Data;
// 商店的一篇文章,带有指定其表的注解
[Table("articles")]
[Index(nameof(Name), IsUnique = true)]
public class Article
{
// 主键,由 DBMS 生成(AUTO_INCREMENT)
public int Id { get; set; }
// 文章名称:必填,最多 30 个字符,唯一(参见 [Index])
[MaxLength(30)]
public required string Name { get; set; }
// 价格:10 位数字,其中小数点后 2 位
[Column(TypeName = "decimal(10,2)")]
public decimal Price { get; set; }
// 当前库存和最低库存,低于最低库存时需要补货
public int CurrentStock { get; set; }
public int MinimumStock { get; set; }
// 显示
public override string ToString() => $"[{Id}, {Name}, {Price}, {CurrentStock}, {MinimumStock}]";
}
|
- 第 8 行:表名为 [articles],与第 10 章相同;
- 第 9 行:EF Core 的 [Index] 特性(命名空间 [Microsoft.EntityFrameworkCore])在列 [Name] 上创建唯一索引:任何两件商品都不能同名,与 2008 年课程中的数据库一样;
- 第 16–17 行:必填的名称,不超过 30 个字符。该成员是 [required]:创建商品的代码必须指定其名称;
- 第 20–21 行:价格,类型为 [decimal(10,2)]。
上下文如下:
| using Ef.Tools;
using Microsoft.EntityFrameworkCore;
namespace Articles.Data;
// 数据库 [efarticles] 的上下文
public class ArticlesContext : DbContext
{
// 连接字符串和 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));
// 无参构造函数:配置由 OnConfiguring 完成
public ArticlesContext() { }
// 接收现成配置的构造函数(依赖注入)
public ArticlesContext(DbContextOptions<ArticlesContext> options) : base(options) { }
// 文章表
public DbSet<Article> Articles => Set<Article>();
// 默认配置,在构造函数没有收到配置时使用
protected override void OnConfiguring(DbContextOptionsBuilder options)
{
if (!options.IsConfigured)
{
// 并显示 SQL 语句(参见项目 [Ef.Tools])
options.UseMySql(Connection, MySqlVersion).WithSqlLog();
}
}
// (重新)创建数据库及其六篇文章,不输出日志
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();
}
}
|
- 第 10–11 行:连接字符串和服务器版本,它们是公共的,以便其他项目使用;
- 第 14 行:第一个构造函数,没有参数:配置将由 [OnConfiguring] 处理;
- 第 17 行:第二个构造函数,它接收一个预先配置好的对象([DbContextOptions<ArticlesContext>]),并将其传给 [DbContext] 类的构造函数。这是依赖注入所使用的构造函数(稍后会介绍);
- 第 25 行:两种情况下都会调用 [OnConfiguring] 。[IsConfigured] 检查上下文是否通过其构造函数收到了配置。如果没有,就使用默认配置:MySQL,并使用紧凑日志;
- 第 33–48 行:一个静态方法,用于重新创建数据库及其六件商品。它使用不含日志的配置创建上下文:我们不希望在示例结果中看到这次初始化产生的 SQL。[DbContextOptionsBuilder<T>] 是 [OnConfiguring] 所接收对象的泛型版本;它的 [Options] 属性返回构建好的配置。[AddRange] 一次添加多个实体。
示例项目引用 [Articles.Data] 库,该库又引用 [Ef.Tools]:
| <Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<!-- [Article] 实体和 [ArticlesContext] 上下文(含 EF Core) -->
<ProjectReference Include="../Articles.Data/Articles.Data.csproj" />
</ItemGroup>
</Project>
|
由 [Articles.Data] 引用的 EF Core 和 Pomelo 包,会被引用它的项目继承。
11.5. 基本操作:添加、读取、修改、删除
11.5.1. [Crud] 程序
[Crud] 项目演示了四种基本操作(CRUD:创建、读取、更新、删除):
| using Articles.Data;
using Microsoft.EntityFrameworkCore;
// 数据库被重新创建,包含它的六篇文章
ArticlesContext.Initialize();
using var context = new ArticlesContext();
// 1 - 按主键搜索
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 - 添加一篇文章
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 - 修改:修改对象就足够了
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 - 删除
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 - 上下文所跟踪的实体
Console.WriteLine("--- the tracked entities");
bike!.CurrentStock--;
context.ChangeTracker.DetectChanges();
Console.WriteLine(context.ChangeTracker.DebugView.LongView);
|
结果:
| > 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
|
说明:
- 第 10 行:[Find(1)] 搜索主键为 1 的记录。返回类型是 [Article?]:如果键不存在,[Find] 返回 [null] 。生成的 SQL(第 2–7 行)是一条参数化的 [SELECT],限定为一行;
- 第 13 行:对 [Find(1)] 的第二次调用不会发送任何 SQL 命令,并返回同一个对象(第 10 行)。上下文会存储它读取或添加的实体:在查询数据库之前,[Find] 会检查所请求的实体是否已被跟踪。一个上下文绝不会为数据库中的同一行包含两个对象;
- 第 18–19 行:添加商品。在 [SaveChanges] 之前,商品处于 [Added] 状态,其 [Id] 值为 0(第 12 行)。[SaveChanges] 发送一条 [INSERT] 命令,取回生成的键,并将其放入 [x.Id] (第 21 行)。商品随即转换为 [Unchanged] 状态:它与数据库中的行一致;
- 第 26 行:要修改数据库中的一行,只需修改对象。不需要 [Update] 方法:上下文保留了所读取值的副本(原始值),并将当前值与之比较。商品转换为 [Modified] 状态(第 23 行);
- 第 27 行:[context.Entry(x)] 提供对实体 [x] 的跟踪信息的访问:其状态([State]),以及每个属性的原始值([OriginalValue])和当前值([CurrentValue]);
- 第 29 行:生成的 [UPDATE] 命令(第 25–28 行)只修改发生变化的列 [Price]。随后是 [SELECT ROW_COUNT()]:EF Core 验证该命令确实修改了一行;
- 第 34–36 行:删除。[Remove] 将商品的状态改为 [Deleted];[SaveChanges] 发送 [DELETE] 命令。此后该对象不再被上下文跟踪:它处于 [Detached] 状态;
- 第 41–43 行:对象 [context.ChangeTracker] (“变更跟踪”)管理被跟踪的实体。[DetectChanges] 将实体的当前值与其原始值进行比较(EF Core 会在 [SaveChanges]、[Entry] 和其他几个方法中自动调用它)。属性 [DebugView.LongView] 返回所有被跟踪实体的描述(第 38–44 行):上下文现在只跟踪那辆自行车,其库存已从 10 减少到 9。[!] 运算符出现在 [bike!] 中,它告诉编译器 [bike],类型为 [Article?],在这里不是 [null] 。
Pomelo 生成的 SQL 的两个细节:
- 命令 [INSERT],以及随后读取所生成键的 [SELECT] ,被包含在一个事务中(第 13–20 行):该命令包含两条必须一起成功的 SQL 命令。我们稍后会回到事务上;
- 单独的命令 [UPDATE] 和 [DELETE] 没有被包含在事务中。它们之前有 [SET AUTOCOMMIT = 1],这是一个 MySQL 会话设置(每条命令一执行就提交),提供程序出于预防而将其恢复。正如我们将看到的,此设置对显式打开的事务没有影响。
11.5.2. 实体的状态
变更跟踪基于每个实体的状态,状态是 [EntityState] 枚举中的一个值:
状态 | 含义 |
[Detached] | 对象未被上下文跟踪(由 [new] 创建但尚未添加,或已从数据库中删除) |
[Added] | 对象已被添加到上下文([Add]):[SaveChanges] 会将其插入数据库 |
[Unchanged] | 对象是从数据库读取的(或已保存),此后未被修改 |
[Modified] | 至少有一个属性已被修改:[SaveChanges] 会发送 [UPDATE] 命令 |
[Deleted] | 对象已被标记为删除([Remove]):[SaveChanges] 会发送 [DELETE] 命令 |
请注意使用 EF Core 的工作周期:读取实体,像普通对象一样修改它们,添加和删除实体,然后调用 [SaveChanges],它会将所有必要的命令以单个批次发送到数据库。上下文起着“工作单元”的作用。上下文是一个轻量级对象,生命周期很短:一个工作单元,例如 Web 应用程序中的一次 HTTP 请求。不会在应用程序的整个生命周期内使用同一个上下文,否则它会不断累积被跟踪的实体。
11.5.3. 批量更新与不跟踪的读取
变更跟踪是有代价的:要为 100 件商品涨价,就必须读取全部 100 件商品,逐个修改,而 [SaveChanges] 会发送 100 条 [UPDATE] 命令。EF Core 7 引入了两个方法,它们直接发送覆盖查询所选全部行的 SQL 命令:[ExecuteUpdate] 和 [ExecuteDelete]。[BulkUpdate] 项目介绍了它们,以及只读操作:
| using Articles.Data;
using Microsoft.EntityFrameworkCore;
// 数据库被重新创建,包含它的六篇文章
ArticlesContext.Initialize();
using var context = new ArticlesContext();
// 1 - ExecuteUpdate:单条 UPDATE 语句,不把实体加载到内存
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:单条 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 - 不带更改跟踪的读取
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 忽略
articles[0].Price = 0;
Console.WriteLine($"SaveChanges: {context.SaveChanges()} row(s) modified");
// 4 - ExecuteUpdate 不会修改上下文已加载的实体
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}");
|
结果:
| > 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
|
说明:
- 第 10–12 行:[ExecuteUpdate] 作用于查询([Where]),并接收一个描述要修改的列的 lambda 表达式:[SetProperty(property, new value)]。新值可以取决于 行本身([a => a.MinimumStock * 2])。SQL 语句(第 3–5 行)会立即执行,无需 [SaveChanges],并返回被修改的行数;
- 第 16–18 行:低价商品涨价 10%。请注意,C# 代码中的常量([150]、[1.1M])被写入了 SQL 命令的文本中([150.0]、[1.1]);
- 第 23 行:[ExecuteDelete] 删除查询所选的行——在这里是那把弓,它是唯一价格超过 550 欧元的商品;
- 第 28 行:[AsNoTracking()] 请求 不跟踪的读取:读取的实体不会被上下文存储(第 26 行)。这样更快,也更节省内存:它用于只读取而不修改的数据(显示、计算)。代价是 [SaveChanges] 会忽略对这些实体的更改(第 27 行);
- 第 37–41 行:一个陷阱。[ExecuteUpdate] 直接作用于数据库:它不会修改上下文已加载的实体。被上下文跟踪的那辆自行车保留着旧价格(第 37 行),直到用 [context.Entry(bike).Reload()] 重新读取它。[Single] 返回查询中唯一的元素,如果元素为零个或多个,则抛出异常:这就是生成的 SQL 请求两行([LIMIT 2])的原因。
11.6. LINQ 翻译为 SQL
11.6.1. 查询
第 5 章介绍了针对内存集合的 LINQ。同样的运算符([Where]、[OrderBy]、[Select]、[First]、[Count]、[Sum]……)也适用于 [DbSet<T>],但它们不是由 .NET 执行的:EF Core 将它们翻译成 SQL,由 DBMS 执行。[Linq] 项目提供了几个示例:
| using Articles.Data;
using Microsoft.EntityFrameworkCore;
// 数据库被重新创建,包含它的六篇文章
ArticlesContext.Initialize();
using var context = new ArticlesContext();
// 1 - 过滤和排序
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 - 投影:只请求有用的列
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 - 单个结果;变量 [minPrice] 变成 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 - 聚合:由 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 - 被翻译成 SQL 的 .NET 方法
Console.WriteLine("--- StartsWith and Contains");
// 使用列表而不是数组(参见说明)
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 - 查询的 SQL,不执行它
Console.WriteLine("--- ToQueryString");
IQueryable<Article> query = context.Articles.Where(a => a.Price < 150).OrderBy(a => a.Price);
Console.WriteLine(query.ToQueryString());
// 7 - 分页:按价格升序排列的第三页,每页两篇文章
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 - EF Core 无法翻译的 C# 方法
Console.WriteLine("--- untranslatable method");
try
{
var list = context.Articles.Where(a => Rules.OutOfStock(a)).ToList();
}
catch (InvalidOperationException e)
{
// 我们只显示消息的第一句
int end = e.Message.IndexOf(" Either");
Console.WriteLine($"{e.GetType().Name} : {(end > 0 ? e.Message[..end] : e.Message)}");
}
// AsEnumerable:查询的其余部分由 .NET 在内存中执行
var outOfStock = context.Articles.AsEnumerable().Where(a => Rules.OutOfStock(a)).ToList();
outOfStock.ForEach(Console.WriteLine);
// 用 C# 编写的业务规则
static class Rules
{
// 如果文章的库存低于最低库存,则缺货
public static bool OutOfStock(Article a) => a.CurrentStock < a.MinimumStock;
}
|
结果:
| > 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]
|
说明:
- 第 10–13 行:[Where] 和 [OrderBy] 变成子句 [WHERE] 和 [ORDER BY] (第 5–6 行)。查询只在请求其结果时才执行,这里是由 [ToList] 触发:这就是 LINQ 的 延迟执行 (第 5 章);
- 第 18–20 行:投影。[Select] 为每件商品创建一个匿名类型的对象,只包含名称和库存价值。生成的 SQL(第 9 行)只检索相关的列,并自行完成计算。匿名类型的对象不是实体:它们不会被上下文跟踪。提供程序在乘法之前将库存(一个整数)转换为 [decimal(65,30)] ,这就解释了结果中为何有那么多小数位,随后使用 [{v.Value:0.00}] 对结果进行格式化;
- 第 30 行:[FirstOrDefault] 变成 [LIMIT 1]。程序变量 [minPrice] 成为 SQL 命令的参数([@__minPrice_0],第 21 行),而写在 lambda 表达式中的常量则被复制到 SQL 文本中。因此,无需担心 SQL 注入:来自程序外部的值始终作为参数传递。这就是第 10 章通过参数化查询手动应用的规则;
- 第 35–36 行:聚合 [Count] 和 [Sum] 由 DBMS 计算([COUNT(*)]、[SUM(...)]):只传输结果,而不传输行。[COALESCE(..., 0.0)] 在表为空时返回 0,就像 LINQ 的 [Sum] 一样;
- 第 42–45 行:EF Core 所了解的 .NET 方法会被翻译为 SQL:[a.Name.StartsWith("b")] 变成 [LIKE 'b%'],而引用内存列表的 [names.Contains(a.Name)],变成 [IN ('bow', 'pump', 'racket')] (第 35 行)。被翻译的方法有很多:对字符串、日期的操作以及数学函数;
- 第 51–52 行:[ToQueryString()] 返回查询的 SQL 文本而不执行它(第 37–41 行)。这对调试很有用;
- 第 57–60 行:分页,用于分页显示长列表。[Skip] 跳过前面各页的商品,而 [Take] 保留所请求页面的商品:它们变成子句 [OFFSET] 和 [LIMIT] (第 46 行)。分页只有在已排序的列表上才有意义([OrderBy]);
- 第 61 行:该投影包含一个插值字符串,EF Core 不会将其翻译为 SQL。这不是错误:当无法翻译的操作位于最后的 [Select] 中时,EF Core 会向 DBMS 请求所需的列([Name] 和 [Price]),并对读取的每一行在内存中执行该投影。请注意,价格按 en-US 区域设置格式化,使用小数点。
- 第 69–71 行:EF Core 无法翻译对程序中任何方法的调用:它不知道该方法的代码,即使知道,也不一定知道如何用 SQL 来表达它。执行查询会触发 [InvalidOperationException](第 50–51 行)。消息(与 .NET 中所有异常消息一样是英文的,程序只显示其第一句)随后给出两种解决办法:重写查询,或显式切换为内存中求值;
- 第 78 行:[AsEnumerable()] 将查询从 [IQueryable<T>] 转换为 [IEnumerable<T>]:前面的部分被翻译为 SQL(这里是读取整个表),后面的部分则由 LINQ 在内存中执行。结果是正确的,但整个表都被加载了:对于大表,应避免这样做。更好的做法是把条件写在 lambda 表达式中([a.CurrentStock < a.MinimumStock]),如第 11 行所示。
11.6.2. IQueryable 与表达式树
同一个 lambda 表达式,怎么既能在 C# 中对列表执行,又能在 [DbSet] 上被翻译为 SQL?第 7 章给出了答案:[DbSet<T>] 实现了 [IQueryable<T>] 接口,其方法 [Where]、[OrderBy]、[Select]……接收的不是委托([Func<T, bool>]),而是 表达式树 ([Expression<Func<T, bool>>])。编译器将 lambda 表达式 [a => a.CurrentStock < a.MinimumStock] 转换为描述它的数据结构(“参数 [a] 的属性 [CurrentStock] 与属性 [MinimumStock] 的比较 [<]”);EF Core 遍历这个结构并生成等效的 SQL。像 [Rules.OutOfStock] 这样的方法在树中只表现为一次方法调用,其代码无法被分析:因此会出错。
运算符是可组合的:查询可以分阶段构建,每个阶段都返回一个新的 [IQueryable<T>],只有最后的执行([ToList]、[First]、[Count]、[foreach]……)才会发送 SQL 命令:
| IQueryable<Article> query = context.Articles;
if (maxPrice != null)
{
query = query.Where(a => a.Price <= maxPrice);
}
query = query.OrderBy(a => a.Name);
// 单条 SELECT 语句,带或不带 WHERE
List<Article> articles = query.ToList();
|
11.6.3. EF Core 9 与 C# 14 之间的不兼容
在程序 [Linq] 中,列表 [names]被声明为 [List<string>] 类型而不是 [string[]],并附有引用本段的注释。如果使用数组,查询 [context.Articles.Where(a => names.Contains(a.Name))] 可以编译,但在运行时会失败,抛出 [InvalidOperationException] 错误(“An exception was thrown while attempting to evaluate a LINQ query parameter expression”)。实际上,C# 14 将数组到 [ReadOnlySpan<T>] (第 5 章介绍的类型)的转换变成了隐式的语言转换,它也适用于调用扩展方法的对象。因此,对于数组,调用 [names.Contains(...)] 现在引用的是扩展方法 [MemoryExtensions.Contains(ReadOnlySpan<T>, T)] 而不是 [Enumerable.Contains(IEnumerable<T>, T)]:检查 lambda 表达式的表达式树就能明显看出这一点,而用 C# 13 编译的同一个程序([<LangVersion>13</LangVersion>])找到的是 [Enumerable.Contains] ,可以正常运行。EF Core 9 发布于 C# 14 之前,不认识这个方法:它试图对数组到 [ReadOnlySpan<string>] 的转换求值,以便将其作为 SQL 参数,结果失败(内部异常是由表达式树解释器抛出的 [ArgumentException])。与 C# 14 同时发布的 EF Core 10 支持这种语法。使用 EF Core 9 时,可以像这里一样改用列表来绕过该问题,或者写成 [((IEnumerable<string>)names).Contains(a.Name)]。这是本章在 .NET 10 上使用 EF Core 9 时遇到的唯一问题。
11.7. 关系
11.7.1. 商店模型
数据库中的表彼此相连。EF Core 使用 导航属性来表示这些联系:导航属性是引用另一个实体或实体集合的属性。[Relations] 项目使用一个 [efshop] 数据库,它描述了一家小商店:
| namespace Relations;
// 一个类别包含多个产品(一对多关系)
public class Category
{
public int Id { get; set; }
public string Name { get; set; } = "";
// 导航属性:该类别的产品
public List<Product> Products { get; set; } = [];
}
// 一个产品属于一个类别,并带有多个标签
public class Product
{
public int Id { get; set; }
public string Name { get; set; } = "";
public decimal Price { get; set; }
// 指向类别的外键和导航属性
public int CategoryId { get; set; }
public Category Category { get; set; } = null!;
// 与标签的多对多关系
public List<Tag> Tags { get; set; } = [];
}
// 一个标签(促销、新品……)可被多个产品携带
public class Tag
{
public int Id { get; set; }
public string Label { get; set; } = "";
public List<Product> Products { get; set; } = [];
}
// 客户下订单
public class Client
{
public int Id { get; set; }
public string Name { get; set; } = "";
public List<Order> Orders { get; set; } = [];
}
// 客户的一个订单,由若干行组成
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; } = [];
}
// 一个订单行:某个产品的一定数量
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!;
}
|
- 一对多关系,存在于 [Category] 和 [Product] 之间:一个类别包含多个商品(第 9 行),一个商品属于一个类别(第 19–20 行)。属性 [CategoryId] 是 外键:按约定,是导航属性的名称后跟 [Id]。它在代码中是可选的(如果类中没有它,EF Core 会在表中创建它),但它很方便:无需加载商品的类别,就能确定该商品所属的类别;
- 多对多关系,存在于 [Product] 和 [Tag] 之间:一个商品有多个标签(第 22 行),一个标签与多个商品相关联(第 30 行)。这里没有外键:该关系将存储在由 EF Core 创建的关联表中;
- 一对多关系 [Client] - [Order] 和 [Order] - [OrderLine],以及多对一关系 [OrderLine] - [Product]:订单行表示某个商品的数量;
- 集合用空集合初始化([= []],一个 C# 12 的集合表达式)。指向单个实体的导航属性用 [null!] 初始化:值 [null] 带上运算符 [!],它告诉编译器不要把不可为 null 的属性被赋予 [null] 标记为问题。这是对由 EF Core 在读取操作期间自行填充的属性的惯用写法,在正确加载的实体中,该属性绝不会是 [null] 。这样的属性定义了强制关系(外键 [NOT NULL]);类型为 [Category?] 的属性加上类型为 [int?] 的键则会定义可选关系。
上下文如下:
| using Ef.Tools;
using Microsoft.EntityFrameworkCore;
namespace Relations;
// 数据库 [efshop] 的上下文;[log]:是否显示 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)
{
// 价格保留两位小数
modelBuilder.Entity<Product>().Property(p => p.Price).HasPrecision(10, 2);
}
}
|
- 第 7 行:上下文有一个主构造函数(C# 12),其可选参数 [log] 可以使日志中不输出 SQL;
- 第 9–13 行:五个 [DbSet]。实体不需要有 [DbSet] 才能成为模型的一部分:[OrderLine] 通过导航属性 [Order.Lines] 到达,实际上就是模型的一部分;
- 第 19 行:如有要求,则添加紧凑日志;
- 第 28 行:流式 API 设置价格精度。
由 [EnsureCreated] 创建的表如下:
| > 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
|
- 第 5–11 行:每个实体一张表。表 [OrderLine] 以类名命名,因为没有 [DbSet] 属性;表 [ProductTag] 是多对多关系的关联表;
- 第 22 行:外键 [CategoryId] 位于表 [Products] 中,引用表 [Categories]。选项 [ON DELETE CASCADE] 会在删除某个类别时删除该类别的商品:这是 EF Core 对强制关系的默认行为。EF Core 还会为每个外键创建一个索引(第 21 行);
- 第 26–32 行:关联表有两列,即指向两张被关联表的外键,二者共同构成其主键;
- 第 17 行:我们没有限制名称的长度,因此类型是 [longtext]。
11.7.2. 程序
| using Microsoft.EntityFrameworkCore;
using Relations;
// 1 - 创建数据库和第一批数据,不输出日志
using (var context = new ShopContext(log: false))
{
context.Database.EnsureDeleted();
context.Database.EnsureCreated();
// 两个标签
var promo = new Tag { Label = "promo" };
var novelty = new Tag { Label = "new" };
// 三个类别及其产品:我们添加一个对象图
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();
// 一个客户及其订单
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 - 一个客户、其订单及订单行,一次性添加
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 - 导航属性不会自动加载
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 - 使用 Include 和 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 - 显式加载集合
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 - 查询中的多对多关系
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 - 跨关系的计算,由 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 - 分组:每个类别的产品数量和平均价格
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"));
}
|
结果:
| > 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
|
说明:
- 第 13–32 行:添加三个类别及其商品和商品标签:一个 对象图。EF Core 遍历导航属性,并将遇到的所有实体添加到上下文。[SaveChanges] 按正确的顺序插入它们(先插入类别,再插入引用这些类别的商品),并填充外键和关联表。此初始化在不记录日志的情况下执行;
- 第 35–36 行:[DbSet] 的 [Local] 属性可以访问上下文已经跟踪的实体,而无需查询数据库;
- 第 56–71 行:一名客户、其订单及订单的两个订单行,通过一次对 [Add] 的调用添加。SQL(第 11–35 行)显示了插入的顺序:先是客户,然后是订单——其外键([ClientId])接收为客户生成的键([@p1=2])——最后是订单行,其外键([OrderId])接收订单的键;
- 第 79–80 行:默认情况下,EF Core 只加载所请求的实体。所读取订单的导航属性 [Client] 和 [Lines] 没有被填充(第 41 行):[Client] 等于 [null] (尽管声明为不可为 null,因此要用 [?.] 运算符),订单行列表为空。EF Core 支持懒加载:导航属性在首次读取时自动加载。它必须显式启用(包 [Microsoft.EntityFrameworkCore.Proxies],导航属性为 [virtual]);我们不使用它,因为它隐藏了数据库访问;
- 第 87–89 行:预先加载。[Include(c => c.Client)] 指示系统为每个订单加载客户;[Include(c => c.Lines)] 加载订单行,而 [ThenInclude(l => l.Product)] 为每个订单行加载商品。所有这些通过一条 [SELECT] 查询并使用连接一次加载完成(第 45–51 行)。显示结果包含两个订单及其订单行;
- 第 106 行:显式加载。我们加载一个已读取类别的商品集合:第二条查询 [SELECT],读取外键与该类别主键匹配的商品。对于指向单个实体的导航属性,我们写 [context.Entry(product).Reference(p => p.Category).Load()];
- 第 114–116 行:在 LINQ 查询中使用导航属性,无需 [Include]:[p.Tags.Any(...)] 变成针对关联表的子查询 [EXISTS] (第 72–76 行),而 [p.Category.Name] 变成连接;
- 第 125–126 行:跨两个关系的计算——每个订单的金额——完全由 DBMS 使用子查询完成(第 81–84 行);
- 第 135–138 行:分组。[GroupBy] 按类别名称对商品分组;对于每个分组([g]),键([g.Key])、商品数量([Count])和平均价格([Average])都由 DBMS 计算:查询变成 [GROUP BY] (第 90–93 行)。没有商品的类别 [diving] 不会出现:与类别表的连接是内连接([INNER JOIN])。
所谓的“N+1 查询”问题是任何 ORM 用户都面临的风险。假设我们想显示每个订单的客户名称,我们在不使用 [Include] 的情况下读取订单,然后通过显式加载(或延迟加载,其效果相同,只是我们没有意识到)为每个订单检索客户:我们先为 N 个订单执行一次查询,然后再执行 N 次查询,每个订单一次。对于一千个订单,这会导致与服务器往返一千零一次,而一次往返本就足够。解决办法就是示例中所展示的那些:[Include],或者更好的做法是使用只检索相关数据的投影([Select])。SQL 日志有助于发现该问题:同一条查询被重复了许多次。
11.8. 迁移
11.8.1. 原理
到目前为止,数据库都是先由 [EnsureDeleted] 删除,再由 [EnsureCreated] 创建的。这对于线上运行的应用程序是行不通的:其数据库包含的数据在模型演进(新增一列、新增一张表)时必须保留。此外,[EnsureCreated] 只能创建不存在的数据库:如果数据库已经存在并带有表,它什么也不做,即使模型已经改变。
迁移 正是为满足这一需求而设。迁移是一个 C# 类,由 [dotnet ef] 工具生成,它描述从模型的一个版本到下一个版本的过渡:其 [Up] 方法应用更改(创建表、添加列),而其 [Down] 方法则撤销更改。数据库中包含一张名为 [__EFMigrationsHistory] 的表,EF Core 在其中记录已应用于该数据库的迁移;这使它能够知道还有哪些迁移需要应用。
11.8.2. 项目
[Clients] 项目使用 [efclients] 数据库。其项目文件添加了 [Microsoft.EntityFrameworkCore.Design] 包,这是 [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 及其 MySQL 提供程序(Pomelo) -->
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
<!-- [dotnet ef] 工具(迁移)使用的代码:运行时无用 -->
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
</ItemGroup>
</Project>
|
- 第 15–18 行:元素 [PrivateAssets] (“all”)表示该包仅用于开发:它不会分发给引用本项目的项目,运行时也不需要它。这就是 [dotnet add package Microsoft.EntityFrameworkCore.Design] 命令的输出结果。
实体是一个客户:
| using System.ComponentModel.DataAnnotations;
namespace Clients;
// 一个客户
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; }
}
|
在应用程序的第一个版本中,客户没有电话号码:第 13–14 行尚不存在。我们将在第二个版本中添加它们。
[dotnet ef] 工具必须能够创建上下文以确定模型,并且对于某些命令,还要连接到数据库。为此,它依次使用:项目中实现 [IDesignTimeDbContextFactory<T>] 接口的类,或者 ASP.NET Core 应用程序的依赖注入容器,或者在这些都没有时,使用上下文的无参构造函数。我们来编写一个工厂:
| using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;
namespace Clients;
// 上下文通过其构造函数接收配置(主构造函数)
public class ClientsContext(DbContextOptions<ClientsContext> options) : DbContext(options)
{
public DbSet<Client> Clients => Set<Client>();
}
// [dotnet ef] 工具(以及我们的程序)使用的上下文工厂
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);
}
}
|
- 第 7 行:上下文通过主构造函数(C# 12)接收其配置,并将其传递给 [DbContext] 的构造函数。它没有 [OnConfiguring] 方法:它不知道自己使用哪个数据库,由创建它的代码来选择;
- 第 13–21 行:工厂。其[CreateDbContext]方法构建配置([DbContextOptionsBuilder<T>])并创建上下文。参数[args] 接收传递给该工具的任何参数;我们不使用它。
11.8.3. 第一次迁移
[dotnet ef]工具的命令在项目文件夹中输入。第一次迁移我们命名为[Initial],由[dotnet ef migrations add]命令创建:
| > dotnet ef migrations add Initial
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'
|
该工具编译了项目,使用工厂创建了上下文,将模型与上一次迁移的模型进行比较(目前还没有上一次迁移),并在名为[Migrations]的文件夹中生成了三个文件:
| 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
|
文件名以创建迁移的日期和时间开头(年、月、日、时、分、秒):迁移按此顺序应用。文件[ClientsContextModelSnapshot.cs] 包含对最后一次迁移之后模型状态的描述:该工具使用此文件与当前模型进行比较,以生成下一次迁移。这些文件是应用程序源代码的一部分:它们与其余代码一起存储和管理(例如放在 Git 仓库中)。
生成的迁移如下:
| 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");
}
}
}
|
- 第 9 行:迁移派生自[Migration]类;
- 第 12–32 行:[Up]方法使用[MigrationBuilder]对象描述要执行的操作:修改数据库字符集([AlterDatabase]),创建表[Clients] ([CreateTable])及其列和主键。注解[MySql:...] 包含 Pomelo 提供程序特有的信息;
- 第 36–39 行:[Down] 方法通过删除表来撤销迁移。
迁移的代码可以手动修改,例如添加工具无法从模型推断出的操作([migrationBuilder.Sql("...")] 可执行任意 SQL 命令)。
11.8.4. 应用迁移
命令[dotnet ef database update] 会将尚未应用的所有迁移应用到数据库;如果给出某个迁移的名称,则应用到该迁移(含)为止的所有迁移:
| > 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.
|
数据库[efclients] 原先并不存在:它已被创建。MySQL 的客户端[mysql] 显示其中的表:
| > 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 | |
+-------+--------------+------+-----+---------+----------------+
|
其中包含模型表[Clients] 和表[__EFMigrationsHistory],后者为每个已应用的迁移保存一行记录。
11.8.5. 第二次迁移
应用程序在不断演进:实体[Phone]属性,类型为[string?] 且限制为 20 个字符,被添加到实体[Client] 中(这是上文所示文件[Client.cs] 的版本)。创建一个新的迁移:
| > dotnet ef migrations add AddPhone
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'
|
该工具将当前模型与快照进行比较,并生成了以下迁移:
| 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");
}
}
}
|
- 第 13–18 行:[Up] 添加列[Phone],由于该属性的类型为[string?],因此该列是可选的。表中的现有行将被赋值为[NULL]。如果该属性是必填的([string]),就必须为现有行指定一个值:迁移会使用空字符串来完成,空字符串是该列的默认值([defaultValue: ""]);
- 第 25–27 行:[Down] 删除该列。
模型快照也已更新。以下是主要的变化:
| [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");
});
|
- 第 12 行:特性[DbContext] 将快照与上下文[ClientsContext]关联起来;
- 第 24–48 行:对实体[Client]的描述,使用流式 API 编写:每个属性、其 SQL 类型、长度、是否必填([IsRequired])、主键以及表。属性[Phone]也包含在其中(第 42–44 行)。通过将此模型与代码中的当前模型进行比较,该工具将确定下一次迁移的操作。此文件绝不应手动修改;若要撤销最后一次迁移(如果尚未应用),请使用[dotnet ef migrations remove],它会删除迁移文件并将快照恢复到之前的状态。
命令[dotnet ef migrations list] 列出项目的迁移,以及尚未应用到数据库的迁移:
| > dotnet ef migrations list
Build started...
Build succeeded.
20261003100720_Initial
20261003100726_AddPhone (Pending)
|
[dotnet ef migrations script]命令为一个迁移(或一系列迁移)生成 SQL 脚本而不执行它。当生产数据库不是由开发人员而是由管理员更新,且管理员希望自行审查并执行 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;
|
- 第 4–10 行:迁移在一个事务中执行:架构修改和向历史表添加迁移记录要么同时成功,要么同时失败。注意:在 MySQL 下,架构修改命令([ALTER TABLE]、[CREATE TABLE])会隐式提交当前事务。如果迁移执行到一半发生错误,数据库可能会停留在中间状态;
- 第 7 行:迁移被记录在历史表中,同时记录应用该迁移的 EF Core 版本。
11.8.6. 从应用程序中应用迁移
应用程序也可以在启动时自行应用迁移。[Clients]项目中的程序就是这样做的:
| using Clients;
using Microsoft.EntityFrameworkCore;
// 上下文由与 [dotnet ef] 工具相同的工厂创建
using ClientsContext context = new ClientsContextFactory().CreateDbContext(args);
// 迁移的状态
Console.WriteLine($"applied migrations: {string.Join(", ", context.Database.GetAppliedMigrations())}");
Console.WriteLine($"pending migrations: {string.Join(", ", context.Database.GetPendingMigrations())}");
// 应用待处理的迁移
context.Database.Migrate();
Console.WriteLine("Migrate(): the database is up to date");
// 新列可以使用了
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"}]");
}
|
- 第 5 行:使用该工具提供的工厂创建上下文;
- 第 8–9 行:已应用到数据库的迁移(从历史表读取)以及尚待应用的迁移;
- 第 12 行:[Migrate] 应用待处理的迁移(必要时创建数据库)。这等价于[dotnet ef database update];
- 第 16–20 行:使用新增的列。
结果:
| > 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]
|
第二次迁移由程序应用。历史表现在包含这两次迁移:
| > mysql -uroot -t efclients -e "SELECT * FROM __EFMigrationsHistory"
+-------------------------+----------------+
| MigrationId | ProductVersion |
+-------------------------+----------------+
| 20261003100720_Initial | 9.0.0 |
| 20261003100726_AddPhone | 9.0.0 |
+-------------------------+----------------+
|
在启动时应用迁移对于小型应用程序或开发期间很方便。对于部署在多台服务器上的大型应用程序,最好将其作为部署过程中的单独一步来应用(SQL 脚本,或由[dotnet ef migrations bundle]生成的迁移可执行文件)。请注意以下几点:
- [EnsureCreated]:适用于示例、测试和原型,此时数据库可以被删除并重新创建;
- 迁移:一旦数据库中包含需要保留的数据就应使用迁移。两者不应混用:由[EnsureCreated] 创建的数据库没有历史表,因此无法对其应用迁移。
11.9. 异步
数据库查询是一种 I/O 操作:服务器在工作时,等待的线程什么也不做。第 9 章展示了如何使用[async] 和[await]释放这个线程。EF Core 为所有访问数据库的方法提供了异步版本:[ToListAsync]、[FirstOrDefaultAsync]、[SingleAsync]、[CountAsync]、[SumAsync]、[FindAsync]、[SaveChangesAsync]等。它们定义在[Microsoft.EntityFrameworkCore]命名空间中(而不是[System.Linq])。[Async]项目使用了它们:
| using Articles.Data;
using Microsoft.EntityFrameworkCore;
// 数据库被重新创建,包含它的六篇文章
ArticlesContext.Initialize();
// 上下文以异步方式释放(await using)
await using var context = new ArticlesContext();
// 1 - 异步查询
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 - 异步保存
Console.WriteLine("--- SaveChangesAsync");
bow!.Price = 550;
int nbRows = await context.SaveChangesAsync();
Console.WriteLine($"{nbRows} row(s) modified");
// 3 - 异步流:行在读取时被处理
Console.WriteLine("--- await foreach");
await foreach (Article article in context.Articles.AsNoTracking().Where(a => a.Price >= 300).AsAsyncEnumerable())
{
Console.WriteLine($"read: {article.Name}");
}
// 4 - 取消
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}");
}
|
结果:
| > 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.
|
说明:
- 第 7 行:[DbContext] 实现了[IAsyncDisposable]:[await using] (C# 8,第 9 章)以异步方式释放它;
- 第 11 行:[ToListAsync] 执行查询并返回[Task<List<Article>>]。查询本身([Where]、[OrderBy])的写法与之前相同:只有执行它的方法发生了变化;
- 第 14–15 行:[FirstOrDefault] 和[Count]的异步版本;
- 第 21 行:异步保存;
- 第 26 行:[AsAsyncEnumerable()] 将查询作为异步流返回([IAsyncEnumerable<T>],第 9 章),并使用[await foreach]对其进行迭代。实体在读取时即被处理,无需构成列表:这对于处理大量行很有用;
- 第 33–39 行:异步方法接受[CancellationToken] (第 9 章)。这里,令牌在调用之前就已被取消:[ToListAsync] 立即抛出 [OperationCanceledException](第 34 行)。在 Web 应用程序中,会传入 HTTP 请求的令牌:如果客户端中止请求,当前的读取操作就会被中断。
一条重要规则:上下文不是线程安全的,一次只接受一个操作。不要在同一个上下文上同时发起两个请求(例如使用[Task.WhenAll]):必须等待([await])一个操作完成后才能开始另一个操作。EF Core 通常能检测到这个错误并抛出 [InvalidOperationException] (“在上一个操作完成之前,此上下文实例上已启动第二个操作”),但并非总是如此。对于真正并行的请求,每个任务使用一个上下文。
在像我们的示例这样的控制台应用程序中,异步并不会带来明显的好处。它在服务器应用程序(第 12 章和第 13 章)中尤其有价值,在那里,SQL 请求期间被释放的线程可以为其他客户端提供服务。这就是 ASP.NET Core 应用程序始终使用 EF Core 异步方法的原因。
11.10. 事务与并发
11.10.1. 事务
第 10 章介绍了事务:一组要么全部成功、要么全部失败的操作。使用 EF Core 时,有两个要点需要注意:
- [SaveChanges] 是事务性的:如果它发送多条命令,就会在一个事务中执行这些命令。如果其中任何一条失败,则都不会提交,并且[SaveChanges] 会抛出 [DbUpdateException];
- 若要将对[SaveChanges] 的多次调用(或诸如[ExecuteUpdate]、[ExecuteSql]等命令)归入同一个事务,可使用[context.Database.BeginTransaction()] (或其异步版本)开启显式事务,用[Commit]提交,用[Rollback]回滚。
[Transactions]项目演示了这两种情况:
| using Articles.Data;
using Microsoft.EntityFrameworkCore;
// 数据库被重新创建,包含它的六篇文章
ArticlesContext.Initialize();
// 1 - SaveChanges 是事务性的:要么全部成功,要么全部失败
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)
{
// DBMS 错误是内部异常
Console.WriteLine($"{e.GetType().Name} : {e.InnerException?.Message}");
}
}
await DisplayAsync("racket");
// 2 - 跨越多个 SaveChanges 的显式事务
Console.WriteLine("--- explicit transaction rolled back");
await using (var context = new ArticlesContext())
{
await using var transaction = await context.Database.BeginTransactionAsync();
try
{
// 出售两辆自行车
Article bike = await context.Articles.SingleAsync(a => a.Name == "bike");
bike.CurrentStock -= 2;
await context.SaveChangesAsync();
// 添加一篇名称已存在的文章:出错
context.Articles.Add(new Article { Name = "pump", Price = 12, CurrentStock = 5, MinimumStock = 1 });
await context.SaveChangesAsync();
// 提交整个事务(这里不会执行到这一步)
await transaction.CommitAsync();
}
catch (DbUpdateException e)
{
Console.WriteLine($"{e.GetType().Name} : {e.InnerException?.Message}");
// 取消事务的所有操作
await transaction.RollbackAsync();
}
}
// 自行车的出售已被取消
await DisplayAsync("bike");
// 用新的上下文显示从数据库读取的一篇文章
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"}");
}
|
结果:
| > 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]
|
说明:
- 第 11–15 行:添加了两个商品,其中第二个与现有商品同名。[SaveChanges] 开启一个事务(第 3 行)并发送两条 [INSERT] 语句。第二条违反了[Name] 列上的唯一索引:MySQL 拒绝该插入,并且[SaveChanges] 抛出 [DbUpdateException],其内部异常是来自 DBMS 的错误(第 15 行)。该事务没有被提交:它被放弃,其操作由 MySQL 回滚。已成功插入的球拍不在数据库中(第 21 行);
- 第 29 行:显式事务。返回的对象([IDbContextTransaction])由[await using]释放:如果它尚未提交,事务将在此处回滚;
- 第 33–35 行:第一个 [SaveChangesAsync] 记录了两辆自行车的销售。由于已有事务在进行,[SaveChanges] 不会启动新的事务;而是并入现有事务。位于,[UPDATE] 之前(第 28 行)的命令 [SET AUTOCOMMIT = 1] 不会提交当前事务:后面的几行表明这次销售确实会被取消;
- 第 37–38 行:第二次保存失败(第 38–40 行);
- 第 40 行:永远不会执行到提交;
- 第 46 行:在[catch]中,事务被回滚(第 41 行)。自行车的销售虽然已由第一个[SaveChangesAsync]记录,但被取消了:自行车库存仍为 10(第 47 行);
- 第 53–57 行:一个异步本地函数,它使用新的上下文重新读取某个商品,以查看数据库的实际状态,而不是工作上下文所跟踪的实体。
11.10.2. 乐观并发
两个用户读取同一个商品,其库存为 10。第一个用户卖出一件并将库存更新为 9。第二个用户在此次更新之前读取了库存,卖出三件并将库存更新为 7:第一个用户的销售丢失了。这就是丢失更新问题。
一种解决方案是在每个用户操作的整个期间锁定该行(“悲观”并发):这会阻塞其他用户,有时会阻塞很长时间。EF Core 实现的是乐观并发:不锁定任何内容,但在提交时,系统会验证该行自读取以来是否被修改过。为此,需要将一个或多个属性指定为并发令牌:EF Core 会在[WHERE]子句中为[UPDATE] 和[DELETE] 语句添加条件“令牌仍为读取时的值”。如果命令没有修改任何行,就意味着其他用户已经处理过这些行:EF Core 会抛出 [DbUpdateConcurrencyException]。
[Concurrency]项目将库存变为并发令牌。它没有修改其他示例共用的[Article]实体,而是派生出上下文,并使用流式 API 补充模型:
| using Articles.Data;
using Microsoft.EntityFrameworkCore;
namespace Concurrency;
// 文章上下文,其中库存成为并发令牌
public class ArticlesConcurrencyContext : ArticlesContext
{
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
base.OnModelCreating(modelBuilder);
// 每次 UPDATE 或 DELETE 时,都会检查读取到的库存值
modelBuilder.Entity<Article>().Property(a => a.CurrentStock).IsConcurrencyToken();
}
}
|
- 第 11 行:保留父类的配置;
- 第 13 行:属性[CurrentStock] 成为并发令牌。等效的注解是应用于该属性的[ConcurrencyCheck]特性。
程序用两个上下文模拟这两个用户:
| using Articles.Data;
using Concurrency;
using Microsoft.EntityFrameworkCore;
// 数据库被重新创建,包含它的六篇文章
ArticlesContext.Initialize();
// 两个用户,两个上下文:各自读取同一篇文章
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");
// 用户 1 出售 1 辆自行车
Console.WriteLine("--- user 1 sells 1 bike");
bike1.CurrentStock -= 1;
context1.SaveChanges();
Console.WriteLine($"stock saved by user 1: {bike1.CurrentStock}");
// 用户 2 基于过时的数据出售 3 辆自行车(库存 = 10)
Console.WriteLine("--- user 2 sells 3 bikes");
bike2.CurrentStock -= 3;
try
{
context2.SaveChanges();
}
catch (DbUpdateConcurrencyException e)
{
// 我们只显示消息的第一句
Console.WriteLine($"{e.GetType().Name} : {e.Message[..(e.Message.IndexOf('.') + 1)]}");
// 解决办法:我们从数据库重新读取该文章并重做出售
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}");
}
|
结果:
| > 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
|
说明:
- 第 12–13 行:每个用户在各自的上下文中读取自行车;
- 第 17–18 行:第一个用户的 [UPDATE] 命令 包含条件[CurrentStock = @p2],其值为读取到的 10(第 13–16 行)。该行被修改;
- 第 23–26 行:第二个用户的命令包含相同的条件,其值为他们读取到的 10,而此时数据库中的库存为 9。没有任何行被修改:[SELECT ROW_COUNT()] 返回 0,EF Core 抛出 [DbUpdateConcurrencyException] (第 24 行);
- 第 34–36 行:异常的[Entries]属性列出发生冲突的实体。如何解决取决于应用程序:中止、提醒用户,或者像这里一样,从数据库重新读取实体([Reload])并重复该操作。重新读取到的库存为 9(第 31 行),卖出三辆自行车后库存为 6,条件为[CurrentStock = 9] (第 36 行)。
最常见的并发令牌不是业务数据,而是在每次更新行时都会修改的专用列:版本号或修改日期。在 SQL Server 下,标有[byte[]] 特性[Timestamp] 的属性会与类型[rowversion]关联,该类型由 DBMS 自动修改;在 MySQL 下,通常使用一个整数或日期,由应用程序(或触发器)在每次更新时修改。
11.11. 原生 SQL
EF Core 根据 LINQ 生成 SQL,但仍然可以自己编写查询的 SQL,以使用 DBMS 特有的功能或优化复杂查询。[RawSql]项目介绍了可用的方法:
| using Articles.Data;
using Microsoft.EntityFrameworkCore;
// 数据库被重新创建,包含它的六篇文章
ArticlesContext.Initialize();
using var context = new ArticlesContext();
// 1 - FromSql:手写的、返回实体的 SQL 查询
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 - 插值会产生参数:不可能发生 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");
// 通过拼接构建的同一个查询:千万不要这样做
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:非实体的结果(列名为 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:一条 update 语句
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");
|
结果:
| > 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
|
说明:
- 第 11–13 行:[FromSql] 执行返回实体表中各行的 SQL 查询并实例化实体(由上下文跟踪)。它的参数是一个插值字符串:EF Core 不会将其转换为文本;而是接收一个[FormattableString]对象,其中文本和要插入的值是分开存放的,并将每个值转换为 SQL 参数([@p0],第 5 行)。[FromSql] 的结果是 [IQueryable<T>]:可以用 LINQ 继续补充。[OrderBy] 子句是由 EF Core 在我们的查询外围添加的,我们的查询因而变成了子查询;
- 第 19–20 行:一次 SQL 注入尝试。[name] 的值作为参数传递:它被原样与[Name] 列进行比较,没有记录匹配(第 18 行);
- 第 24 行:通过拼接构造并传递给[FromSqlRaw]的同一个查询,它会执行提供给它的文本。[name] 的值变成了 SQL 代码,条件始终为真,查询返回全部六个商品(第 24 行):这是一次成功的 SQL 注入。[FromSqlRaw] 只应与常量文本一起使用,并将值作为参数传递([FromSqlRaw("... WHERE Name = {0}", name)]);
- 第 29–31 行:[Database.SqlQuery<T>] (EF Core 7 支持简单类型,EF Core 8 支持其他类型)执行返回任意类型值的查询,这里是字符串。对于简单类型,返回的列必须命名为[Value] (别名[AS Value]):这是 EF Core 使用 LINQ 构造查询时所用的名称,就像接下来的[Single] (第 28–32 行)那样。[SqlQuery] 也接受任何类,其属性会被赋予同名的列;
- 第 40–42 行:[Database.ExecuteSql] 执行更新命令,同样通过插值进行参数化,并返回被修改的行数。
所有这些方法都有异步版本(对[ToListAsync] 调用[FromSql]的结果,以及[ExecuteSqlAsync])。
11.12. 上下文与依赖注入
前面的示例使用[new]创建上下文。在分层应用程序以及所有 ASP.NET Core 应用程序中,上下文由第 6 章介绍的依赖注入容器创建。为此,EF Core 提供了[IServiceCollection]的两个扩展方法:
- [AddDbContext<T>(options => ...)] 以“[T]作用域”生存期注册上下文:容器为每个作用域创建一个上下文,将其提供给该作用域内所有请求它的服务,并在作用域结束时释放它。在 Web 应用程序中,每个 HTTP 请求都会创建一个作用域:每个请求都有自己的上下文,这对应于上下文的工作单元;
- [AddDbContextFactory<T>(options => ...)] 注册上下文工厂,[IDbContextFactory<T>],其方法[CreateDbContext] 在每次调用时创建一个新的上下文。它用于长时间运行的服务(单例),这类服务无法在应用程序的整个生命周期内保持同一个上下文;也用于并行处理,并行处理要求每个任务使用一个上下文。
在这两种情况下,lambda 表达式都会接收一个 [DbContextOptionsBuilder] ,并像 [OnConfiguring] 那样配置上下文;上下文必须有一个接受 [DbContextOptions<T>] 的构造函数,就像 [ArticlesContext] 类中的那个。
[Injection]项目引用了[Microsoft.Extensions.DependencyInjection]包(版本 10.0.12,与第 6 章相同)。它定义了两个服务:
| using Articles.Data;
using Microsoft.EntityFrameworkCore;
namespace Injection;
// 通过注入接收上下文的服务:它的生命周期与上下文相同
public class ArticlesDao(ArticlesContext context)
{
// 需要补货的文章
public List<string> ArticlesOutOfStock() =>
context.Articles.Where(a => a.CurrentStock < a.MinimumStock).Select(a => a.Name).ToList();
}
// 长生命周期的服务:它接收一个上下文工厂
public class StatisticsService(IDbContextFactory<ArticlesContext> factory)
{
// 每次调用使用一个新的上下文,用完立即释放
public async Task<decimal> StockValueAsync()
{
await using ArticlesContext context = await factory.CreateDbContextAsync();
return await context.Articles.SumAsync(a => a.Price * a.CurrentStock);
}
}
|
- 第 7 行:一个通过(主)构造函数接收上下文的服务。它必须以与上下文相同的生存期(作用域)进行注册;
- 第 15 行:一个接收上下文工厂的服务;
- 第 20 行:对该方法的每次调用都会创建一个上下文并立即释放它。
程序如下:
| using Articles.Data;
using Injection;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
// 数据库被重新创建,包含它的六篇文章
ArticlesContext.Initialize();
// 1 - AddDbContext:上下文以 "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())
{
// 在同一个作用域内,我们总是得到同一个上下文
contextOfScope1 = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
var context = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
Console.WriteLine($"scope 1: same context = {ReferenceEquals(context, contextOfScope1)}");
// [ArticlesDao] 服务收到了这个上下文
var dao = scope.ServiceProvider.GetRequiredService<ArticlesDao>();
Console.WriteLine($"scope 1: out of stock = {string.Join(", ", dao.ArticlesOutOfStock())}");
}
using (IServiceScope scope = provider.CreateScope())
{
// 另一个作用域:另一个上下文
var context = scope.ServiceProvider.GetRequiredService<ArticlesContext>();
Console.WriteLine($"scope 2: same context as in scope 1 = {ReferenceEquals(context, contextOfScope1)}");
}
// 作用域结束时,上下文已被释放
try
{
contextOfScope1.Articles.Count();
}
catch (ObjectDisposedException e)
{
Console.WriteLine($"{e.GetType().Name} : {e.Message[..(e.Message.IndexOf('.') + 1)]}");
}
// 2 - AddDbContextFactory:用于长生命周期服务的上下文工厂
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");
|
结果:
| > 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
|
说明:
- 第 11–12 行:上下文注册。这里给出的配置就是上下文构建器所接收的配置:因此[OnConfiguring] 将[options.IsConfigured] 判定为 true,不会添加 SQL 日志。可以在这里通过[WithSqlLog]添加;
- 第 13 行:服务[ArticlesDao],它同样是作用域服务;
- 第 17 行:[CreateScope()] 创建一个作用域。“作用域”服务从该作用域的服务提供者([scope.ServiceProvider])获取;
- 第 20–22 行:在同一作用域内两次请求上下文,返回的是同一个对象(第 2 行);
- 第 24 行:容器通过向服务[ArticlesDao] 传入该作用域的上下文来创建它;
- 第 27–31 行:另一个作用域获得不同的上下文(第 4 行);
- 第 36–38 行:在其作用域结束时,上下文已被容器释放;使用它会抛出 [ObjectDisposedException]。这是长时间运行的服务常见的错误:它保留了在某个作用域内接收到的上下文;
- 第 45–47 行:上下文工厂和使用它的单例服务。该服务可以与应用程序一样长寿:它不持有上下文,而是在每次计算时创建一个新的上下文。
请牢记上下文生存期的规则:生命周期短(一个工作单元)、绝不在多个线程之间共享、并且始终要释放([using],或由容器释放)。
11.13. 示例应用程序——版本 7
11.13.1. 架构
税款计算应用程序的版本 6(第 10 章)使用 ADO.NET 从 MySQL 数据库读取税率档次。版本 7 使用 EF Core 完成同样的工作。与版本 6 一样,只有[dao]层发生变化:版本 5(第 6 章)中的 [business] 和 [ui] 层通过项目引用原样复用。

解决方案在[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. [dao]层
[Tax.Dao.Ef]项目引用版本 5 的[dao]层,该层包含实体([TaxBracket]、[TaxException])以及接口[ITaxDao]:
| <Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<!-- 第 5 版的 [dao] 层:实体、ITaxDao 接口、HardwiredTax -->
<ProjectReference Include="../../../06-architectures/TaxV5/Tax.Dao/Tax.Dao.csproj" />
</ItemGroup>
<ItemGroup>
<!-- EF Core 及其 MySQL 提供程序 -->
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
<!-- 供 [dotnet ef] 工具使用(迁移) -->
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
</ItemGroup>
</Project>
|
- 第 11 行:使用相对路径对版本 5 中[Tax.Dao]项目的引用;
- 第 16–19 行:EF Core、Pomelo,以及[dotnet ef]工具所需的包。
版本 5 中的[Entities.TaxBracket]结构不能作为 EF Core 实体:它是一个[readonly record struct],不可修改且没有主键。它不被修改,因为它是各层之间契约的一部分,由所有版本共享。因此为持久化实体专门创建了一个属于[dao]层的实体,其作用是表示表中的一行:
| using System.ComponentModel.DataAnnotations.Schema;
namespace Dao;
// 存储在数据库中的税率档次:一个 EF Core 实体
[Table("brackets")]
public class TaxBracketEntity
{
// 主键,它在 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; }
}
|
- 第 6 行:表[brackets],与 2008 年课程的版本 7 相同;
- 第 10 行:主键,也用于对各档次排序;
- 第 12–19 行:三个列,使用合适的[decimal]数据类型:上限和系数[coeffN] 是带两位小数的金额,而[coeffR] 是带四位小数的比率。
上下文:
| using Microsoft.EntityFrameworkCore;
namespace Dao;
// 数据库 [eftaxes] 的上下文:它通过构造函数接收配置
public class TaxContext(DbContextOptions<TaxContext> options) : DbContext(options)
{
// 税率档次表
public DbSet<TaxBracketEntity> Brackets => Set<TaxBracketEntity>();
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
// 种子数据:HardwiredTax 类(第 5 版)的档次,
// 从 1 开始编号;它们将由迁移插入
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);
}
}
|
- 第 6 行:上下文通过其构造函数进行配置:由主程序选择数据库;
- 第 15–17 行:种子数据。为避免重写税率档次,我们复用版本 5 中类[HardwiredTax] 里的档次,并借助提供元素索引的 [Select] 重载从 1 开始为它们编号;
- 第 18 行:[HasData] 声明属于模型的行。迁移会将它们插入表中,如果它们发生变化,下一次迁移将包含必要的 [UPDATE]、[INSERT] 或 [DELETE] 命令。必须显式指定主键,以便工具能够跨版本比较数据。
工具[dotnet ef]使用的工厂:
| using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;
namespace Dao;
// [dotnet ef] 工具用来创建上下文的工厂(迁移)
public class TaxContextFactory : IDesignTimeDbContextFactory<TaxContext>
{
public TaxContext CreateDbContext(string[] args)
{
// 开发数据库;运行时,连接字符串来自配置
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);
}
}
|
它仅在开发期间由该工具使用:开发数据库的连接字符串在其中是硬编码的。在运行时,连接字符串来自应用程序的配置文件。
[EfTax]类实现了[ITaxDao]接口:
| using System.Data.Common;
using Entities;
using Microsoft.EntityFrameworkCore;
namespace Dao;
// 使用 EF Core 从数据库读取税率档次的 [dao] 层
public class EfTax : ITaxDao
{
// 此实现特有的错误代码
public enum ErrorCodes { Access = 1, EmptyTable = 2 }
// 税率档
public TaxBracket[] TaxBrackets { get; }
// 构造函数:注入上下文工厂
public EfTax(IDbContextFactory<TaxContext> factory)
{
try
{
// 短生命周期的上下文,仅用于读取表的这段时间
using TaxContext context = factory.CreateDbContext();
// 持久化实体被投影到应用程序的实体上
TaxBrackets = context.Brackets
.AsNoTracking()
.OrderBy(t => t.Id)
.Select(t => new TaxBracket(t.Limit, t.CoeffR, t.CoeffN))
.ToArray();
}
catch (DbException e)
{
// DBMS 错误:我们把它包装在 TaxException 中
throw new TaxException("Error while reading the tax brackets from the database", e)
{
Code = (int)ErrorCodes.Access
};
}
// [business] 层至少需要一个档次
if (TaxBrackets.Length == 0)
{
throw new TaxException("The tax brackets table is empty") { Code = (int)ErrorCodes.EmptyTable };
}
}
}
|
- 第 11 行:此实现的错误代码,与[FileTax] 和 [JsonTax]相同;
- 第 17 行:[dao]层接收一个上下文工厂。它将是单例:它在构造函数中一次性读取全部档次,使用一个生命周期很短、随即释放的上下文(第 22 行);
- 第 24–28 行:读取表,不进行跟踪(档次不会被修改),按主键顺序。[Select]投影将每个持久化实体转换为 [Entities.TaxBracket]:应用程序的其余部分永远看不到[TaxBracketEntity]实体。EF Core 仅向 DBMS 请求这三个相关列;
- 第 30–35 行:DBMS 错误(数据库无法访问、表缺失等)表现为派生自[DbException]的异常,它是 ADO.NET 连接器异常的基类(第 10 章):对于 MySqlConnector 是[MySqlException] 。与其他实现一样,它被封装在[TaxException]中;
- 第 39–41 行:空表同样是错误:[business]层要求至少有一个档次。
11.13.3. 数据库
[eftaxes]数据库由[Initial] 迁移创建,该迁移由在[dotnet ef migrations add Initial]命令生成,命令在[Tax.Dao.Ef]项目文件夹中输入。该工具接受类库作为启动项目,因为它包含[TaxContextFactory]工厂和[Microsoft.EntityFrameworkCore.Design]包(否则,需要使用[--startup-project]选项指定一个可执行项目)。迁移如下:
| using Microsoft.EntityFrameworkCore.Metadata;
using Microsoft.EntityFrameworkCore.Migrations;
#nullable disable
#pragma warning disable CA1814 // 优先使用交错数组而不是多维数组
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");
}
}
}
|
- 第 19–31 行:创建表;
- 第 35–46 行:插入种子数据,每个档次一行;
- 第 6 行:生成的代码禁用了代码分析器关于多维数组([new object[,]])的警告。
SQL 迁移脚本显示了将要执行的命令:
| > 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;
|
如果表[__EFMigrationsHistory] 不存在则创建它(第 4–8 行),然后在事务中应用迁移。应用迁移:
| > 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.
|
并检查表的内容:
| > 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 |
+----+----------+--------+---------+
|
薪资档次都在,最后一个档次的上限为零([business]层不使用它,当没有其他档次合适时,该层会选择最后一个档次)。
要在您自己的机器上建立数据库:[Initial] 迁移已经包含在课程代码的[11-efcore/TaxV7/Tax.Dao.Ef/Migrations]文件夹中。因此,您无需再次输入[dotnet ef migrations add Initial]命令(它用于生成迁移,所以这一步已经完成)。只需:
- 运行 MySQL(在 Laragon 中;参见附录;用户[root] ,无密码);
- 如果尚未安装,请安装[dotnet-ef]工具:[dotnet tool install --global dotnet-ef --version 9.0.0];
- 进入[11-efcore/TaxV7/Tax.Dao.Ef]文件夹,输入这一条命令[dotnet ef database update]。
随后会创建[eftaxes]数据库,其[brackets]表中已填入种子数据。如果命令失败,请检查 MySQL 是否正在运行,以及[TaxContextFactory]工厂中的连接字符串是否与您的服务器相符(端口 3306,用户名[root],密码为空)。
11.13.4. 各层的集成
可执行项目[Tax.Ui.Ef] 由以下各层组成:
| <Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<!-- 第 5 版的 [business] 层和 [ui] 层,保持不变 -->
<ProjectReference Include="../../../06-architectures/TaxV5/Tax.Business/Tax.Business.csproj" />
<ProjectReference Include="../../../06-architectures/TaxV5/Tax.Ui/Tax.Ui.csproj" />
<!-- 新的 [dao] 层 -->
<ProjectReference Include="../Tax.Dao.Ef/Tax.Dao.Ef.csproj" />
</ItemGroup>
<ItemGroup>
<!-- 依赖注入容器和 JSON 配置 -->
<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.12" />
</ItemGroup>
<ItemGroup>
<!-- 配置文件被复制到可执行文件旁边 -->
<None Update="tax-ef*.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
</Project>
|
- 第 12–13 行:版本 5 的 [business] 和 [ui] 层 。[Tax.Ui]项目是一个可执行文件:可以将其作为库引用,以使用其[Ui.Dialog]类;
- 第 15 行:新的[dao]层;
- 第 26 行:配置文件。它们不命名为[appsettings.json]:被引用的项目[Tax.Ui] 已经把它自己的[appsettings*.json] 文件复制到输出文件夹,两个同名文件会冲突。
配置文件[tax-ef.json] 包含连接字符串:
| {
"ConnectionStrings": {
"Tax": "Server=localhost;Port=3306;Database=eftaxes;User=root;Password="
}
}
|
[ConnectionStrings] 节是 .NET 配置中存放连接字符串的常规位置:方法[config.GetConnectionString("Tax")] 读取键[ConnectionStrings:Tax]。文件[tax-ef-error.json] 指向一个名为[eftaxesmissing]的数据库,该数据库并不存在。
主程序沿用版本 5 的主程序,其中只有[dao]层的组装发生变化:
| using Dao;
using Entities;
using Business;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Ui;
// 配置文件:默认为 tax-ef.json,或作为参数传入的文件
string configFile = args.Length > 0 ? args[0] : "tax-ef.json";
// 层的集成
ITaxBusiness business;
try
{
// 读取可执行文件旁边的配置
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}");
// 在容器中注册各层
var services = new ServiceCollection();
// 为 MySQL 配置的 EF Core 上下文工厂
services.AddDbContextFactory<TaxContext>(options =>
options.UseMySql(connection, new MySqlServerVersion(new Version(8, 0, 36))));
// [dao] 层:EfTax 将接收该工厂
services.AddSingleton<ITaxDao, EfTax>();
// [business] 层:它将接收 [dao] 层
services.AddSingleton<ITaxBusiness, TaxBusiness>();
// 创建容器,然后创建 [business] 层(从而创建 [dao] 层)
ServiceProvider provider = services.BuildServiceProvider();
business = provider.GetRequiredService<ITaxBusiness>();
}
catch (Exception e)
{
// 显示错误并结束程序
Dialog.DisplayError(e);
return 1;
}
// 与用户的对话,使用第 5 版的对话
Dialog.Run(business);
return 0;
|
- 第 21–22 行:从配置中读取的连接字符串。位于[throw] (C# 7)表达式右侧的[??] 如果缺失则抛出异常;
- 第 27–28 行:上下文工厂[TaxContext],使用配置中的连接字符串进行配置;
- 第 30 行:[dao]层是一个 [EfTax]:容器会将上下文工厂传递给它。单例[dao]层不能直接接收上下文,因为上下文是“作用域”的——因此使用工厂;
- 第 32 行:版本 5 的[business]层;
- 第 46 行:版本 5 的对话框。
11.13.5. 执行
| > 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:
|
沿用以前版本的阈值:已婚、有两个孩子、合计收入 60,000 欧元的夫妇为 4,282 欧元,有三个孩子的家庭为 2,959 欧元,没有孩子的单身人士为 11,519 欧元。
使用配置文件[tax-ef-error.json],它指向一个不存在的数据库:
| > dotnet run -- tax-ef-error.json
Exception chain:
----------------------------------------
Entities.TaxException: Error while reading the tax brackets from the database
----------------------------------------
MySqlConnector.MySqlException: Unknown database 'eftaxesmissing'
----------------------------------------
|
- 第 6 行:原始异常,由 MySqlConnector 连接器通过 EF Core 抛出;
- 第 4 行:[dao]层将其封装在[TaxException]中,由主程序显示。
2008 年的课程在版本 7 中演示了,由于 ADO.NET 的通用连接器,[dao]层只需修改配置文件就可以切换 DBMS(从 MySQL 到 SQL Server Compact)。使用 EF Core 时,切换 DBMS 相当于切换提供程序:将 Pomelo 包替换为另一个 DBMS 的包(例如[Microsoft.EntityFrameworkCore.SqlServer]),将[UseMySql]调用替换为相应的调用([UseSqlServer]),然后重新生成迁移,因为迁移包含特定于提供程序的信息。以 LINQ 编写的[EfTax]类代码保持不变。
11.14. 结论:ADO.NET、Dapper 还是 EF Core?
现在我们有两种访问数据库的方式:ADO.NET(第 10 章)和 EF Core(本章)。还有第三种被广泛使用的折中方式:Dapper,一个小型库(“微型 ORM”),它为 ADO.NET 连接添加了扩展方法。这些方法执行手写的 SQL 查询,并自动将结果中的行转换为对象:[connection.Query<Article>("SELECT * FROM articles WHERE Price > @price", new { price = 200 })]。SQL 由您编写,Dapper 负责将列映射到属性。
| | 优势 | 劣势 |
ADO.NET | 完全控制 SQL;性能好;无依赖项 | 大量重复代码(参数、读取列);SQL 写在字符串中,编译器不检查 |
Dapper | SQL 手写,但无需编写拷贝代码;性能与 ADO.NET 相近 | 没有更改跟踪,也不生成[INSERT]/[UPDATE];没有迁移 |
EF Core | LINQ 查询由编译器验证;更改跟踪;关系;迁移;独立于 DBMS | 多了需要理解的一层;需要监控生成的 SQL;不太适合复杂的批量处理 |
可以提出以下指导原则:
- EF Core 适用于大多数管理类应用程序:由相互关联的实体构成的模型、读取和更新实体的操作,以及随应用程序演进的架构。它是 ASP.NET Core 应用程序的默认选择;
- ADO.NET或Dapper适用于希望精确控制所执行 SQL 的场合:复杂的报表查询、存储过程、处理海量数据,或者现有数据库的架构不适合面向对象模型;
- 这些方法可以结合使用:应用程序可以在大部分场合使用 EF Core,而对少数关键查询使用手写 SQL 代码——借助[FromSql]、[SqlQuery]或 Dapper。EF Core 还提供对其所使用的 ADO.NET 连接的访问([context.Database.GetDbConnection()])。
无论如何,了解 ORM 并不意味着不再需要理解 SQL 和 DBMS 的工作原理:本章中我们一直显示的已执行 SQL 命令日志,是验证 EF Core 实际行为的首要工具。
如需进一步了解,Microsoft 的文档非常全面:Entity Framework Core。Pomelo 提供程序的文档位于其仓库中:Pomelo.EntityFrameworkCore.MySql。