.NET CLI 命令参考

概述

.NET CLI (Command-Line Interface) 是 EF Core 迁移和脚手架的主要工具。本文档提供完整的命令参考。

安装 EF Core CLI

bash

# 全局安装(推荐)
dotnet tool install --global dotnet-ef

# 验证安装
dotnet ef --version

# 更新到最新版本
dotnet tool update --global dotnet-ef

# 项目级别安装
dotnet new console
dotnet tool install dotnet-ef

迁移命令

创建迁移

bash

# 基本语法
dotnet ef migrations add <MigrationName>

# 示例
dotnet ef migrations add InitialCreate
dotnet ef migrations add AddUserTable
dotnet ef migrations add UpdateProductSchema

# 指定输出目录
dotnet ef migrations add InitialCreate --output-dir Migrations

# 指定 DbContext
dotnet ef migrations add InitialCreate --context AppDbContext

# 指定项目(多项目方案)
dotnet ef migrations add InitialCreate \
  --project src/Infrastructure \
  --startup-project src/WebApi

# 自定义命名空间
dotnet ef migrations add InitialCreate \
  --namespace MyCompany.MyApp.Migrations

应用迁移

bash

# 应用到最新迁移
dotnet ef database update

# 应用到特定迁移
dotnet ef database update AddUserTable

# 回滚所有迁移(清空数据库)
dotnet ef database update 0

# 指定连接字符串
dotnet ef database update \
  --connection "Server=localhost;Database=MyApp;..."

# 指定环境
dotnet ef database update --environment Production

删除迁移

bash

# 删除最新的迁移(未应用的)
dotnet ef migrations remove

# 强制删除(即使已部分应用)
dotnet ef migrations remove --force

列出迁移

bash

# 列出所有迁移
dotnet ef migrations list

# 输出格式: JSON
dotnet ef migrations list --json

# 示例输出:
# [
#   {"Id":"20260401000000_InitialCreate","Name":"InitialCreate"},
#   {"Id":"20260402000000_AddUsers","Name":"AddUsers"}
# ]

数据库命令

生成 SQL 脚本

bash

# 生成从空数据库到最新迁移的脚本
dotnet ef migrations script

# 生成特定范围的脚本
dotnet ef migrations script InitialCreate AddUsers

# 生成幂等脚本(可重复执行)
dotnet ef migrations script --idempotent

# 输出到文件
dotnet ef migrations script --output migrations.sql

# 不包含事务
dotnet ef migrations script --no-transactions

删除数据库

bash

# 删除数据库
dotnet ef database drop

# 强制删除(跳过确认)
dotnet ef database drop --force

# 指定环境
dotnet ef database drop --environment Production

检查数据库状态

bash

# 检查是否有待应用的迁移
dotnet ef database update --dry-run

# 查看数据库上下文信息
dotnet ef dbcontext info

DbContext 命令

列出 DbContext

bash

# 列出项目中所有 DbContext
dotnet ef dbcontext list

# JSON 格式
dotnet ef dbcontext list --json

优化模型

bash

# 优化模型(提高启动性能)
dotnet ef dbcontext optimize

# 输出目录
dotnet ef dbcontext optimize --output-dir CompiledModels

# 命名空间
dotnet ef dbcontext optimize --namespace MyApp.CompiledModels

缩放模型

bash

# 创建模型的缩小版本(用于诊断)
dotnet ef dbcontext scale

脚手架命令

从数据库生成代码

bash

# 基本语法
dotnet ef dbcontext scaffold "<connection_string>" <provider>

# SQL Server 示例
dotnet ef dbcontext scaffold \
  "Server=localhost;Database=AdventureWorks;Trusted_Connection=True;" \
  Microsoft.EntityFrameworkCore.SqlServer

# PostgreSQL 示例
dotnet ef dbcontext scaffold \
  "Host=localhost;Database=adventureworks;Username=postgres;Password=pass" \
  Npgsql.EntityFrameworkCore.PostgreSQL

# MySQL 示例
dotnet ef dbcontext scaffold \
  "Server=localhost;Database=adventureworks;Uid=root;Pwd=pass" \
  Pomelo.EntityFrameworkCore.MySql

