使用指南

实体

创建并设计一个实体

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

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

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

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

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

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

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

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

例如，要添加一个基类实体：

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

步骤 2：在实体设计器中，单击 添加字段 以添加并指定字段设置。

基类实体可以包含其他实体中的常用字段。

字段名称 字段类型 字段设置
ID Int32 主键：选中
InsertTime Compute 表达式：UtcNow()
数据类型：DateTime
插入时执行：选中
UpdateTime Compute 表达式：UtcNow()
数据类型：DateTime
插入时执行：选中
更新时执行：选中

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

image-20231214135958437

再例如，添加一个实体（并从基类实体继承字段）：

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

步骤 2：在实体设计器中，选择从基类实体继承，并选择 显示继承的字段 选项，以便基类实体中的字段以只读方式显示在字段列表中。

步骤 3：单击 添加字段 以添加并指定字段设置。

字段名称 字段类型 字段设置
DepartmentName String 必填：选中
Company Company 集合：选中
映射到：Company
SuperiorDepartment Department 可空：选中

步骤 4：在 服务与API设计 选项卡中，点击 添加基础服务 和 生成所有API，生成所有基础 API。

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

image-20231214140443743

从实体生成数据库

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

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

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

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

image-20231214142425835

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

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

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

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

image-20231214142225712

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

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

image-20231214142259272

从数据库生成实体

请参阅 这个小节。

添加或修改实体中的字段

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

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

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

添加搜索字段（使用过滤器设计器）

要将搜索字段添加到应用程序：

步骤 1：在设计器中打开实体文件（我们使用 WeatherForecast 模板，直接打开 WeatherForecast.sde 文件）。

步骤 2：选择 过滤器设计 选项卡，然后单击 添加过滤器，然后指定过滤器的选项。

假如您想添加一个搜索字段，允许用户输入日期并搜索输入日期的温度，那么您应该指定如下设置：

（Date 参数和 WeatherForecast.DateTime 字段必须按类型匹配。例如，如果将 Date 参数设置为 DateOnly，则 WeatherForecast.DateTime 字段也必须设置为 DateOnly。）

image-20231214144800117

步骤 3：选择 服务与 API 设计 选项卡，然后选择 添加服务 > 获取分页数据 > SearchByDate。

image-20231214144848829

步骤 4：确保选中 生成 API 选项。

image-20231214144910495

步骤 5：生成项目并运行 Web API。

使用继承策略

有三种继承策略可供选择：TPH 具有更好的查询性能，TPT 具有更高的存储效率，TPC 适用于不需要多表关联或查询的情况（从不或很少查询基类）。

image-20231214145656405

要使用继承策略，您需要创建一个父实体（不能是基类实体类型）和一个子实体。

以 TPH 为例：

  1. 创建一个名为 TPHBase 的实体，然后选择 TPH 继承策略。

    image-20231214145320704

  2. 创建名为 TPH 的实体并选择 TPHBase 作为基类实体。

    image-20231214145456513

复合查询

创建复合查询

首先创建两个实体：Person 和 IDCard，这里使用一对一关系进行演示，每个人只有一张身份证，一张身份证只能被一个人所有。

Person 实体：

image-20240613111910044

IDCard 实体：

image-20240613111902554

然后创建一个复合查询：

  1. 右键点击项目然后选择 添加 > 新建项。

image-20240613111925814

  1. 选择 复合查询设计。

image-20240613111935076

  1. 选择 Person 和 IDCard 两个实体用于设计查询模型。

image-20240613111942114

  1. 点击 创建。

image-20240613111948695

设置关系

普通关联

在 IDCard 和 Person 中，将 IDCard 的 PersonID 字段和 Person 的 ID 字段建立关联，可以通过长按并拖拽鼠标把 PersonID 字段和 ID 字段连接起来。也可以在右侧的 关系设置 标签页中，添加实体和字段来建立关联。

image-20240613112040082

选择两个实体的连接方式：Inner Join、Left Join、或 Right Join。

image-20240613112048889

条件关联

在右侧的 关系设置 标签页中，输入表达式来进行关系设置。

image-20240606154623844

设置分组

完成关系设置之后，我们可以进行分组，什么时候需要分组？这里的分组概念应该和数据库的保持一致，就是在使用聚合函数时，我们可以通过分组来统计不同组的数据：如统计男女人数，那么就需要按照性别进行分组，因为性别为男的人数和性别为女的人数需要分开显示，如果统计总人数那就不需要分组。

下面介绍两种分组模式。

字段分组

当选择字段分组时，可供选择的字段只能包含实体数据源的字段。

image-20240613112059396

添加字段分组后，结果集字段会添加相应字段。就是同步会输出分组字段，如下图所示，这里要按性别统计男女人数（性别分组）。

image-20240613112105673

表达式分组

除了字段分组，有时候还需要用表达式进行分组，以实现动态分组的效果，如下图所示。

image-20240613112112648

例如：按年龄进行分组，20岁以下为青年，20岁到60岁为壮年，60岁以上是老年，并统计各个年龄段的人数，那么分组表达式如下图所示。

image-20240613112119131

设置过滤条件

在完成复合查询的连接关系和分组设置之后，可以进行条件过滤设置。条件过滤设置和实体过滤器的使用方法一样，对实体的字段的值进行条件过滤，满足条件的进行查询，并且返回结果，不满足条件的不返回。例如：查询地址在深圳XX区的人的姓名和身份证号码，这样就需要对地址进行过滤。

注意：需要过滤的字段只能是数据源字段（不能选择输出结果集映射），如下图所示。

image-20240613112128880

输出结果集映射

添加字段

场景一：对一个查询模型进行输出，需要设置查询字段。

如查询连接后但是没有进行分组的信息，如查询出（地址、姓名、年龄）来自不同的实体，如下图所示。

image-20240613112137069

场景二：对分组和连接的结果统计。

分组过后，可供选择字段如下图所示。

image-20240613112144081

Group

Group 和 EF Core 框架保持一致，Group.key 是用户分组的字段。如果表达式只选择 key 下面的某一个字段进行输出，那么输出的就是分组字段。

Group 中的实体 Person 和 IDcard 是分组后的数据源，它们都是集合，例如要统计男女生人数可以如下图所示，输入表达式统计 Group 下面的分组数据源，就可以统计出男生人数和女生人数。

image-20240613112152744

QueryItems

QueryItems 中的数据源可以满足一部分需求，提供更加灵活的统计。QueryItems 其实是一个连接后未分组的结果集。

例如，为了统计男女比例，需要先统计总人数。这种情况下，不要使用 Group 下面的 Person，应该使用 QueryItems 下面的 Person（表示已连接并且未分组的数据），这时候 Count(Person) 就是总人数。

image-20240613112200236

枚举

枚举就是实体设计的枚举字段。在写表达式时可以引用枚举，减少字符串在代码中的频率。使用枚举生成的代码更加规范。

添加计算列

计算列可以对输出结果集进行进一步处理。

上面我们统计了分组的人数和总人数，接下来我们通过一个计算列来统计男女占比（男生人数或者女生人数/总人数）。

image-20240613112208148

image-20240613112214818

image-20240613112220313

项目

修改生成的项目

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

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

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