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

寫在前面

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 表的數據。
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章