适用于 Entity Framework Core 的命令行接口 (CLI) 工具可执行设计时开发任务。 例如，他们可以创建迁移、应用迁移，并为基于现有数据库的模型生成代码。 这些命令是跨平台 dotnet 命令的扩展，它是 .NET SDK 的一部分。 这些工具适用于 .NET 项目。
使用 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 类库中。
- .NET 控制台应用或 Web 应用引用类库。
还可以将迁移代码放置在独立于 EF Core 上下文的类库中。
其他目标框架
CLI 工具适用于 .NET 项目和 .NET Framework 项目。 在 .NET Standard 类库中具有 EF Core 模型的应用可能没有 .NET 或 .NET Framework 项目。 例如，Xamarin 和通用 Windows平台应用也是如此。 在这种情况下，可以创建一个 .NET 控制台应用项目，其唯一目的是充当工具的启动项目。 该项目可以是一个没有实际代码的虚拟项目——其唯一目的是为工具提供一个目标。
Important
Xamarin.Android、Xamarin.iOS、Xamarin.Mac 现在直接集成到 .NET（从 .NET 6 开始）作为适用于 Android 的 .NET、适用于 iOS 的 .NET 和适用于 macOS 的 .NET。 如果要使用这些项目类型进行构建，则应将其升级到 .NET SDK 样式项目，以便继续提供支持。 有关将 Xamarin 项目升级到 .NET 的详细信息，请参阅 从 Xamarin 升级到 .NET & .NET MAUI 文档。
为什么需要虚拟项目？ 如前所述，这些工具必须在设计时执行应用程序代码。 为此，他们需要使用 .NET 运行时。 当 EF Core 模型位于面向 .NET 或 .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
Tip
-- 标记指示 dotnet ef 将后面的所有内容都视为参数，而不要试图将它们解析为选项。
dotnet ef 未使用的任何额外参数都会转发到应用。
常用选项
| Option | Short | Description |
|---|---|---|
--json |
显示 JSON 输出。 | |
--context <DBCONTEXT> |
-c |
要使用的 DbContext 类。 类名或带命名空间的完全限定名称。 如果省略此选项，EF Core 将查找上下文类。 如果有多个上下文类，则此选项是必需的。 |
--project <PROJECT> |
-p |
目标项目的项目文件夹的相对路径。 默认值是当前文件夹。 |
--startup-project <PROJECT> |
-s |
启动项目的项目文件夹的相对路径。 默认值是当前文件夹。 |
--framework <FRAMEWORK> |
目标框架标识符的目标框架。 当项目文件指定了多个目标框架，并且你想要选择其中一个目标框架时，请使用此选项。 | |
--configuration <CONFIGURATION> |
生成配置，例如 Debug 或 Release。 |
|
--runtime <IDENTIFIER> |
用于还原包的目标运行时的标识符。 有关运行时标识符 (RID) 的列表，请参阅 RID 目录。 | |
--no-build |
请勿生成项目。 旨在当构建处于最新版本时使用。 | |
--help |
-h |
显示帮助信息。 |
--verbose |
-v |
显示详细输出。 |
--no-color |
请勿为输出着色。 | |
--prefix-output |
用级别作为前缀输出。 |
任何其他参数都会传递到应用程序。
dotnet ef database drop
删除数据库。
Options:
| Option | Short | Description |
|---|---|---|
--force |
-f |
请勿确认。 |
--dry-run |
显示要删除的数据库，但不删除它。 | |
--connection <CONNECTION> |
用于连接到数据库的连接字符串。 默认为 AddDbContext 或 OnConfiguring 中指定的值。 在 EF Core 11 中添加。 |
上面列出了常用选项。
dotnet ef database update
将数据库更新到上一次迁移或指定的迁移。
Arguments:
| Argument | Description |
|---|---|
<MIGRATION> |
目标迁移。 可以按名称或 ID 识别迁移操作。 数字 0 是一种特殊情况，表示在首次迁移之前，并导致所有迁移被还原。 如果未指定迁移，该命令默认还原到上一次迁移。 |
Options:
| Option | Description |
|---|---|
--connection <CONNECTION> |
用于连接到数据库的连接字符串。 默认为 AddDbContext 或 OnConfiguring 中指定的值。 |
上面列出了常用选项。
下面的示例将数据库更新为指定的迁移。 第一个示例使用迁移名称，第二个示例使用迁移 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 使用的模型的编译版本，并预编译查询。
有关详细信息，请参阅已编译的模型。
Options:
| Option | Short | Description |
|---|---|---|
--output-dir <PATH> |
-o |
要在其中放置文件的目录。 路径相对于项目目录。 |
--namespace <NAMESPACE> |
-n |
要用于所有生成的类的命名空间。 默认设置为从根命名空间和输出目录以及 CompiledModels 生成。 |
--suffix <SUFFIX> |
要附加到所有生成的文件的名称的后缀。 例如 .g ，可用于指示这些文件包含生成的代码 |
|
--no-scaffold |
不要生成已编译的模型。 生成已编译的模型时，将使用此模式。 | |
--precompile-queries |
生成预编译查询。 如果目标项目包含任何查询，则 NativeAOT 编译需要此项 | |
--nativeaot |
在 NativeAOT 编译和预编译查询所需的已编译模型中生成其他代码 |
Note
NativeAOT 支持和预编译查询在 EF 9 中被视为试验性查询，在下一版本中可能会发生巨大变化。
上面列出了常用选项。
下面的示例使用默认设置，如果项目中只有一个 DbContext，则可以正常运行：
dotnet ef dbcontext optimize
下面的示例为具有指定名称的上下文优化模型，并将该模型放置在单独的文件夹和命名空间中：
dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext
dotnet ef dbcontext scaffold
为 DbContext 生成代码，并为数据库生成实体类型。 为了让此命令生成实体类型，数据库表必须具有主键。
Arguments:
| Argument | Description |
|---|---|
<CONNECTION> |
用于连接到数据库的连接字符串。 对于 ASP.NET Core 2.x 项目，值可以是 name=<连接字符串名称>。 在这种情况下，名称来自为项目设置的配置源。 |
<PROVIDER> |
要使用的提供程序。 通常，这是 NuGet 包的名称，例如：Microsoft.EntityFrameworkCore.SqlServer。 |
Options:
| Option | Short | Description |
|---|---|---|
--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 |
禁止在生成的 OnConfiguring 类中生成 DbContext 方法。 |
|
--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;Integrated Security=true;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring
dotnet ef dbcontext script
从 DbContext 生成 SQL 脚本。 绕过任何迁移。
Options:
| Option | Short | Description |
|---|---|---|
--output <FILE> |
-o |
要向其写入结果的文件。 |
上面列出了常用选项。
dotnet ef migrations add
添加新的迁移。
Arguments:
| Argument | Description |
|---|---|
<NAME> |
迁移的名称。 |
Options:
| Option | Short | Description |
|---|---|---|
--output-dir <PATH> |
-o |
这个目录用于输出文件。 路径相对于目标项目目录。 默认路径为“Migrations”。 |
--namespace <NAMESPACE> |
-n |
要用于生成的类的命名空间。 默认为从输出目录生成。 |
上面列出了常用选项。
dotnet ef migrations bundle
创建可执行文件以更新数据库。
Options:
| Option | Short | Description |
|---|---|---|
--output <FILE> |
-o |
要创建的可执行文件的路径。 |
--force |
-f |
覆盖现有文件。 |
--self-contained |
同时绑定 .NET 运行时，因此不需要在计算机上安装它。 | |
--target-runtime <RUNTIME_IDENTIFIER> |
-r |
要打包的目标运行时。 |
上面列出了常用选项。
dotnet ef migrations has-pending-model-changes
Note
已在 EF Core 8.0 中添加此命令。
检查自上次迁移以来是否对模型进行了任何更改。
Options:
上面列出了常用选项。
dotnet ef migrations list
列出可用的迁移。
Options:
| Option | Description |
|---|---|
--connection <CONNECTION> |
用于连接到数据库的连接字符串。 默认为 AddDbContext 或 OnConfiguring 中指定的值。 |
--no-connect |
不要连接到数据库。 |
上面列出了常用选项。
dotnet ef migrations remove
删除上一次迁移，回退为上一次迁移所做的代码更改。
Options:
| Option | Short | Description |
|---|---|---|
--force |
-f |
还原最新迁移，将代码和数据库的更改回滚到最新迁移之前的状态。 如果连接到数据库时出错，则仅继续回退代码更改。 |
--connection <CONNECTION> |
用于连接到数据库的连接字符串。 默认为 AddDbContext 或 OnConfiguring 中指定的值。 在 EF Core 11 中添加。 |
|
--offline |
在不连接到数据库的情况下删除迁移。 在 EF Core 11 中添加。 |
上面列出了常用选项。
Note
--offline和--force选项不能一起使用，因为--force需要数据库连接来检查迁移是否已应用，然后再还原迁移。
dotnet ef migrations script
从迁移生成 SQL 脚本。
Arguments:
| Argument | Description |
|---|---|
<FROM> |
初始迁移。 可以按名称或 ID 识别迁移操作。 数字 0 是一种特殊情况，表示首次迁移之前。 默认值为 0。 |
<TO> |
迁移的结束 默认为上一次迁移。 |
Options:
| Option | Short | Description |
|---|---|---|
--output <FILE> |
-o |
要在其中写入脚本的文件。 |
--idempotent |
-i |
生成可在任何迁移时用于数据库的脚本。 |
--no-transactions |
不要生成 SQL 事务语句。 |
上面列出了常用选项。
以下示例创建用于 InitialCreate 迁移的脚本：
dotnet ef migrations script 0 InitialCreate
以下示例为 InitialCreate 迁移后的所有迁移创建脚本。
dotnet ef migrations script 20180904195021_InitialCreate
配置文件
Note
EF Core 11 中引入了此功能。
从 EF Core 11 开始， dotnet ef 可以从 JSON 配置文件加载默认选项值。 这减少了跨多个调用重复相同的命令行选项的需求。
文件位置和发现
将名为dotnet-ef.json.config的文件放置在目录中：
<repository root>/
└── .config/
└── dotnet-ef.json
运行dotnet ef时，它会从当前工作目录向上遍历目录树，并使用首次找到的.config/dotnet-ef.json文件。 这意味着可以将文件放置在存储库的根目录，并且将从任何子目录中使用该文件。
支持的属性
配置文件是具有以下可选属性的 JSON 对象：
{
"project": "src/App.Infrastructure",
"startupProject": "src/App.Api",
"framework": "net11.0",
"configuration": "Debug",
"context": "AppDbContext",
"runtime": "win-x64",
"verbose": true,
"noColor": false,
"prefixOutput": false
}
| 财产 | 类型 | Description |
|---|---|---|
project |
字符串 | 目标项目文件夹的相对路径或绝对路径。 相对路径是相对于包含该文件的目录的父级来解析的。 |
startupProject |
字符串 | 启动项目文件夹的相对路径或绝对路径。 相对路径是相对于包含文件的目录的父目录进行解析的。 |
framework |
字符串 | 目标框架标识。 |
configuration |
字符串 | 生成配置，例如 Debug 或 Release。 |
context |
字符串 | 要使用的 DbContext 类。 类名或带命名空间的完全限定名称。 |
runtime |
字符串 | 用于还原包的目标运行时的标识符。 有关运行时标识符 (RID) 的列表，请参阅 RID 目录。 |
verbose |
布尔 | 启用详细输出。 |
noColor |
布尔 | 禁用彩色控制台输出。 |
prefixOutput |
布尔 | 为其严重性级别的输出行添加前缀。 |
所有属性都是可选的。 仅包括所需的属性。
Note
显式命令行选项始终优先于配置文件中的值。
