跳到主要内容

实体设计器

本文将介绍实体设计器。在创建实体文件后，此设计器将打开。 它允许您创建和配置与 EF Core 8.0 兼容的实体。

创建实体​

可以通过以下两种方式创建实体：

  1. 从零开始创建实体

    选择菜单 项目 > 新建项，在 添加新项 窗口中选择 实体设计（从零开始）。将会创建一个空白实体文件，你可以在此实体文件中从零开始添加一个或多个实体表（从组件库中拖拽表组件到设计视窗中），或者直接将已有数据表导入为实体表（同方法2）。

  2. 从数据库导入实体

    选择菜单 项目 > 新建项，在 添加新项 窗口中选择 实体设计（从数据库导入） ，然后选择一个或多个已存在的数据库表，将这些表直接导入为实体表。在实体设计器中，你也可以随时从设计视窗的顶部工具栏选择 从数据库导入 工具（image-20250630111336921）选择数据表导入为实体。具体步骤，请参考 此教程。

实体设计器由以下组成：组件库、大纲树、设计视窗、实体（表）选项页、数据库选项页。

组件库​

在实体设计器的组件库中，提供了基本组件如：空白表、审计表和多租户表，为您提供创建不同类型数据库表的基础模板和功能支持：

  1. 空白表：空白表是指一个不包含任何预设字段或业务逻辑的表。在实体设计器中，空白表是最基础的数据库实体，用户可以根据实际需求添加字段，设置约束，定义主键等。
  2. 审计表：审计表用于记录数据的操作历史，包括对数据的创建、更新、删除等操作的审计日志。审计表会自动记录每条记录的变化历史，适用于需要追溯和审计的场景。审计表包含字段如：创建人，创建时间，更新人，更新时间等。这些字段的数据会自动更新和维护，不需要用户处理。
  3. 多租户表：用于实现多租户架构下的数据隔离。多租户表通常包含一个标识租户的字段（TenantId），确保不同租户的数据不会互相干扰。多租户表的数据会自动更新和维护，不需要用户处理。

image-20250625161549491

大纲树​

在实体设计器中，大纲树作为一种结构化视图，帮助用户轻松理解及浏览数据库、表和字段之间的关系，直观管理和导航数据库中的各个元素。它通过层级化的方式呈现数据库、表和字段的结构，使得用户可以快速选择数据库/表或删除表/字段。

大纲树与设计视窗之间实时同步与交互。当用户在大纲树中选择数据库、表或字段时，设计视窗中的焦点及相关配置页面会随之更新。

例如，当用户在大纲树中选中一个表时，设计视窗会同步选中该表的设计界面，并且选中该表的配置页面（ 实体（表） 选项卡）。你可以在 实体（表） 选项卡中对表进行修改，例如：添加/删除字段，修改字段的数据类型，设置主键、外键、索引等。详细说明，请参考 实体（表）选项页。

例如，当用户在大纲树中选中根节点时，数据库的配置页面（数据库选项卡）将会被选中。您可以在数据库选项卡中修改数据库名称、类型、连接字符串等。详细说明，请参考 数据库选项页。

image-20250625161701342

设计视窗​

在实体设计器中，设计视窗提供了一个直观、交互式的可视化设计界面，帮助用户通过图形化的方式创建、编辑和管理数据库表、字段以及它们之间的关系。设计视窗支持通过鼠标拖拽添加表以及建立表之间的外键关系。

设计视窗顶部的工具条提供以下功能（您可以将鼠标悬停在某个图标上，以查看图标所提供的功能）：

