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> |
生成配置，例如 Debug 或 Release。 |
|
--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> |
用于连接到数据库的连接字符串。 默认为 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 模型的编译版本。
有关详细信息，请参阅已编译的模型。
选项：
| 选项 | 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
