張高興的 Entity Framework Core 即學即用：（一）創建第一個 EF Core 應用
- 2022 年 3 月 22 日
- 筆記
- .NET, c#, entity framework, 張高興的 Entity Framework Core 即學即用
寫在前面
Entity Framework Core (EF Core) 是 .NET 平台流行的對象關係映射（ORM）框架。雖然 .NET 平台中 ORM 框架有很多，比如 Dapper、NHibernate、PetaPoco 等，並且 EF Core 的性能也不是最優的（這是由於 EF 的實體跟蹤特性，將其禁用後可以大幅提升性能），但依然吸引到很多後端開發者的使用，原因如下：
- EF Core 由 .NET 官方進行開發維護，出現問題解決較為及時，這是很多國產 ORM 框架不具有的優勢；
- EF Core 和 C# 語法高度綁定，使用 LINQ 不再需要編寫複雜的資料庫訪問程式碼；
- EF Core 支援大部分流行的資料庫，切換資料庫時只需要更改資料庫訪問驅動，並不需要更改業務邏輯。
因此在項目中使用 EF Core 不一定是最優的，但一定不會錯。
《張高興的 Entity Framework Core 即學即用》系列部落格將會從實踐的角度去介紹 EF Core。由於學習的是資料庫訪問技術，因此還需要一個資料庫供我們實踐。將根據如下背景設計一個資料庫，本系列部落格將基於此資料庫進行實踐：
新冠肺炎的流行打破了人們原有的正常生活。為了更好地預防和控制疫情，我們決定開發一個病毒檢測管理系統，用於記錄公民的核酸檢測報告。核酸檢測在醫院進行，所有檢測報告將由病毒檢測管理系統收集統計。當前有多家醫院可以進行核酸檢測，未來這些醫院的數量也會增加。考慮到病毒的變異以及未來的擴展性，病毒檢測管理系統還需要支援存儲不同病毒的檢測報告。核酸檢測的流程由收集患者的基本資訊開始，然後是收集樣本的類型，最後出具帶有醫生姓名的核酸檢測報告。
《張高興的 Entity Framework Core 即學即用》系列部落格使用 .NET 6 和 EF Core 6 進行編碼，保證了技術的時效性。和絕大部分 EF Core 的教程不同，這裡並沒有選擇使用 SQL Server，而是使用 PostgreSQL 資料庫。此處並沒有否認 SQL Server 是一款優秀的資料庫，並且 EF 的很多特性在 SQL Server 上表現更好，可以說 SQL Server 是 EF Core 的最佳實踐。但 SQL Server 最致命的問題是閉源並且收費，現在雖然可以跨平台運行，但這個方向仍有很長的路要走。PostgreSQL 開源且免費，甚至可以運行在 ARM 的 Linux 開發板上，性能也要優於 MySQL。PostgreSQL 擴展性高，擁有龐大的插件群，並且還具有一些「領先時代」的功能，可以說是資料庫界的 C#。當然本系列部落格並沒有涉及到資料庫的原生操作，如果你不想使用 PostgreSQL，可以直接將 NuGet 包替換成對應資料庫的即可，這也是 EF Core 的優勢。
《張高興的 Entity Framework Core 即學即用》系列部落格共分為 4 個部分：
- 第一部分將從 0 開始創建一個 EF Core 應用，介紹了使用 Database First 的方式以及手工的方式生成實體類，並且嘗試查詢一張表的數據；
- 第二部分介紹了 EF Core 的實體狀態以及增刪改查等資料庫操作；
- 第三部分實現了一個 EF Core 的幫助類，以簡化資料庫的操作和增強擴展性；
- 第四部分使用 Razor 引擎實現了一個實體類生成工具。
每一篇部落格在介紹功能點時都附帶有簡單的示例，每一章的最後還附有若干個小練習，希望讀者可以借著練習幫助理解，之後根據項目中遇到的問題再學習其他的內容。歡迎批評與指正，有任何的問題都可以通過郵件或者評論的方式與我交流。
張高興
2022年3月22日
本文將使用 .NET 6 創建一個控制台程式，從 0 開始，學習 EF Core 的使用。通過本文你可以學到：
- 使用 Database First 的方式生成實體類；
- 熟悉實體類中的 EF Core Attribute；
- 查詢一張表的數據；
- 使用
Docker拉取鏡像。
準備工作
準備工作包含兩部分：安裝資料庫與創建資料庫。EF Core 對 PostgreSQL 的版本沒有要求，但後續的部落格在介紹編寫實體類生成工具時要求 12 及以上的版本。
安裝 PostgreSQL
直接安裝
PostgreSQL 支援在絕大多數作業系統下運行，下載地址：//www.postgresql.org/download
Windows 下載 exe 安裝包，安裝時直接點擊「下一步」即可，無需額外配置。如果使用 Debian 系列的 Linux 發行版時，直接使用 apt 進行安裝，也無需其他操作。其他的作業系統建議根據下載地址中的安裝指南進行操作。
使用 Docker 拉取鏡像
- 拉取 PostgreSQL 鏡像：
docker pull postgres
- 創建卷，用於持久化資料庫數據：
docker volume create pgsql_data
- 運行鏡像，埠映射為
54321，密碼配置為弱密碼@Passw0rd：
docker run -d --name pgsql -p 54321:5432 --restart=always -e POSTGRES_PASSWORD='@Passw0rd' -e TZ='Asia/Shanghai' -e ALLOW_IP_RANGE=0.0.0.0/0 -v pgsql_data:/var/lib/postgresql postgres
資料庫的表結構
資料庫的設計取決於業務的需求，對同樣的業務，每個人的設計都有可能不同，資料庫的設計並沒有標準答案，讀者們或許有更好的設計方案，這裡給出的表結構僅供參考，只是為了滿足教程的需要：
🛈 重要
下面使用熟悉的資料庫管理工具，如 pgAdmin、Navicat 等，創建資料庫 pandemic，具體的執行 SQL 如下，刪減了欄位注釋等不必要的語句：
create table doctor (
id SERIAL not null,
name VARCHAR(20) not null,
hospital_id INT4 not null,
is_deleted INT4 not null default 0,
creator_id VARCHAR(50) null,
created_dt TIMESTAMP not null default 'now()',
modifier_id VARCHAR(50) null,
modified_dt TIMESTAMP not null default 'now()',
constraint PK_DOCTOR primary key (id)
);
create table hospital (
id SERIAL not null,
name VARCHAR(20) not null,
is_deleted INT4 not null default 0,
creator_id VARCHAR(50) null,
created_dt TIMESTAMP not null default 'now()',
modifier_id VARCHAR(50) null,
modified_dt TIMESTAMP not null default 'now()',
constraint PK_HOSPITAL primary key (id)
);
create table patient (
id SERIAL not null,
name VARCHAR(20) not null,
sex VARCHAR(10) null,
age INT2 null,
mobile VARCHAR(15) null,
is_deleted INT4 not null default 0,
creator_id VARCHAR(50) null,
created_dt TIMESTAMP not null default 'now()',
modifier_id VARCHAR(50) null,
modified_dt TIMESTAMP not null default 'now()',
constraint PK_PATIENT primary key (id)
);
create table report (
id SERIAL not null,
report_type_cd VARCHAR(20) not null,
doctor_id INT4 not null,
patient_id INT4 not null,
result BOOL not null default FALSE,
collect_time TIMESTAMP null,
test_time TIMESTAMP null,
report_time TIMESTAMP null,
description VARCHAR(200) null,
is_deleted INT4 not null default 0,
creator_id VARCHAR(50) null,
created_dt TIMESTAMP not null default 'now()',
modifier_id VARCHAR(50) null,
modified_dt TIMESTAMP not null default 'now()',
constraint PK_REPORT primary key (id)
);
create table report_type (
cd VARCHAR(20) not null,
name VARCHAR(20) null,
description VARCHAR(200) null default 'covid',
is_deleted INT4 not null default 0,
creator_id VARCHAR(50) null,
created_dt TIMESTAMP not null default 'now()',
modifier_id VARCHAR(50) null,
modified_dt TIMESTAMP not null default 'now()',
constraint PK_REPORT_TYPE primary key (cd)
);
alter table doctor
add constraint FK_DOCTOR_REFERENCE_HOSPITAL foreign key (hospital_id)
references hospital (id)
on delete restrict on update restrict;
alter table report
add constraint FK_REPORT_REFERENCE_DOCTOR foreign key (doctor_id)
references doctor (id)
on delete restrict on update restrict;
alter table report
add constraint FK_REPORT_REFERENCE_REPORT_T foreign key (report_type_cd)
references report_type (cd)
on delete restrict on update restrict;
alter table report
add constraint FK_REPORT_REFERENCE_PATIENT foreign key (patient_id)
references patient (id)
on delete restrict on update restrict;
INSERT INTO report_type (cd, name) VALUES ('COVID-1', '新冠肺炎1號');
INSERT INTO report_type (cd, name) VALUES ('COVID-2', '新冠肺炎2號');
INSERT INTO report_type (cd, name) VALUES ('COVID-3', '新冠肺炎3號');
INSERT INTO report_type (cd, name) VALUES ('COVID-4', '新冠肺炎4號');
INSERT INTO report_type (cd, name) VALUES ('COVID-5', '新冠肺炎5號');
Code First 與 Database First
Code First 和 Database First 算是 EF 中比較有特色的功能。簡單來說 Code First 是先編寫 C# 實體類，EF 會根據實體類之間的關係創建資料庫；Database First 是先設計和創建資料庫，EF 根據資料庫的表結構生成 C# 實體類。對於不熟悉資料庫的開發者來說，Code First 似乎非常方便，不需要掌握資料庫的知識也可以使用資料庫進行開發。Code First 是被應用於領域驅動設計（Domain Driven Design）中的，由於作者並沒有 DDD 的實踐，因此無法評判 Code First 的實用性。實際上資料庫設計有很多優秀的軟體，如 PowerDesigner、Navicat Data Modeler 等，並不需要手動的編寫創建資料庫的 SQL，因此 Database First 是一種非常高效的方式。而 Code First 中手動編寫實體類這一步是不可避免的，在大型項目中數十上百的實體類，這些工作量是不容小覷的。因此本文不會介紹 Code First 的有關操作。
創建一個 EF Core 應用
項目地址：//github.com/ZhangGaoxing/ef-core-demo
項目結構
創建一個控制台應用和類庫，項目結構如下：
Pandemic 為控制台應用，用於實踐 EF Core 的有關操作；Pandemic.Models 為類庫，用於提供資料庫上下文和實體類。
項目依賴
Pandemic 需要引用項目 Pandemic.Models：
<ItemGroup>
<ProjectReference Include="..\Pandemic.Models\Pandemic.Models.csproj" />
</ItemGroup>
Pandemic.Models 添加如下 NuGet 包引用：
<ItemGroup>
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="6.0.3" />
</ItemGroup>
使用 Scaffold-DbContext 命令生成實體類
接下來使用 Database First 的方式去生成實體類。Scaffold-DbContext 顧名思義譯為「資料庫上下文腳手架」，通過此命令生成實體類和資料庫上下文。由於新版本的 .NET 已經不再集成 EF Core Tools 了，因此需要在項目中添加 NuGet 包 Microsoft.EntityFrameworkCore.Tools。下面切換到 Pandemic.Models，即提供實體類的項目中安裝 NuGet 包 Microsoft.EntityFrameworkCore.Tools。安裝完成後，打開 Visual Studio 中的 工具 – NuGet 包管理器 – 程式包管理器控制台 執行以下命令：
- 切換到項目
Pandemic.Models：PM> cd .\Pandemic.Models - 運行實體類生成命令
Scaffold-DbContext，該命令的詳細參數請參考 //docs.microsoft.com/zh-cn/ef/core/cli/powershell#scaffold-dbcontext ：Scaffold-DbContext -Connection "Server=127.0.0.1;Port=54321;Database=pandemic;User Id=postgres;Password=@Passw0rd;" -Provider Npgsql.EntityFrameworkCore.PostgreSQL -Context PandemicContext
提示
正常運行沒有報錯後，實體類與資料庫上下文就生成完畢了。
之後打開資料庫上下文 PandemicContext.cs，會發現其中還是有些許的問題，比如創建時間欄位 created_dt 的默認值為 PostgreSQL 中的 now() 函數，但 EF 並沒有將其識別出來：
還需要手動的進行一些調整：
由此可見 Database First 的最佳實踐應該使用 SQL Server，這種錯誤只能希望微軟在下一個版本儘快解決。
手動創建實體類
下面將手動編寫兩個實體類 Hospital.cs 和 Doctor.cs，以熟悉 EF Core Attribute 是如何將資料庫表和實體類之間建立聯繫的。
實體屬性
每一個實體類都有一組屬性，EF Core 會將實體屬性映射到資料庫表中的列。
表的映射
對資料庫表進行映射，使用 Table() Attribute。
[Table("hospital")]
public class Hospital { }
列的映射
對資料庫表中的列進行映射，使用 Column() Attribute。
[Table("hospital")]
public class Hospital
{
[Column("id")]
public int Id { get; set; }
}
主鍵的映射
對資料庫表中的主鍵進行映射，使用 Key() Attribute。當主鍵是自增鍵時，還需要設置 DatabaseGenerated() Attribute。
[Table("hospital")]
public class Hospital
{
[Key]
[DatabaseGenerated(DatabaseGeneratedOption.Identity)]
[Column("id")]
public int Id { get; set; }
}
使用上文介紹的 Attribute 完整的映射醫院類 Hospital.cs 以及醫生類 Doctor.cs：
[Table("hospital")]
public class Hospital
{
[Key]
[DatabaseGenerated(DatabaseGeneratedOption.Identity)]
[Column("id")]
public int Id { get; set; }
[Column("name")]
public string Name { get; set; }
[Column("is_deleted")]
public int IsDeleted { get; set; } = 0;
[Column("creator_id")]
public string CreatorId { get; set; }
[Column("created_dt")]
public DateTime CreatedDt { get; set; } = DateTime.Now;
[Column("modifier_id")]
public string ModifierId { get; set; }
[Column("modified_dt")]
public DateTime ModifiedDt { get; set; } = DateTime.Now;
}
[Table("doctor")]
public class Doctor
{
[Key]
[DatabaseGenerated(DatabaseGeneratedOption.Identity)]
[Column("id")]
public int Id { get; set; }
[Column("name")]
public string Name { get; set; }
[Column("hospital_id")]
public int HospitalId { get; set; }
[Column("is_deleted")]
public int IsDeleted { get; set; } = 0;
[Column("creator_id")]
public string CreatorId { get; set; }
[Column("created_dt")]
public DateTime CreatedDt { get; set; } = DateTime.Now;
[Column("modifier_id")]
public string ModifierId { get; set; }
[Column("modified_dt")]
public DateTime ModifiedDt { get; set; } = DateTime.Now;
}
導航屬性
導航（Navigation）屬性是資料庫表之間的關係在實體類中的體現。設置好實體類之間的導航屬性後，可以通過導航屬性輕鬆的查詢到關聯實體的數據。在設置導航屬性之前，首先需要理清楚醫院和醫生存在著怎樣的數量關係，醫生是醫院的附屬，一家醫院下面會有多名醫生，因此醫院和醫生之間是一對多的關係。為了方便理解，下面只保留主鍵、外鍵和導航屬性。
[Table("doctor")]
public class Doctor
{
[Key]
[DatabaseGenerated(DatabaseGeneratedOption.Identity)]
[Column("id")]
public int Id { get; set; }
[Column("hospital_id")]
public int HospitalId { get; set; }
[ForeignKey("HospitalId")]
public virtual Hospital Hospital { get; set; }
}
[Table("hospital")]
public class Hospital
{
[Key]
[DatabaseGenerated(DatabaseGeneratedOption.Identity)]
[Column("id")]
public int Id { get; set; }
public virtual List<Doctor> Doctors { get; set; }
}
資料庫表之間通過外鍵建立數量關係，因此配置導航屬性使用 ForeignKey() Attribute。
提示
創建資料庫上下文
資料庫上下文（DbContext）是 EF 不可或缺的一部分。DbContext 的實例表示程式與資料庫的一個會話（session），通過 DbContext 實例對資料庫中的數據進行修改和查詢。
為了在程式中訪問資料庫 pandemic，使資料庫表與創建的 C# 實體類建立映射，需要創建一個資料庫上下文類 PandemicContext.cs，該類派生自 Microsoft.EntityFrameworkCore.DbContext。
public class PandemicContext : DbContext
{
public PandemicContext() { }
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { }
protected override void OnModelCreating(ModelBuilder modelBuilder) { }
}
OnConfiguring() 方法用於配置資料庫的一些設置，比如連接字元串、日誌等：
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
optionsBuilder.UseNpgsql("Server=127.0.0.1;Port=54321;Database=pandemic;User Id=postgres;Password=@Passw0rd;");
}
警告
OnModelCreating() 方法用於配置資料庫表與實體類之間的映射。由於資料庫表中配置了軟刪除標記 is_deleted，當 is_deleted = 1 時認為該條數據是刪除的，因此還需要對獲取的數據進行過濾，使用 HasQueryFilter() 方法：
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.Entity<Hospital>()
.HasQueryFilter(x => x.IsDeleted == 0);
modelBuilder.Entity<Doctor>()
.HasQueryFilter(x => x.IsDeleted == 0);
modelBuilder.Entity<Report>()
.HasQueryFilter(x => x.IsDeleted == 0);
modelBuilder.Entity<ReportType>()
.HasQueryFilter(x => x.IsDeleted == 0);
modelBuilder.Entity<Patient>()
.HasQueryFilter(x => x.IsDeleted == 0);
}
資料庫上下文中通常還包括每個實體類的 DbSet<TEntity> 屬性。DbSet<TEntity> 是用於修改和查詢實體的數據，對 DbSet<TEntity> 的 LINQ 查詢會轉換為對應資料庫表的查詢。最終的資料庫上下文類 PandemicContext.cs 如下所示：
public class PandemicContext : DbContext
{
public DbSet<Hospital> Hospitals { get; set; }
public DbSet<Doctor> Doctors { get; set; }
public DbSet<Report> Reports { get; set; }
public DbSet<ReportType> ReportTypes { get; set; }
public DbSet<Patient> Patients { get; set; }
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
optionsBuilder.UseNpgsql("Server=127.0.0.1;Port=54321;Database=pandemic;User Id=postgres;Password=@Passw0rd;");
}
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.Entity<Hospital>()
.HasQueryFilter(x => x.IsDeleted == 0);
modelBuilder.Entity<Doctor>()
.HasQueryFilter(x => x.IsDeleted == 0);
modelBuilder.Entity<Report>()
.HasQueryFilter(x => x.IsDeleted == 0);
modelBuilder.Entity<ReportType>()
.HasQueryFilter(x => x.IsDeleted == 0);
modelBuilder.Entity<Patient>()
.HasQueryFilter(x => x.IsDeleted == 0);
}
}
提示
從資料庫中查詢
將實體類配置完關係以及創建資料庫上下文後，就可以通過實例化資料庫上下文對資料庫進行操作。下面切換到 Pandemic 控制台應用查詢 report_type 這張表中的數據：
using Pandemic.Models;
PandemicContext context = new PandemicContext();
var types = context.ReportTypes.ToList();
練習