image-20250630131450110

  • 缩放百分比 -- 用户可以点击按钮选择合适的百分比，或者使用鼠标滚轮来缩小或放大设计视窗的视图。
  • 网格 -- 用户可以选择设计视窗中是否显示网格线。
  • 小地图 -- 用户可以选择设计视窗的右下角是否显示一个小地图。它展示了整个设计视窗的缩略图，并实时反映视图中的位置，有助于用户快速定位和导航到特定区域。
  • 排序 -- 自动优化实体表的整体排布，使设计画布更加整齐有序。例如：将各个实体表自动进行排布整理，避免重叠，提升整体布局的清晰度和可读性。如果实体表之间存在外键或其他关联关系，排序功能还会尝试调整实体间位置，减少连线交叉，使关系更清晰直观。
  • 全部展开 -- 用户可以选择一次性展开所有表中的字段，方便用户查看每个表的所有字段。
  • 全部折叠 -- 用户可以选择一次性隐藏所有表中的字段，只显示表名。适用于查看表之间的关系时，减少视觉干扰。
  • 从数据库导入 -- 用户可以直接从现有的数据库导入表和字段，将数据库实体（如表、字段、主键、外键等）直接导入到设计视窗中。可以避免手动创建每一个表结构，节省时间。具体说明，请参考 开发教程。
  • 搜索 -- 用户可以输入表名或关键字来快速定位到目标表。
  • 视图模式/列表模式 -- 用户可以选择将设计视窗在图形化视图和列表模式之间切换。
  • 生成逻辑和视图设计 -- 用户可以基于设计视窗中已有的实体表设计直接创建与之相关的逻辑设计和视图设计。

image-20250625161806948

生成逻辑和视图设计​

在完成实体设计后，可以点击设计视窗工具条右边的 生成逻辑和视图设计 快速生成逻辑和视图。

在 生成逻辑和视图设计 窗口中，选择增删改查方法。设置逻辑文件的存放路径，默认存放到 逻辑设计 子目录。选择是否按实体名称自动创建子文件夹，是否覆盖同名文件，以及是否生成后自动打开文件。

点击 仅生成逻辑 按钮将只生成逻辑文件。如果您还需要生成视图文件，请点击 下一步配置视图 按钮。

image-20250620142026019

点击 下一步配置视图 按钮后，您可以选择要生成的视图页面以及关联的API方法。同样，您可以设置视图文件的存放路径，默认存放到 视图设计 子目录。选择是否按逻辑名称自动创建子文件夹，是否覆盖同名文件，以及是否生成后自动打开文件。点击 确认 后，将按设置生成逻辑文件和视图文件。

image-20250620143915305

"实体（表）"选项页​

在实体设计器中，实体（表） 选项卡是用户进行设计和管理表/字段的核心区域。它提供了表和字段的基本配置选项，以及其他重要功能如外键管理、索引等。以下是对 实体（表） 选项卡中主要功能和配置的详细描述。

常规​

表名：数据库表的名称。

架构：如果使用关系数据库，您还需要指定表架构。 如果此处未指定架构名称，则将使用数据库中的默认架构。

显示名称： 表的显示名称。

列名、数据类型、可空 等：请参考列设计小节。

image-20250625163158560

列设计​

每个表包含若干列（也叫字段），每列都有特定的数据类型（如String，Int，Boolean等），您可以为每列设置约束，例如：主键，是否可空，是否为集合等。

您可以点击字段列表底端的 +添加列，添加新字段到当前列表，点击字段左边的 编辑 图标（image-20250627144449891)可以修改字段的基本配置，或者点击字段右边终端的 拖动排序 图标（image-20250627144903860)调整字段次序。

常规​

  • 列名：列的名称。
  • 显示名称：列的显示名称。
  • 数据类型： 列的数据类型。 例如，Int32 数据类型将在 C# 代码中定义为 int 类型。支持的数据类型包括：
    • 整数类型：Int16、Int32、Int64、UInt16、UInt32、UInt64
    • 字符类型：String、Char
    • 日期时间类型：DateTime、DateTimeOffset、DateOnly、TimeOnly、TimeSpan
    • 浮动类型：Decimal、Single、Double
    • 其他：Boolean、Guid、Byte、枚举、模型（注：模型还可支持 Any 类型）
  • 主键：详见以下小节。
  • 可空：当选择 可空 选项时，该列将允许为空值。 对于关键字段如主键或约束字段，通常会设置为不可空，以确保数据的完整性。
  • 集合：详见以下小节。
  • 长度：指定字符串类型（例如 String 和 Char）列的最大长度。
  • 精度：指定数字类型（例如 Double 和 Decimal）列中可以存储的总位数（包括整数位数和小数位数）。
  • 小数位数：指定数字类型（例如 Double 和 Decimal）列中小数点后面的位数，即该列在存储浮动小数点数值时允许的小数位数。
  • 默认值：指定列的默认值。 在插入新记录时，如果该列没有显式指定值时，将自动使用默认值。 指定默认值有以下三种方式： 1) 手动输入默认值； 2）通过表达式计算默认值； 3）通过 SQL 语句设置默认值。
  • 描述： 列的描述。简短说明列的用途或存储的数据类型。

