DB First 开发教程

以下教程演示了从数据库创建实体的方法。 有关使用代码优先方法的教程，请参阅 Code First 开发教程。

创建 Web API 演示

本教程将向您展示如何从现有数据库生成实体、使用可视化设计器配置实体以及生成后端 Web API。

在这个demo中，可以生成并调用后端Web API来提供以下功能：

  • 添加、编辑、删除、查看部门
  • 添加、编辑、删除、查看员工
  • 查找员工

本教程将开发过程分成以下阶段：

第 1 阶段：从现有数据库创建实体

第 2 阶段：生成基本 Web API（用于添加/获取/编辑/删除部门和员工）

第 3 阶段：设计过滤器并生成过滤器 Web API（用于过滤员工）

第 4 阶段：从设计项目生成 C# 项目

第 5 阶段：运行并测试 Web API

第 6 阶段：修改数据库连接（可选）

第 1 阶段：从现有数据库创建实体

您可以从现有数据库（SQLite、SQL Server、MySQL、Oracle 和 PostgreSQL）创建实体。 数据库架构将自动导入到实体中。

您可以使用以下任一方法从数据库表/视图创建实体：

  • 右键单击设计项目，选择 添加 > 新建项，然后选择 实体设计（基于数据库） 项目。

  • 右键单击设计项目，选择 添加 > 从数据库新增。

步骤1：选择 Web API 创建一个设计器项目。

  1. 在 SnapDevelop 中，选择 文件 > 新建 > 新建项目，选择 设计器开发 选项卡，然后选择 Web API 并单击 下一步。

    image-20231214154227980

  2. 使用默认设置并单击 创建。

    image-20231214154245559

    该项目显示在解决方案资源管理器中。

    该项目包含一个实体设计文件 WeatherForecast.sde，它具有基本配置。

    image-20240701134647061

步骤2：右键单击项目，选择 添加 > 从数据库新增。

image-20231214154456801

（或者选择 添加 > 新建项，然后在 添加新项 对话框中选择 实体设计（基于数据库）。）

步骤3：选择现有的数据库连接，或点击 新建 创建新的数据库连接。

image-20231214160156452

示例1：创建 SQLite 数据库连接

  1. 单击 新建。

  2. 从数据提供程序 列表中选择 SQLite，选择数据库文件，单击 测试连接 以确保连接成功，然后单击 确定。

    image-20231214154906695

  3. 从 连接 列表中选择 SQLite 数据库连接。

示例2：创建 SQL Server 数据库连接

  1. 单击 新建。

  2. 指定与 SQL Server 数据库连接的设置，单击 测试连接 以确保连接成功，然后单击 确定。

    image-20231214160035359

  3. 从 连接 列表中选择 SQL Server 数据库连接。

步骤4：选择一个或多个数据库表/视图来创建实体。 如果列表很长，您可以搜索表或视图的名称。

当您选择表或视图时，默认情况下会自动选择关联的字段和相应的表/视图。

例如，选择 Company 表将自动选择 Department 和 Employee 表。

您可以调整所选表和视图中的列和引用。

image-20231214160258943

  • 覆盖 -- 是否覆盖同名的实体文件。
  • 为每个架构创建目录 -- 是否使用数据库架构名称创建文件夹并将实体文件存储在该文件夹中。

步骤5：单击 创建。

将根据所选的数据库表/视图自动创建实体。

image-20240701135040515

您可以双击这些文件以在实体设计器中加载实体设置。

实体设计器 包含 4 个选项卡：字段设计、 过滤器设计、服务与 API 设计 以及 代码预览。 字段设计 选项卡包含字段的设置；过滤器设计 选项卡包含数据过滤器和条件的设置； 服务和 API 设计 选项卡指定要生成的服务和 API； 代码预览 选项卡允许您以不同模式（按类别或按目标）查看自动生成的 C# 代码。

例如，Department 实体包含以下字段：

image-20231214161047180

例如，Employee 实体包含以下字段：

image-20231214161111065

第 2 阶段：生成 Web API

现在我们可以为实体生成 Web API。 API 包括 Get、GetList、GetPage、Add、AddRange、Update、和 Delete，可以调用这些 API 来执行添加/获取/编辑/删除数据等 CRUD 操作。

步骤 1：打开 Department 实体 (Department.sde)。

步骤 2：选择 服务与 API 设计 选项卡，然后选择 生成所有 API，一次性为所有服务生成 API。

您还可以选择仅为某些服务生成 API（通过在每个服务后选择 生成 API 选项）。

image-20231214161259973

步骤 3：打开 Employee 实体 (Employee.sde)。

