跳到主要内容

基础操作指南

创建实体​

您可以从零开始或从现有数据库表创建实体。

  • 要从零开始创建实体，您可以选择 实体设计（从零开始）。

    然后您可以创建一个或多个实体表。 每个实体表将被创建为一张数据库表。 字段设置将用于创建表架构。

  • 要从现有数据库表创建实体，您可以使用 实体设计（从数据库导入） 项。

    然后您可以修改实体表并创建新数据库或将更改迁移到现有数据库。

创建和设计实体时请注意以下事项：

  • 数据库是在您生成项目并运行 Web API 项目后创建的。 默认情况下，将在 [project].WebApi 项目下创建 SQLite 数据库（数据库文件 data.db）。

  • 数据库创建完成后，如果要对实体表进行更改（包括添加/删除/修改字段或删除实体表），可能会发生数据库冲突，数据操作可能失败。 您需要按照 实体表更改后更新数据库 中的说明手动删除或迁移数据库。

例如，要添加一个空白实体：

步骤 1：右键单击设计项目节点并选择 添加 > 新建项。 在 添加新项 对话框中，选择 实体设计（从零开始），指定实体名称，然后单击 创建。

步骤 2：在实体设计器中，从左边的组件库拖拽 空白表 组件到中间的设计视窗中。

步骤 3：在右边 实体（表） 选项卡中，单击 +添加 以添加并指定列设置。

步骤 4：您可以打开 演示应用 中的 database.sde 文件仔细查看这些设置。

image-20250401112205559

从实体生成数据库​

创建实体后，您可以从这些实体自动生成数据库。

步骤 1：在设计项目中创建实体后，右键单击设计项目节点并选择 生成项目。配置文件向导将打开。

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

您还可以在配置文件向导中创建或选择不同的数据库连接。

image-20250401112338427

步骤 2：选择现有数据库连接或选择 新建 创建新的数据库连接。

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

项目生成后会自动加载到解决方案中。

步骤 4：在 IDE 工具栏中，从项目列表中选择 [project].WebApi，然后单击 运行 来启动 Web API。

image-20231214142225712

Web API 成功启动后，会自动生成数据库文件。

例如，默认情况下会在 [project].WebApi 的根文件夹下自动生成一个 SQLite 数据库（data.db）。 有关更多信息，请参阅 管理和更新数据库连接。

image-20231214142259272

从数据库生成实体​

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

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

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

  • 右键单击设计项目，选择 添加 > 从数据库生成实体。

  • 在实体设计器中，从设计视窗的顶部选择 从数据库导入 工具选择数据表导入为实体。

步骤1：选择数据库连接。

如没有数据库连接，点击 新建 图标创建一个数据库连接。

image-20250313135837509

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

  1. 单击 新建。

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

    image-20231214154906695

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

  1. 单击 新建。

  2. 从数据提供程序 列表中选择 Microsoft SQL Server，指定与 SQL Server 数据库连接的信息，单击 测试连接 以确保连接成功，然后单击 确定。

    image-20231214160035359

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

当您选择表或视图时，默认情况下会自动选择与之关联的表并生成外键关系。如您不希望自动选择关联表，您可以清除 自动选择关联表 选项。

例如，选择 CustomerAddress 表将自动选择 Address 和 Customer 表，并自动生成外键。

image-20250313142940282

步骤3：单击 创建。

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

您可以双击文件以在实体设计器中加载实体设置。如下图所示：实体文件中包含了三张表。

image-20250313143924955

管理和更新数据库连接​

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

当您从设计项目生成标准 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。

添加或修改实体字段​

一旦数据库文件生成后（例如生成并运行 Web API），在现有实体中添加/删除/修改字段可能会导致数据库冲突（从而导致数据操作失败）。 在这种情况下，您需要按照 实体更改后更新数据库 中的说明手动删除或迁移数据库。

如果您修改实体中的以下字段设置，则需要手动删除或迁移数据库，以便将这些更改包含在数据库架构中。

  • 列名
  • 数据类型
  • 集合
  • 可空
  • 主键
  • 索引
  • 索引 > 唯一

创建外键约束​

请参阅 这个小节。

创建枚举​

请参阅 这个小节。

创建模型​

请参阅 这个小节。

生成序列或流水号​

请参阅 这个小节。

添加自定义代码​

请参阅 这个小节。

添加外部数据源​

请参阅 这个小节。

添加静态数据源​

请参阅 这个小节。

认证和授权​

请参阅 这个小节。

创建逻辑​

请参阅 这个小节。

设计过滤器​

请参阅 这个小节。

设计方法​

请参阅 这个小节。

创建视图​

请参阅 这个小节。

配置事件​

请参阅 这个小节。

生成项目​

请参阅 这个小节。

修改生成的项目​

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

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

  • 添加自定义代码。
  • 创建一个新项目并将脚本放入新项目中，并在该新项目和自动生成的项目之间进行引用。
  • 在生成的项目中创建一个新的类文件，并将脚本放入新的类文件中。