image-20250321101233860

数据规范​

  • 数据：指定是否为自增列。自增列的值在每次插入数据时会自动递增。某些数据类型（例如 Int、UInt）具有这个选项。
    • 起始值：指定自增列从某个起始值开始，并在每次插入新数据时自动增加。
    • 增量值：指定自增列的步长，即每次递增的数量。
  • 计算列：指定是否为计算列。计算列的值由其他列的值通过表达式或公式自动计算得出。计算列的值根据其他列的值在查询时动态计算生成，也可以持久化存储在数据库中。
    • 持久化：指定计算列的值是否被持久化存储在数据库中。如果计算列是持久化的，数据库会存储计算结果，而不是每次查询时都动态计算。
    • 表达式：指定定义计算列的值的表达式、公式或函数，例如，可以将两列的和、差、乘积或其他计算逻辑作为计算列的定义。
  • 序列：使用序列生成唯一的标识符。点击 添加序列 后将打开 自定义唯一标识 窗口（详见 自定义唯一标识）。某些数据类型（例如 String、Int）具有这个选项。

主键​

在 实体（表） 选项卡中 主键 是一个非常重要的功能，用于确保表中数据的唯一性和完整性。主键是每个表中用来唯一标识记录的字段或字段组合。每个表只能有一个主键，主键可以由一个或多个列组成，多个列组成的主键叫 复合主键。

当选择 主键 选项时，C# 代码中会自动为该字段生成 [key] 属性或 HasKey 方法。

如果表中不指定主键，则会生成 [Keyless] 属性或 HasNoKey 方法。 无主键表主要用于不需要考虑每条数据唯一性的情况。无主键表主要为临时表、日志表、关联表等。例如，一个随机名称表（名称重复与否无关紧要）。虽然表可以没有主键，但通常不推荐。

复合主键 由两个或更多的列组成，这些列的值组合在一起形成唯一的标识符。当单一列无法满足唯一性要求时，可以指定多个字段组成主键来确保记录的唯一性。每个列单独的值可能在表中是重复的，但组合起来的值必须是唯一的。比如OrderDetails表中一个orderid可以包含多个商品，那么将orderid和prodctid组合起来建立一个复合主键就可以唯一标识每一条记录。在多对多关系中，经常使用复合主键作为外键，例如OrderDetails表的orderid和prodctid可以作为外键，引用Orders表和Products表的主键。虽然复合主键在某些场景非常有用，但也需要注意带来的性能影响和管理复杂性。

集合​

将某个字段设置为 集合 类型，表示该字段支持存储多个值，而不是单一的值，也就是说，该字段可以存储一个数据集合如列表、数组、集合或其他形式的多个元素，而不只是一个单一的项。

集合类型的字段通常用于存储多重数据的场景。例如，在多对多关系中可以使用集合类型的字段来存储与其他表的多个关联（比如一个学生可能有多个课程，一个课程可能被多个学生选修）。假如你希望在单个字段中存储多个相关数据项（如多个电话号码、多个电子邮件地址等），也可以使用集合来表示这些数据。

外键​

外键约束用于确保数据之间的关系完整性，防止出现无效或孤立的数据。例如，当某个表中的外键列指定另一个表的主键列时，在插入数据时，必须确保外键列的值在参照表中已存在。

您可以通过以下方式添加外键到当前外键列表。

  1. 方式1：在 实体（表） 选项卡 > 外键 中点击 添加外键，然后选择当前表中需要创建外键约束的列（该列将作为外键），选择主键表（即外键所参照的表）及列（即作为外键参照的主键或唯一键列）。
  2. 方式2：在设计器视窗中用鼠标点击当前表中需要创建外键约束的列，然后拖拽鼠标到参照表中的主键，两列之间出现一条虚线，松开鼠标后虚线将变成带箭头实线。箭头的方向从包含外键的表（源表）指向包含主键或唯一字段的参照表。

