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 生成。 |
上面列出了常用选项。
下面的示例使用默认设置,如果项目中只有一个 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