# 完整参数
dotnet ef dbcontext scaffold \
  "Server=localhost;Database=MyApp;Trusted_Connection=True;" \
  Microsoft.EntityFrameworkCore.SqlServer \
  --output-dir Models \
  --context-dir Data \
  --context MyAppContext \
  --schema dbo \
  --table Users \
  --table Products \
  --data-annotations \
  --force \
  --no-pluralize \
  --use-database-names

参数说明

参数	简写	说明
`--output-dir`	`-o`	实体类输出目录
`--context-dir`	-	DbContext 输出目录
`--context`	-	DbContext 类名
`--schema`	-	指定架构(逗号分隔)
`--table`	`-t`	指定表(可多个)
`--data-annotations`	-	使用数据注解
`--force`	`-f`	覆盖现有文件
`--no-pluralize`	-	禁用复数化
`--use-database-names`	-	使用数据库名称
`--namespace`	-n	自定义命名空间

通用选项

项目选项

bash

# 指定项目
--project <PATH>

# 指定启动项目
--startup-project <PATH>

# 指定框架
--framework <FRAMEWORK>

# 指定配置
--configuration <CONFIGURATION>

verbosity 选项

bash

# 详细程度
--verbose          # 详细输出
--no-color         # 禁用颜色
--prefix-output    # 添加前缀

其他选项

bash

# 根目录
--root-namespace <NAMESPACE>

# 语言
--language <LANGUAGE>

# 帮助
--help
-h

实际工作流示例

新项目初始化

bash

# 1. 创建项目
dotnet new webapi -n MyApp
cd MyApp

# 2. 添加 EF Core 包
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

# 3. 创建第一个迁移
dotnet ef migrations add InitialCreate

# 4. 应用迁移
dotnet ef database update

# 5. 验证
dotnet ef migrations list

开发迭代

bash

# 修改实体类后

# 1. 创建新迁移
dotnet ef migrations add AddEmailToUsers