实体（表） 选项卡中的外键列表和设计视窗中的可视化设计界面实时同步。当你通过方式1创建了一个外键约束时，可视化设计界面中也会在两个字段之间同步画一条带箭头的实线；反之亦然，当你通过方式2创建了一个外键约束时，实体（表） 选项卡中的外键列表也会自动添加外键字段和主键/唯一字段连接。

当前表可以和一个或多个主键表建立一个或多个外键约束：

  • 一对多：一个表的记录可以与另一个表的多条记录相关联。例如：customer表与order表之间的关系就是一对多关系，外键约束为：从order表（多方表）的字段customer_id（外键字段）指向customer表（一方表）的id字段（主键）。
  • 多对多：两个表通过一个中间表来建立关联。例如students和courses之间通过交叉表student_courses来建立多对多的关系。外键约束为：从交叉表的外键字段分别指向两个主表的主键。
  • 一对一：一个表的记录只与另一个表的一条记录相关联。例如：employee表和employeedetails表之间的关系，外键约束为：从employee表的字段指向employeedetails表的字段，表示每个员工有一条对应的员工详细信息记录。

image-20250321101531759

外键创建完成后，您可以点击外键左边的 编辑 图标为当前外键指定以下设置：

  • 外键名称：外键约束的名字。
  • 删除规则：如果删除参照表的主键，外键约束将根据指定的动作处理数据：不执行任何操作、级联、设置 Null、设置默认值。
    • 不执行任何操作：当参照表的主键被删除时，当前表不做任何操作。 当外键列设置为不可空时，可选择此选项。
    • 级联：当参照表的主键被删除时，当前表中与其相关联的所有记录也会被自动删除。
    • 设置 Null：当参照表的主键被删除时，当前表中与其相关联的所有记录的外键值都会被设置为空。 当外键列设置为可空时，可选择此选项。
    • 设置默认值：当参照表的主键被删除时，当前表中与其相关联的所有记录的外键值的处理方式将遵循数据库定义该外键时设定的默认删除策略。 通常为级联删除，或者是不执行操作或设置为空，具体取决于数据库定义。
  • 描述：对该外键的描述。

image-20250321101646608

索引​

选择适当的列创建索引可以提高数据库查询性能。索引为表中的字段或字段组合提供快速访问路径。

您可以添加新索引到当前索引列表。在 实体（表） 选项卡 > 索引 中点击 添加索引，然后选择需要创建索引的列，并设置索引列的排序方式（升序或降序）。您可以创建单列索引（为每个列分别创建一个索引），也可以创建多列索引（将多个列组合创建一个索引）。

索引创建完成后，您可以点击索引左边的 编辑 图标为当前索引指定以下设置：

  • 索引名称：索引的名称。
  • 唯一：指定该索引是否为唯一索引。如果索引是唯一的，则该索引列中的每个值不能重复。
  • 描述：对该索引的描述。

image-20250321102416923

"数据库"选项页​

数据库 选项卡主要用于配置和管理数据库连接的基本信息，包括以下设置：

  • 名称 -- 数据库名称。

  • 类型 -- 数据库类型。支持的类型包括：MySQL、PostgreSQL、SQL Server、Oracle、SQLite。

  • 连接字符串 -- 连接到数据库所需的详细信息，例如：数据库的地址、端口、用户名、密码、数据库名称等等。连接字符串的格式取决于数据库类型，例如：

    MySQL：server=myServerAddress;Database=myDatabase;Uid=myUsername;Pwd=myPassword;

    SQL Server：server=myServerAddress;Database=myDatabase;UserId=myUsername;Password=myPassword;

    PostgreSQL：Host=myServer;Port=5432;Usename=myUser;Password=myPassword;Database=myDatabase;

  • 描述 -- 关于数据库的作用或配置的简短描述。

image-20250321102501743