張高興的 Entity Framework Core 即學即用:(一)建立第一個 EF Core 應用

張高興發表於2022-03-22

寫在前面

Entity Framework Core (EF Core) 是 .NET 平臺流行的物件關係對映(ORM)框架。雖然 .NET 平臺中 ORM 框架有很多,比如 Dapper、NHibernate、PetaPoco 等,並且 EF Core 的效能也不是最優的(這是由於 EF 的實體跟蹤特性,將其禁用後可以大幅提升效能),但依然吸引到很多後端開發者的使用,原因如下:

  1. EF Core 由 .NET 官方進行開發維護,出現問題解決較為及時,這是很多國產 ORM 框架不具有的優勢;
  2. EF Core 和 C# 語法高度繫結,使用 LINQ 不再需要編寫複雜的資料庫訪問程式碼;
  3. 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 個部分:

  1. 第一部分將從 0 開始建立一個 EF Core 應用,介紹了使用 Database First 的方式以及手工的方式生成實體類,並且嘗試查詢一張表的資料;
  2. 第二部分介紹了 EF Core 的實體狀態以及增刪改查等資料庫操作;
  3. 第三部分實現了一個 EF Core 的幫助類,以簡化資料庫的操作和增強擴充套件性;
  4. 第四部分使用 Razor 引擎實現了一個實體類生成工具。

每一篇部落格在介紹功能點時都附帶有簡單的示例,每一章的最後還附有若干個小練習,希望讀者可以藉著練習幫助理解,之後根據專案中遇到的問題再學習其他的內容。歡迎批評與指正,有任何的問題都可以通過郵件或者評論的方式與我交流。

張高興
2022年3月22日


本文將使用 .NET 6 建立一個控制檯程式,從 0 開始,學習 EF Core 的使用。通過本文你可以學到:

  1. 使用 Database First 的方式生成實體類;
  2. 熟悉實體類中的 EF Core Attribute;
  3. 查詢一張表的資料;
  4. 使用 Docker 拉取映象。

準備工作

準備工作包含兩部分:安裝資料庫與建立資料庫。EF Core 對 PostgreSQL 的版本沒有要求,但後續的部落格在介紹編寫實體類生成工具時要求 12 及以上的版本。

安裝 PostgreSQL

直接安裝

PostgreSQL 支援在絕大多數作業系統下執行,下載地址:https://www.postgresql.org/download

Windows 下載 exe 安裝包,安裝時直接點選“下一步”即可,無需額外配置。如果使用 Debian 系列的 Linux 發行版時,直接使用 apt 進行安裝,也無需其他操作。其他的作業系統建議根據下載地址中的安裝指南進行操作。

使用 Docker 拉取映象

  1. 拉取 PostgreSQL 映象:
docker pull postgres
  1. 建立卷,用於持久化資料庫資料:
docker volume create pgsql_data
  1. 執行映象,埠對映為 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

資料庫的表結構

資料庫的設計取決於業務的需求,對同樣的業務,每個人的設計都有可能不同,資料庫的設計並沒有標準答案,讀者們或許有更好的設計方案,這裡給出的表結構僅供參考,只是為了滿足教程的需要:

? 重要

表結構這裡不過多的講解,雖然使用 EF Core 並不需要掌握複雜的資料庫知識,也不需要會寫複雜的 SQL,但必要的表結構關係還是應該要理解。

下面使用熟悉的資料庫管理工具,如 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 應用

專案地址:https://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 包管理器 - 程式包管理器控制檯 執行以下命令:

  1. 切換到專案 Pandemic.Models
    PM> cd .\Pandemic.Models
    
  2. 執行實體類生成命令 Scaffold-DbContext,該命令的詳細引數請參考 https://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
    

? 提示

執行 Scaffold-DbContext 命令報錯時,請將 Pandemic.Models 設為啟動專案,並且將“程式包管理器控制檯”中的“預設專案”也設定為 Pandemic.Models。

正常執行沒有報錯後,實體類與資料庫上下文就生成完畢了。

之後開啟資料庫上下文 PandemicContext.cs,會發現其中還是有些許的問題,比如建立時間欄位 created_dt 的預設值為 PostgreSQL 中的 now() 函式,但 EF 並沒有將其識別出來:

還需要手動的進行一些調整:

由此可見 Database First 的最佳實踐應該使用 SQL Server,這種錯誤只能希望微軟在下一個版本儘快解決。

手動建立實體類

下面將手動編寫兩個實體類 Hospital.csDoctor.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。

? 提示

導航屬性中的 virtual 關鍵字不是必須的,當使用懶載入(lazy loading)時才有意義。在任何時候都不建議使用懶載入,這會拖慢資料的查詢速度。

建立資料庫上下文

資料庫上下文(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;");
}

⚠️ 警告

不建議將密碼以明文的方式暴露在程式中,在 .NET 中字串並不是加密的,密碼可能會短暫的出現在記憶體中,或是對程式的反編譯都可能會造成密碼的洩露。最優的解決方案是不使用密碼進行身份驗證,或是通過讀取外部配置檔案,這樣也便於程式的維護。

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

? 提示

DbSet<TEntity> 屬性並不是必須的,只是為了簡化操作,在例項化資料庫上下文後,仍然可以使用 Set<TEntity>() 方法獲取實體類的 DbSet。

從資料庫中查詢

將實體類配置完關係以及建立資料庫上下文後,就可以通過例項化資料庫上下文對資料庫進行操作。下面切換到 Pandemic 控制檯應用查詢 report_type 這張表中的資料:

using Pandemic.Models;
PandemicContext context = new PandemicContext();
var types = context.ReportTypes.ToList();

✏️ 練習

1. 試著編寫剩下的實體類;
2. 比較一下 Database First 生成的實體類和資料庫上下文,與手工編寫的有何不同;
3. 不使用 DbSet<TEntity> 屬性查詢 report_type 表的資料。

相關文章