EF Core 的 Code First 模式

2022年5月13日08:08:35

0 前言

本文正文第一节,会对 Code First 进行基本的介绍,以及对相关名词进行说明,读者一开始可以不用在这里消耗过多时间,可以先操作一遍例子,再回过头理解。

第二节,以一个简单的例子,展示 EF Core 的 Code First 模式的操作流程。

第三节,将 Code First 的其他指令例举出来,以便于日后翻查。

第四节(未完成),将 Code First 其他一些操作,如:在迁移代码中添加 SQL 语句等。

第五节,将 Code First 模式常见的问题列举出来,防止踩坑。

1 相关介绍

1.1 Code First 模式

以 EF Core 模型为准,使用迁移的方式,将 EF Core 模型的变化以增量的方式更新到数据库。

简单理解:以C#代码定义的数据实体,生成数据库的表结构。

1.2 相关名词

数据库上下文(DbContext):继承自 DbContext,主要作用是连接数据库,跟踪数据实体状态(实体状态包括:added、modified、deleted 等),将数据库实体的状态写入数据库(持久化至数据库中)。

数据实体(Entity):C#的实体类,与数据库的表对应

数据模型(Model):暂且认为是数据库的表吧(因为官方文档的描述,感觉就像是)

约定(conventions):主要是数据实体的类名、属性。

数据注释(data annotations):应用于类上、属性的特性(如:[Table("SysUser")]),会被 Fluent API 的配置覆盖。

Fluent API:于自定义的 DbContext 中重写 OnModelCreating 方法中,对数据模型描述的配置,如:

 protected override void OnModelCreating(ModelBuilder modelBuilder)
 {
     builder.Entity<User>().ToTable("SysUser");
 }

数据实体(Entity)、数据模型(Model)、约定(conventions)、数据注释(data annotations)、Fluent API 说明:

数据实体(Entity)的类名、属性等,称之为约定(conventions),约定主要是为了定义数据模型(Model)的形状。

但是光靠约定可能不足以完整描述数据模型,有时我们的数据模型与我们的数据实体可能也有差异,这时,就可以通过数据注释(data annotations)和 Fluent API 补充。

2 EF Core 的基础使用

2.1 新建 WebApi 工程

这里基于 VS Code 工具,使用命令行创建一个 WebApi 程序:

mkdir CodeFirstTest & cd CodeFirstTest #新建文件夹DbFirstTest并切换至该目录下
dotnet new webapi --framework net6.0   #新建ASP.NET6.0 WebAPI程序

2.2 引入 EF Core 相关 Nuget 包

EF Core 部分 Nuget 包如下:

Microsoft.EntityFrameworkCore -->> 核心包
Microsoft.EntityFrameworkCore.Design -->> Design包:Code First 或 Db First 需要
Microsoft.EntityFrameworkCore.SqlServer -->> 微软官方 SQL Server 驱动
Pomelo.EntityFrameworkCore.MySql -->> 社区 MySql 驱动
MySql.EntityFrameworkCore -->> Oracle官方 MySql 驱动

其中核心包是必须的,另外还需配备对应数据库的驱动包,而 Design 包主要是在使用 Code First 或 Db First 需要的包。

这里,我们向工程引入必须的 Nuget 包,SQL 驱动程序选择 SQL Server 的:

dotnet add package Microsoft.EntityFrameworkCore --version 6.0.4
dotnet add package Microsoft.EntityFrameworkCore.Design --version 6.0.4
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 6.0.4
# dotnet add package Pomelo.EntityFrameworkCore.MySql --version 6.0.1

2.3 准备配置信息

在 appsettings.json 中增加一个节点,用于连接数据库时使用。

"ConnectionStrings": {
    "SqlServer": "server=localhost;database=efcore;uid=sa;pwd=Qwe123456;",
    "MySql": "server=localhost;port=3306;database=efcore;user=root;password=123456;charset=utf8mb4;"
}

2.4 新建数据库上下文 DbContext

新建一个自定义的数据库上下文 TestDbContext:

using Microsoft.EntityFrameworkCore;

namespace CodeFirstTest;

public class TestContext : DbContext
{
    public TestContext(DbContextOptions<TestContext> options) : base(options) { }

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        base.OnConfiguring(options);
    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        builder.Entity<User>();
        base.OnModelCreating(builder);
    }

    public virtual DbSet<User> User { get; set; }
}

2.5 创建数据实体

创建一个数据实体 User 如下:

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

namespace CodeFirstTest;

[Table("SysUser")]
public class User
{
    [Key]
    public Guid Id { get; set; } = new Guid();

    [StringLength(128)]
    [Comment("姓名")]
    public string? Name { get; set; }

    [StringLength(11)]
    [Comment("手机号码")]
    public string? Phone { get; set; }
}

[Table("SysUser")] 注释数据库中的表名为 SysUser。

[StringLength(128)] 注释字符串长度,[Comment("姓名")] 注释数据库中该字段含义。

这些注释,称为“数据注释”,主要是对数据模型的补充描述(可以简单认为:对数据库的表结构的补充描述)。

关于配置数据模型的详细内容,可以翻查EF Core官方文档:创建并配置模型

2.6 注册服务

在 Program.cs 中注册服务,并配置数据库连接串。

var configuration = builder.Configuration;
builder.Services.AddDbContext<TestContext>(options => {
    options.UseSqlServer(configuration["ConnectionStrings:SqlServer"]);
});

2.7 编译项目

在生成迁移之前,需要先对工程进行编译,否则会报错。

