Entity Framework Core 工具参考 - .NET Core CLI

适用于 Entity Framework Core 的命令行接口 (CLI) 工具可执行设计时开发任务。 例如,可以创建迁移、应用迁移,并为基于现有数据库的模型生成代码。 这些命令是跨平台 dotnet 命令(属于 .NET Core SDK)的扩展。 这些工具适用于 .NET Core 项目。

使用 Visual Studio,请考虑使用包管理器控制台工具代替 CLI 工具。 包管理器控制台工具自动执行以下操作:

  • 使用包管理器控制台中选择的当前项目,无需手动切换目录
  • 在命令完成后打开该命令生成的文件。
  • 提供命令、参数、项目名称、上下文类型和迁移名称的 Tab 自动补全。

安装工具

可将 dotnet ef 安装为全局工具或本地工具。 大多数开发人员偏向于使用以下命令将 dotnet ef 安装为全局工具:

dotnet tool install --global dotnet-ef

若要将它用作本地工具,请使用工具清单文件恢复声明为工具依赖项的项目的依赖项。

使用下列命令更新工具:

dotnet tool update --global dotnet-ef

在将工具用于特定项目之前,需要将 Microsoft.EntityFrameworkCore.Design 添加到该项目中。

dotnet add package Microsoft.EntityFrameworkCore.Design

验证安装

运行以下命令,验证是否已正确安装 EF Core CLI 工具:

dotnet ef

命令的输出标识使用的工具版本:


                     _/\__
               ---==/    \\
         ___  ___   |.    \|\
        | __|| __|  |  )   \\\
        | _| | _|   \_/ |  //|\\
        |___||_|       /   \\\/\\

Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065

<Usage documentation follows, not shown.>

更新工具

使用 dotnet tool update --global dotnet-ef 将全局工具更新到最新的可用版本。 如果在项目中本地安装了这些工具,请使用 dotnet tool update dotnet-ef。 通过将 --version <VERSION> 追加到命令来安装特定版本。 有关更多详细信息,请参阅 dotnet 工具文档的更新部分。

使用工具

使用这些工具之前,可能需要创建启动项目或设置环境。

目标项目和启动项目

命令会引用项目和启动项目

  • 项目也称为目标项目,因为它是命令添加或删除文件的位置。 默认情况下,当前目录中的项目是目标项目。 可以使用 --project 选项将另一个项目指定为目标项目。

  • 启动项目是工具生成并运行的项目。 这些工具必须在设计时执行应用程序代码,才能获取有关项目的信息,例如数据库连接字符串和模型的配置。 默认情况下,当前目录中的项目是启动项目。 可以使用 --startup-project 选项将另一个项目指定为启动项目。

启动项目和目标项目通常是同一项目。 它们是单独项目的一个典型场景是:

  • EF Core 上下文和实体类均在 .NET Core 类库中。
  • .NET Core 控制台应用或 Web 应用引用类库。

还可以将迁移代码放置在独立于 EF Core 上下文的类库中

其他目标框架

CLI 工具适用于 .NET Core 项目和 .NET Framework 项目。 在 .NET Standard 类库中具有 EF Core 模型的应用可能没有 .NET Core 或 .NET Framework 项目。 例如,Xamarin 和通用 Windows平台应用也是如此。 在这种情况下,可以创建一个 .NET Core 控制台应用项目,该项目的唯一用途是充当工具的启动项目。 启动项目可以是不包含实际代码的虚拟项目 - 需要它的唯一理由是为工具提供一个目标。

为什么需要虚拟项目? 如前所述,这些工具必须在设计时执行应用程序代码。 为此,它们需要使用 .NET Core 运行时。 当 EF Core 模型位于面向 .NET Core 或 .NET Framework 的项目中时,EF Core 工具会从项目中借用运行时。 如果 EF Core 模型位于一个 .NET Standard 类库中,则不能这样做。 .NET Standard 不是实际的 .NET 实现;它是 .NET 实现必须支持的一组 API 的规范。 因此,.NET Standard 不足以让 EF Core 工具执行应用程序代码。 创建用作启动项目的虚拟项目提供了一个具体的目标平台,工具可以在其中加载 .NET Standard 类库。

ASP.NET Core 环境

可以在命令行上为 ASP.NET Core 项目指定环境。 此参数和任何其他参数都将传递到 Program.CreateHostBuilder 中。

dotnet ef database update -- --environment Production

提示

-- 标记指示 dotnet ef 将后面的所有内容都视为参数,而不要试图将它们解析为选项。 dotnet ef 未使用的任何额外参数都会转发到应用。

常用选项