步骤 4：选择 服务与 API 设计 选项卡，然后选择 生成所有 API。

步骤 5：保存两个实体。

第 3 阶段：设计过滤器并生成过滤器 API

接下来我们将为实体生成过滤器 API。 可以调用过滤器 API 来搜索与输入条件匹配的数据。

步骤 1：打开 Employee 实体 (Employee.sde)。

步骤 2：选择 过滤器设计 选项卡，单击 添加过滤器 创建新过滤器。

（PrimaryKeyFilter 为默认生成的过滤器，用于按主键（也就是 ID）过滤员工）

步骤 3：指定过滤条件，如下图所示。

设计过滤器时，您可以在右侧面板底部预览过滤器语法。

image-20231214161603377

步骤 4：选择 服务与 API 设计 选项卡，添加过滤器 API：GetPageBySearchByDepartment（通过单击 添加服务 > 获取分页数据 > SearchByDepartment）。

image-20231214161725131

确保选择 生成 API 选项。

image-20231214161812039

步骤 5：保存实体。

第 4 阶段：生成 C# 项目

步骤 1：单击工具栏中的 生成项目 按钮或右键单击项目节点，然后选择 生成项目 > Profile 以打开默认的配置文件。

image-20231214161931281

您还可以选择 新建配置 创建一个新的配置文件，或者通过双击设计器项目中 生成配置 文件夹下的配置文件来修改现有配置文件。

image-20231214162221575

在 配置文件 向导的底部，选择数据库连接。 默认情况下，会在 [project].WebApi 项目的根文件夹中生成一个 SQLite 数据库（data.db）。

image-20231214162553536

推荐：数据库应与生成实体的数据库类型相同，因为实体可能包含一些特定于数据库类型的设置。

稍后当 Web API 运行时，将根据实体设置生成数据库表。 如果您对实体设置进行了更改，则需要指定一个空数据库而不是已存在的数据库，因为实体设置不会覆盖已有数据库表。

步骤 2：单击 Profile 窗口右上角的 生成项目 按钮。

image-20231214162635043

项目生成成功后，将被加载到解决方案中：

  • [project].Common：被合约层或认证服务层引用或依赖的开发工具包和扩展功能。
  • [project].Contracts：定义服务合约的合约层。
  • [project].Controllers：定义服务控制器的控制器层。
  • [project].Dal：数据访问层，例如 EF Core，其中包含与数据库相关的配置（存储库、工作单元、DbContext）和数据初始化（值比较器、值转换器）。
  • [project].Identity：认证服务层，内部授权用户注册和登录。 只有启用授权后才会生成该项目。
  • [project].Services：实现合约的服务层。
  • [project].WebApi：向用户发送数据的表示层。

image-20231214162800418

这些项目是标准 C# 项目，您可以在任何 C# 编辑器中打开和修改它们。

然而，不建议直接修改这些项目，因为每次执行生成项目时都会自动生成这些项目。 如果您直接对文件进行更改，则下次再次生成项目时，更改将被覆盖。

如果您想将自己的代码添加到生成的项目中，可以考虑以下选项：

  • 使用产品提供的 自定义代码 工具。

  • 创建一个新项目并将脚本放入新项目中，并在该新项目和自动生成的项目之间进行引用。

  • 在生成的项目中创建一个新的类文件，并将脚本放入新的类文件中。

第 5 阶段：运行 Web API

成功生成 C# 项目后，您可以运行并测试 Web API。

运行 [project].WebAPI 项目以启动 Web API 和 Swagger UI。

image-20231214162947182

当 Web API 成功运行后，您将能够看到 Swagger UI 并在 Swagger UI 上测试基本 API 和过滤器 API。

image-20231214163114103

image-20231214163153142

第 6 阶段：修改数据库连接

如果您对实体设置进行了更改，则需要此阶段。

如果修改了实体中的以下字段设置，则需要生成新数据库或更新（手动迁移）现有数据库，以使表架构与实体保持同步，否则实体中的更改可能会发生变化，与现有表架构冲突，会导致数据操作失败。

  • 字段名称
  • 字段类型
  • 集合
  • 可空
  • 主键
  • 列名称
  • 列类型
  • 设置并发检查
  • 索引
  • 索引 > 唯一

要手动迁移现有数据库，请参阅 实体更改后更新数据库。

要生成新的数据库，您可以在 生成项目 向导中配置新的数据库连接并再次生成项目，或者直接更改 [project].WebApi 项目中的 appsettings.json 文件中的 DataContext 设置 。 以 SQL Server 为例。 您可以将 Initial Catalog 设置为新的空数据库或不存在的数据库，然后再次运行 [project].WebApi 项目。