# 2. 检查迁移内容
cat Migrations/*_AddEmailToUsers.cs

# 3. 应用迁移
dotnet ef database update

# 4. 如果有问题,回滚
dotnet ef database update PreviousMigration
dotnet ef migrations remove

# 5. 修正后重新创建
dotnet ef migrations add AddEmailToUsers
dotnet ef database update

生产部署

bash

# 1. 生成 SQL 脚本
dotnet ef migrations script --idempotent --output deploy.sql

# 2. 审查脚本
cat deploy.sql

# 3. 发送给 DBA 执行
# 或在 CI/CD 中自动执行

常见问题

Q1: 找不到 dotnet-ef 命令

bash

# 解决: 安装工具
dotnet tool install --global dotnet-ef

# 如果已安装但找不到,刷新 PATH
# Windows: 重启终端
# Linux/Mac: source ~/.bashrc 或 source ~/.zshrc

Q2: 多项目方案报错

bash

# 错误: Your startup project doesn't reference Microsoft.EntityFrameworkCore.Design

# 解决: 指定启动项目
dotnet ef migrations add InitialCreate \
  --project src/Infrastructure \
  --startup-project src/WebApi

Q3: 迁移文件名冲突

bash

# 使用时间戳避免冲突
dotnet ef migrations add $(date +%Y%m%d%H%M%S)_AddFeature

Q4: 查看生成的 SQL

bash

# 方法 1: 生成脚本
dotnet ef migrations script

# 方法 2: 启用日志
# Program.cs
options.LogTo(Console.WriteLine, LogLevel.Information);

最佳实践

✅ 推荐做法

1. 使用描述性的迁移名称

bash

# ✅ 好
dotnet ef migrations add AddUserEmailAndPhone
dotnet ef migrations add CreateOrdersTable
dotnet ef migrations add MakeProductNameRequired

# ❌ 差
dotnet ef migrations add Update
dotnet ef migrations add Change
dotnet ef migrations add Fix

2. 定期审查迁移文件

bash

# 列出所有迁移
dotnet ef migrations list

# 查看最新迁移
ls -lt Migrations/ | head -1
cat Migrations/*_LatestMigration.cs

3. 生成幂等脚本用于生产

bash

# ✅ 推荐
dotnet ef migrations script --idempotent --output production.sql

# 脚本可以安全地多次执行

4. 版本控制迁移文件

bash

git add Migrations/
git commit -m "Add migration: CreateUsersTable"

❌ 避免的错误

1. 不要手动编辑迁移文件

bash

# ❌ 错误: 手动修改 Designer.cs
# ✅ 正确: 删除并重新创建
dotnet ef migrations remove
dotnet ef migrations add CorrectedMigration

2. 不要在团队中共享已应用的迁移

bash

# 如果迁移已被其他人应用,不要修改它
# 创建新的迁移来修正

3. 不要忘记提交迁移文件

bash

# ❌ 错误
git commit -m "Update entities"
# 忘记提交 Migrations/ 文件夹

# ✅ 正确
git add Migrations/
git commit -m "Add migration: UpdateEntities"

总结

常用命令速查表

任务	命令
创建迁移	`dotnet ef migrations add <Name>`
应用迁移	`dotnet ef database update`
删除迁移	`dotnet ef migrations remove`
列出迁移	`dotnet ef migrations list`
生成脚本	`dotnet ef migrations script`
删除数据库	`dotnet ef database drop`
脚手架	`dotnet ef dbcontext scaffold`
优化模型	`dotnet ef dbcontext optimize`

核心要点

CLI 是首选工具: 比 PMC 更跨平台
描述性命名: 迁移名称要清晰
幂等脚本: 生产部署必须使用
版本控制: 迁移文件必须纳入 Git
团队协作: 沟通迁移变更

.NET CLI 命令参考 ​

概述 ​

安装 EF Core CLI ​

迁移命令 ​

创建迁移 ​

应用迁移 ​

删除迁移 ​

列出迁移 ​

数据库命令 ​

生成 SQL 脚本 ​

删除数据库 ​

检查数据库状态 ​

DbContext 命令 ​

列出 DbContext ​

优化模型 ​

缩放模型 ​

脚手架命令 ​

从数据库生成代码 ​

参数说明 ​

通用选项 ​

项目选项 ​

verbosity 选项 ​

其他选项 ​

实际工作流示例 ​

新项目初始化 ​

开发迭代 ​

生产部署 ​

常见问题 ​

Q1: 找不到 dotnet-ef 命令 ​

Q2: 多项目方案报错 ​

Q3: 迁移文件名冲突 ​

Q4: 查看生成的 SQL ​

最佳实践 ​

✅ 推荐做法 ​

1. 使用描述性的迁移名称 ​

2. 定期审查迁移文件 ​

3. 生成幂等脚本用于生产 ​

4. 版本控制迁移文件 ​

❌ 避免的错误 ​

1. 不要手动编辑迁移文件 ​

2. 不要在团队中共享已应用的迁移 ​

3. 不要忘记提交迁移文件 ​

总结 ​

常用命令速查表 ​

核心要点 ​

.NET CLI 命令参考

概述

安装 EF Core CLI

迁移命令

创建迁移

应用迁移

删除迁移

列出迁移

数据库命令

生成 SQL 脚本

删除数据库

检查数据库状态

DbContext 命令

列出 DbContext

优化模型

缩放模型

脚手架命令

从数据库生成代码

参数说明

通用选项

项目选项

verbosity 选项

其他选项

实际工作流示例

新项目初始化

开发迭代

生产部署

常见问题

Q1: 找不到 dotnet-ef 命令

Q2: 多项目方案报错

Q3: 迁移文件名冲突

Q4: 查看生成的 SQL

最佳实践

✅ 推荐做法

1. 使用描述性的迁移名称

2. 定期审查迁移文件

3. 生成幂等脚本用于生产

4. 版本控制迁移文件

❌ 避免的错误

1. 不要手动编辑迁移文件

2. 不要在团队中共享已应用的迁移

3. 不要忘记提交迁移文件

总结

常用命令速查表

核心要点