选项 Short 说明
--json 显示 JSON 输出。
--context <DBCONTEXT> -c 要使用的 DbContext 类。 仅类名或完全限定命名的空间。 如果省略此选项,EF Core 将查找上下文类。 如果有多个上下文类,则此选项是必需的。
--project <PROJECT> -p 目标项目的项目文件夹的相对路径。 默认值是当前文件夹。
--startup-project <PROJECT> -s 启动项目的项目文件夹的相对路径。 默认值是当前文件夹。
--framework <FRAMEWORK> 目标框架目标框架名字对象。 当项目文件指定了多个目标框架,并且你想要选择其中一个目标框架时,请使用此选项。
--configuration <CONFIGURATION> 生成配置,例如 DebugRelease
--runtime <IDENTIFIER> 要为其还原包的目标运行时的标识符。 有关运行时标识符 (RID) 的列表,请参阅 RID 目录
--no-build 请勿生成项目。 旨在在生成处于最新状态时使用。
--help -h 显示帮助信息。
--verbose -v 显示详细输出。
--no-color 请勿为输出着色。
--prefix-output 具有级别的前缀输出。

任何其他参数都会传递到应用程序。

dotnet ef database drop

删除数据库。

选项:

选项 Short 说明
--force -f 请勿确认。
--dry-run 显示要删除的数据库,但不删除它。

上面列出了常用选项

dotnet ef database update

将数据库更新到上一次迁移或指定的迁移。

参数:

参数 说明
<MIGRATION> 目标迁移。 可以按名称或 ID 识别迁移。 数字 0 是一种特殊情况,表示首次迁移之前并会还原所有迁移。 如果未指定迁移,该命令默认还原到上一次迁移。

选项:

选项 说明
--connection <CONNECTION> 用于连接到数据库的连接字符串。 默认为 AddDbContextOnConfiguring 中指定的值。

上面列出了常用选项

下面的示例将数据库更新为指定的迁移。 第一个示例使用迁移名称,第二个示例使用迁移 ID 和指定的连接:

dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string

dotnet ef dbcontext info

获取有关 DbContext 类型的信息。

上面列出了常用选项

dotnet ef dbcontext list

列出可用的 DbContext 类型。

上面列出了常用选项

dotnet ef dbcontext optimize

生成由预编译查询使用的 DbContext 模型的编译版本。

有关详细信息,请参阅已编译的模型

选项:

选项 Short 说明
--output-dir <PATH> -o 要在其中放置文件的目录。 路径相对于项目目录。
--namespace <NAMESPACE> -n 要用于所有生成的类的命名空间。 默认设置为从根命名空间和输出目录以及 CompiledModels 生成。
--suffix <SUFFIX> 要附加到所有生成的文件的名称的后缀。 例如 .g ,可用于指示这些文件包含生成的代码
--no-scaffold 不要生成已编译的模型。 生成已编译的模型时,将使用此模式。
--precompile-queries 生成预编译查询。 如果目标项目包含任何查询,则 NativeAOT 编译需要此项
--nativeaot 在 NativeAOT 编译和预编译查询所需的已编译模型中生成其他代码

注意

NativeAOT 支持和预编译查询在 EF 9 中被视为试验性查询,在下一版本中可能会发生巨大变化。

上面列出了常用选项

下面的示例使用默认设置,如果项目中只有一个 DbContext,则可以正常运行:

dotnet ef dbcontext optimize

下面的示例为具有指定名称的上下文优化模型,并将该模型放置在单独的文件夹和命名空间中:

dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext

dotnet ef dbcontext scaffold

DbContext 生成代码,并为数据库生成实体类型。 为了让此命令生成实体类型,数据库表必须具有主键。

参数:

参数 说明
<CONNECTION> 用于连接到数据库的连接字符串。 对于 ASP.NET Core 2.x 项目,值可以是 name=<name of connection string>。 在这种情况下,名称来自为项目设置的配置源。
<PROVIDER> 要使用的提供程序。 通常,这是 NuGet 包的名称,例如:Microsoft.EntityFrameworkCore.SqlServer

选项:

选项 Short 说明
--data-annotations -d 使用属性配置模型(如果可能)。 如果省略此选项,则仅使用 Fluent API。
--context <NAME> -c 要生成的 DbContext 类的名称。
--context-dir <PATH> 要在其中放置 DbContext 类文件的目录。 路径相对于项目目录。 命名空间派生自文件夹名称。
--context-namespace <NAMESPACE> 要用于生成的 DbContext 类的命名空间。 注意:重写 --namespace
--force -f 覆盖现有文件。
--output-dir <PATH> -o 要在其中放置实体类文件的目录。 路径相对于项目目录。
--namespace <NAMESPACE> -n 要用于所有生成的类的命名空间。 默认设置为从根命名空间和输出目录生成。
--schema <SCHEMA_NAME>... 要为其生成实体类型的表和视图的架构。 若要指定多个架构,请为每个架构重复 --schema。 如果省略此选项,则包含所有架构。 如果使用此选项,架构中的所有表和视图都将包含在模型中,即使未使用 --table 显式包含它们也是如此。
--table <TABLE_NAME>... -t 要为其生成实体类型的表和视图。 若要指定多个表,请为每个表重复 -t--table。 可以使用“schema.table”或“schema.view”格式包含特定架构中的表或视图。 如果省略此选项,则包含所有表和视图。
--use-database-names 使用与数据库中显示的名称完全相同的表、视图、序列和列名称。 如果省略此选项,数据库名称将更改为更符合 C# 名称样式约定。
--no-onconfiguring 禁止在生成的 DbContext 类中生成 OnConfiguring 方法。
--no-pluralize 请勿使用复数化程序。

上面列出了常用选项

下面的示例搭建所有架构和表的基架,并将新文件放在“模型”文件夹中

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models

下面的示例仅搭建所选表的基架,并在单独的文件夹中创建具有指定名称和命名空间的上下文:

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models -t Blog -t Post --context-dir Context -c BlogContext --context-namespace New.Namespace

以下示例从使用机密管理器工具设置的项目配置中读取连接字符串。

dotnet user-secrets set ConnectionStrings:Blogging "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Blogging"
dotnet ef dbcontext scaffold Name=ConnectionStrings:Blogging Microsoft.EntityFrameworkCore.SqlServer

下面的示例跳过搭建 OnConfiguring 方法的基架。 如果要在类的外部配置 DbContext,这会很有用。 例如,ASP.NET Core 应用通常在 Startup.ConfigureServices 中配置它。

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;User Id=myUsername;Password=myPassword;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring

dotnet ef dbcontext script

从 DbContext 生成 SQL 脚本。 绕过任何迁移。

选项:

选项 Short 说明
--output <FILE> -o 要向其写入结果的文件。

上面列出了常用选项

dotnet ef migrations add

添加新的迁移。

参数:

参数 说明
<NAME> 迁移的名称。

选项:

选项 Short 说明
--output-dir <PATH> -o 用于输出文件的目录。 路径相对于目标项目目录。 默认路径为“Migrations”。
--namespace <NAMESPACE> -n 要用于生成的类的命名空间。 默认为从输出目录生成的命名空间。

上面列出了常用选项

dotnet ef migrations bundle

创建可执行文件以更新数据库。

选项:

选项 Short 说明
--output <FILE> -o 要创建的可执行文件的路径。
--force -f 覆盖现有文件。
--self-contained 同时绑定 .NET 运行时,因此不需要在计算机上安装它。
--target-runtime <RUNTIME_IDENTIFIER> -r 要绑定的目标运行时。

上面列出了常用选项

dotnet ef migrations has-pending-model-changes

注意

已在 EF Core 8.0 中添加此命令。

检查自上次迁移以来是否对模型进行了任何更改。

选项:

上面列出了常用选项

dotnet ef migrations list

列出可用的迁移。

选项:

选项 说明
--connection <CONNECTION> 用于连接到数据库的连接字符串。 默认为 AddDbContext 或 OnConfiguring 中指定的值。
--no-connect 不要连接到数据库。

上面列出了常用选项

dotnet ef migrations remove

删除上一次迁移,回退为上一次迁移所做的代码更改。

选项:

选项 Short 说明
--force -f 还原上次迁移,回退为上次迁移所做的代码和数据库更改。 如果连接到数据库时出错,则继续仅回退到代码更改。

上面列出了常用选项

dotnet ef migrations script

从迁移生成 SQL 脚本。

参数:

参数 说明
<FROM> 初始迁移。 可以按名称或 ID 识别迁移。 数字 0 是一种特殊情况,表示首次迁移之前。 默认值为 0。
<TO> 结束迁移。 默认为上一次迁移。

选项:

选项 Short 说明
--output <FILE> -o 要在其中写入脚本的文件。
--idempotent -i 生成可在任何迁移时用于数据库的脚本。
--no-transactions 不要生成 SQL 事务语句。

上面列出了常用选项

以下示例创建用于 InitialCreate 迁移的脚本:

dotnet ef migrations script 0 InitialCreate

以下示例为 InitialCreate 迁移后的所有迁移创建脚本。

dotnet ef migrations script 20180904195021_InitialCreate

其他资源