dotnet build

2.8 数据库迁移(Code First 模式)

如果没有安装 EF 工具,需要先安装

# 安装全局工具
dotnet tool install --global dotnet-ef
# 更新工具
dotnet tool update --global dotnet-ef

创建一个名为 Initial 的迁移,将会在项目根目录下生成一个 Migrations 的目录:

dotnet ef migrations add Initial

更新到数据库

dotnet ef database update

2.9 增加测试控制器

增加一个 UserController 用于测试。

using Microsoft.AspNetCore.Mvc;

namespace CodeFirstTest.Controllers;

[ApiController]
[Route("[controller]")]
public class UserController : ControllerBase
{
    private readonly TestContext _db;

    public UserController(TestContext db)
    {
        _db = db;
    }

    [HttpGet]
    public User? Get(Guid id)
    {
        return _db.User.Find(id);
    }

    [HttpPost]
    public void Post(User user)
    {
        _db.User.Add(user);
        _db.SaveChanges();
    }

    [HttpDelete]
    public bool Delete(Guid id)
    {
        User? user = _db.User.Find(id) ?? null;
        if (user == null) return false;
        _db.User.Remove(user);
        _db.SaveChanges();
        return true;
    }
}

2.10 运行项目

dotnet build
dotnet run

访问:https://localhost:7232/swagger/index.html

对接口进行操作,可以实现对 User 的增删查。

2.11 源码

Gitee:https://gitee.com/lisheng741/testnetcore/tree/master/EFCore/CodeFirstTest

Github:https://github.com/lisheng741/testnetcore/tree/master/EFCore/CodeFirstTest

3 数据库迁移

具体参考EF Core官方文档:管理数据库架构:迁移

3.1 安装工具

# 安装全局工具
dotnet tool install --global dotnet-ef

# 更新工具
dotnet tool update --global dotnet-ef

# 验证安装
dotnet ef

3.2 迁移

3.2.1 管理迁移

创建一个名为 Migrations 的目录,并生成一些文件

dotnet ef migrations add InitialCreate

创建迁移时指定迁移目录

dotnet ef migrations add InitialCreate --output-dir [directory]

删除迁移

dotnet ef migrations remove

列出所有迁移

dotnet ef migrations list

3.2.2 应用迁移

应用迁移主要有2种方式,一种是生成 SQL 脚本,一种是通过命令行工具执行命令进行迁移,具体请参考EF Core 官方文档:应用迁移

除了这两种迁移方式外,还有一种是在程序种迁移,即将迁移的代码写入程序中,由程序运行时触发。

1) 命令行工具

将迁移应用到数据库

dotnet ef database update

将迁移应用到数据库:指定迁移

dotnet ef database update AddNewTables

注意:使用该命令,也可以进行迁移回滚(回滚到之前的某个迁移)。

2) 生成 SQL 脚本
dotnet ef migrations script

指定迁移起点(From)

dotnet ef migrations script AddNewTables

指定迁移起点(From)和结束点(To)

dotnet ef migrations script AddNewTables AddAuditTable

幂等 SQL 脚本(idempotent):脚本将在内部检查已经应用哪些迁移(通过迁移历史记录表),并且只应用缺少的迁移。

dotnet ef migrations script --idempotent
3)在程序运行时进行迁移

请参考EF Core 文档:应用迁移:在运行时应用迁移

4 其他操作

4.1 迁移代码添加 SQL

请参考:EF Core 官方文档:管理迁移:添加原始 SQL

下面的例子,用一个新的FullName 属性替换现有的FirstNameLastName 属性,并将现存的数据转移到新的列上。

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customer",
    nullable: true);

migrationBuilder.Sql("UPDATE Customer SET FullName = FirstName + ' ' + LastName;");

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

4.2 自定义迁移操作

MigrationBuilder.Sql() 或 自定义 MigrationOperation 对象,可以对 MigrationBuilder 进行扩展。

如:想要在迁移代码中使用如下代码(CreateUser 方法为自定义方法)

migrationBuilder.CreateUser("SQLUser1", "Password");

4.2.1 使用 MigrationBuilder.Sql()

CreateUser 自定义代码如下:

public static OperationBuilder<SqlOperation> CreateUser(
    this MigrationBuilder migrationBuilder,
    string name,
    string password)
    => migrationBuilder.Sql($"CREATE USER {name} WITH PASSWORD '{password}';");

4.2.2 自定义 MigrationOperation 对象

请参考EF Core 官方文档:自定义操作

创建和删除 API(EnsureCreated 和 EnsureDeleted)

在程序运行中可以调用的 API,用于管理数据库的创建和删除。

5 Code First 模式常见问题

5.1 列重命名

具体请查看EF Core 官方文档:管理迁移:列重命名

官方举的例子:如果你将属性从Name 重命名为FullName,EF Core 将生成以下迁移:

migrationBuilder.DropColumn(
    name: "Name",
    table: "Customers");

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customers",
    nullable: true);

该迁移代码将Name 列删除,然后添加新的列FullName,这样做,会导致Name 列原有的数据丢失。

所以需要自行将该迁移代码修改如下:

migrationBuilder.RenameColumn(
    name: "Name",
    table: "Customers",
    newName: "FullName");

参考来源

EF Core 官方文档

EF Core / 基础_从建库到增删改查

EF Core的基本使用

  • 作者:芦荟柚子茶
  • 原文链接:https://www.cnblogs.com/clis/p/16197076.html
    更新时间:2022年5月13日08:08:35 ,共 6459 字。