"DataContext": "Data Source=172.25.13.3,1434;Initial Catalog=EmployeeInfo_new;User ID=sa;Password=<pwd>;Trust Server Certificate=True"

注意：如果要生成新数据库，建议新数据库应与旧数据库的数据库类型相同，因为当您从数据库创建实体时，实体设置可能包含针对数据库类型的具体设置。

管理和更新数据库连接

选择数据库连接（通过生成项目向导）

当您从设计项目生成标准 C# 项目时，您可以在 生成项目 向导中选择数据库连接，以便在 C# 项目运行时从实体生成数据库。

步骤1：右键单击设计项目并选择 生成项目 > 新建生成配置文件。

步骤2：转到 配置文件 向导的底部，选择现有的数据库连接，然后单击编辑图标修改数据库配置。 或者选择 添加连接 来创建新的数据库连接。

默认情况下，将在 [project].WebApi 的根文件夹中创建本地 SQLite 数据库（data.db）。

image-20231214162553536

步骤3：保存配置文件，然后单击 生成项目。

数据库提供程序将自动从 NuGet 网站下载到 [project].Dal 项目。

数据库的连接字符串将存储在 [project].WebApi 项目中的 appsettings.json 文件中。

选择 SQLite 数据库连接时，连接字符串如下所示：

image-20231214163312279

选择 SQL Server 数据库连接时，连接字符串如下所示：

注意：如果指定现有的 SQL Server 数据库，请确保该数据库没有表架构，否则实体设置将不会覆盖数据库中的现有表。 在这种情况下，您可以将 Initial Catalog 设置为不存在的数据库；然后数据库将使用实体设置自动创建。

设置不同的数据库连接（通过配置文件）

从设计项目生成的项目是标准 C# 项目，因此您也可以在项目配置文件中修改数据库连接，就像在任何其他 C# 项目中一样。

更多详细信息即将推出。

实体更改后更新数据库

创建实体（从现有数据库或从头开始）后，您可能会经常更改实体设置； 并且每次实体发生变化时，您可以选择创建一个新的数据库（相同类型），以便新的数据库和表架构将与实体设置同步； 或者，如果您不想丢失数据，可以选择继续使用现有数据库。 要继续使用现有数据库，您需要根据实体更改手动更新数据库架构。

本节为您提供在实体更改时更新数据库的可能选项。

选项#1：删除并重新创建数据库（用于开发环境）

当你处于开发阶段时，如果你认为保留现有的数据库表没有价值，你可能会完全删除数据库或表。 然后，当您再次运行该项目时，将创建新的数据库或表。

  • 使用 SQLite，这很容易。 您可以直接删除 [project].WebApi 项目中的 data.db 文件来彻底删除整个数据库。

  • 对于其他数据库，您可以执行 DROP DATABASE 语句来删除整个数据库或使用 DROP TABLE 语句来删除表：

    DROP DATABASE database_name;

    DROP TABLE table_name;

  • 或者，您可以在 [project].Dal 中添加脚本，以在运行 Web API 时删除现有表并重新创建新表。 使用这种方法，您必须记住在实体设计稳定且不会进行进一步更改后注释掉脚本。

    在 [project].Dal > DalExtensions.cs 中，在 TryMigrateDatabase 方法中找到以下脚本：

    context.Database.EnsureCreated();

    将其更改为

    try
      {
        context.Database.EnsureDeleted();
       }
catch
       {
   		//
        }
context.Database.EnsureCreated();

选项 #2：迁移现有数据库（适用于生产环境）

当您的项目/应用程序在生产环境中运行时，您可能希望始终使用现有数据库，而不是每次实体更改时都使用新数据库。 在这种情况下，您可以考虑使用 EF Core 迁移功能来更新现有数据库架构，而不是创建新数据库。

EF Core 文档 中提供了完整的方法。 下面重点介绍所需的主要步骤。

步骤 1：安装 EF Core 命令行界面工具。

步骤 2：在 [project].Dal 项目中安装 Microsoft.EntityFrameWorkCore.Design 包。 请注意，版本应与 EF Core 相应的数据库提供程序相同。

步骤 3：将迁移程序集更改为 [project].WebApi。

步骤 4：打开命令提示符并切换到 [project].WebApi 的根文件夹，然后执行迁移的相应注释。

例如，您可以执行此命令来添加新的迁移。

dotnet ef migrations add initsample001

执行此命令将数据库更新到指定的迁移。

dotnet ef database update

完整的命令列表，请参考 https://entityframeworktutorial.net/efcore/cli-commands-for-ef-core-migration.aspx。