migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/migrate

What

概述

The single migration workflow for three change types, with EF Core schema migrations as the primary flow:

EF Core schema — review pending model changes, generate a descriptively named migration, review the SQL for data loss and locking risks, apply with a documented rollback path.
.NET version upgrade — phased TFM/SDK/package upgrade with verification at each phase.
NuGet updates — incremental, one-package-at-a-time updates so breakage is always attributable.

Shared principles: verify before applying, rollback plan always, test after every step, one logical change per migration.

这是适用于三种变更类型的统一迁移工作流，其中EF Core架构迁移为核心流程：

EF Core架构 —— 审核待处理的模型变更，生成具有描述性名称的迁移，检查SQL是否存在数据丢失和锁风险，并通过文档化的回滚路径应用变更。
.NET版本升级 —— 分阶段升级TFM/SDK/包，每个阶段均包含验证步骤。
NuGet更新 —— 采用增量式、逐个包更新的方式，确保任何故障都可追溯到具体包。

通用原则：应用前验证、始终制定回滚计划、每步操作后测试、每次迁移仅包含一个逻辑变更。

When

适用场景

After modifying entity classes, DbContext configuration, or relationships
"add migration", "update database", "create migration", "new table", "rename column"
When generating SQL scripts for DBA review
"upgrade to .NET 10", "version upgrade", ".NET upgrade"
"upgrade nuget", "update packages", "dependency update", vulnerable package alerts

修改实体类、DbContext配置或关系之后
执行"add migration"、"update database"、"create migration"、"new table"、"rename column"操作时
生成供DBA审核的SQL脚本时
执行"upgrade to .NET 10"、"version upgrade"、".NET upgrade"操作时
执行"upgrade nuget"、"update packages"、"dependency update"操作，或收到易受攻击包警报时

How

操作流程

First, classify the request: schema change → Flow A; framework upgrade → Flow B; package update → Flow C. Then follow that flow end to end.

首先对请求进行分类：架构变更 → 流程A；框架升级 → 流程B；包更新 → 流程C。然后全程遵循对应流程。

Flow A: EF Core Schema Migration (primary)

流程A：EF Core架构迁移（核心）

Step 1: Assess current state

bash

dotnet ef migrations list --project <InfraProject> --startup-project <ApiProject>

Check for pending migrations and uncaptured model changes.

Step 2: Review model changes

Use MCP tools instead of reading whole files:

find_symbol(name: entity or DbSet)        -- locate the changed entity
get_type_hierarchy(typeName: entity)      -- check TPH/TPT/TPC inheritance changes
find_references(symbolName: property)     -- assess downstream query impact

Confirm the change is one logical unit. If not, split into multiple migrations — mixed migrations make rollback all-or-nothing.

Step 3: Generate migration

Name describes the change, not the entity:

Add|Remove|Rename|Modify

WhatChanged

bash

undefined

步骤1：评估当前状态

bash

dotnet ef migrations list --project <InfraProject> --startup-project <ApiProject>

检查是否存在待执行的迁移和未捕获的模型变更。

步骤2：审核模型变更

使用MCP工具而非直接读取文件：

find_symbol(name: entity or DbSet)        -- 定位已变更的实体
get_type_hierarchy(typeName: entity)      -- 检查TPH/TPT/TPC继承变更
find_references(symbolName: property)     -- 评估下游查询影响

确认变更为单一逻辑单元。若不是，则拆分为多个迁移——混合迁移会导致回滚只能全量执行或完全无法回滚。

步骤3：生成迁移

迁移名称需描述变更内容而非实体：

Add|Remove|Rename|Modify

变更内容

。

bash

undefined

GOOD

规范示例

dotnet ef migrations add AddOrderShippingAddress --project <Infra> --startup-project <Api>

BAD — names the entity, not the change

不规范示例——仅命名实体，未描述变更

dotnet ef migrations add Order


**Step 4: Review generated SQL**

`database update` has no dry-run flag — preview by generating an idempotent
script and reading it:

```bash
dotnet ef migrations script --idempotent --project <Infra> --startup-project <Api>

Flag and report:

DROP COLUMN / DROP TABLE — confirm data loss is intentional
ALTER COLUMN type changes — check precision loss or truncation
ALTER on large tables — warn about lock duration
New non-nullable columns — need defaults for existing rows

If data must survive a rename/retype, use a multi-step migration with raw SQL:

csharp

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.AddColumn<string>("ContactEmail", "Customers", nullable: true);
    migrationBuilder.Sql("UPDATE \"Customers\" SET \"ContactEmail\" = \"Email\"");
    migrationBuilder.AlterColumn<string>("ContactEmail", "Customers", nullable: false);
    migrationBuilder.DropColumn("Email", "Customers");
}

Step 5: Apply and verify

bash

dotnet ef database update --project <Infra> --startup-project <Api>
dotnet build && dotnet test   # integration tests catch schema mismatches

Step 6: Document rollback

bash

dotnet ef database update <PreviousMigrationName> --project <Infra> --startup-project <Api>
dotnet ef migrations remove --project <Infra> --startup-project <Api>   # if unapplying from code

Never modify a migration that is already applied — create a new one.

dotnet ef migrations add Order


**步骤4：审核生成的SQL**

`database update`命令没有试运行标志——可通过生成幂等脚本来预览并审核：

```bash
dotnet ef migrations script --idempotent --project <Infra> --startup-project <Api>

标记并报告以下情况：

DROP COLUMN / DROP TABLE —— 确认数据丢失是有意操作
ALTER COLUMN类型变更——检查是否存在精度损失或截断问题
对大型表执行ALTER操作——警告锁持续时间
新增非空列——需为现有行设置默认值

若重命名/类型转换时需保留数据，可使用包含原始SQL的多步骤迁移：

csharp

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.AddColumn<string>("ContactEmail", "Customers", nullable: true);
    migrationBuilder.Sql("UPDATE \"Customers\" SET \"ContactEmail\" = \"Email\"");
    migrationBuilder.AlterColumn<string>("ContactEmail", "Customers", nullable: false);
    migrationBuilder.DropColumn("Email", "Customers");
}

步骤5：应用并验证

bash

dotnet ef database update --project <Infra> --startup-project <Api>
dotnet build && dotnet test   # 集成测试可捕获架构不匹配问题

步骤6：记录回滚流程

bash

dotnet ef database update <PreviousMigrationName> --project <Infra> --startup-project <Api>
dotnet ef migrations remove --project <Infra> --startup-project <Api>   # 若需从代码中撤销迁移

绝不要修改已应用的迁移——应创建新的迁移。

Flow B: .NET Version Upgrade

流程B：.NET版本升级

Assess —
```
get_project_graph
```
to list all TFMs; flag mixed versions.
Pre-flight — all tests green, no pending EF migrations, dependencies checked for target-version compatibility, dedicated branch created (branch IS the rollback plan).
Update
global.json
— SDK version with
```
"rollForward": "latestMinor"
```
.

Update TFMs —

<TargetFramework>net10.0</TargetFramework>

and

<LangVersion>14</LangVersion>

.csproj

Directory.Build.props

Update packages —

dotnet outdated --upgrade Major --include Microsoft.*

, then build and fix.

Adopt new features — per
```
knowledge/dotnet-whats-new.md
```
:
```
TimeProvider
```
,
```
HybridCache
```
, primary constructors, collection expressions.

Verify —

dotnet build

dotnet test

dotnet format --verify-no-changes

评估 —— 使用
```
get_project_graph
```
列出所有TFM；标记混合版本情况。
预检查 —— 所有测试通过，无待执行的EF迁移，检查依赖项与目标版本的兼容性，创建专用分支（分支本身就是回滚计划）。
更新
global.json
—— 设置SDK版本并配置
```
"rollForward": "latestMinor"
```
。

更新TFMs —— 在

.csproj

或

Directory.Build.props

中设置

<TargetFramework>net10.0</TargetFramework>

和

<LangVersion>14</LangVersion>

。

更新包 —— 执行
```
dotnet outdated --upgrade Major --include Microsoft.*
```
，然后构建并修复问题。
采用新特性 —— 根据
```
knowledge/dotnet-whats-new.md
```
文档：使用
```
TimeProvider
```
、
```
HybridCache
```
、主构造函数、集合表达式等。

验证 —— 执行

dotnet build

、

dotnet test

、

dotnet format --verify-no-changes

。

Flow C: NuGet Package Updates

流程C：NuGet包更新

Audit —
```
dotnet list package --outdated
```
and
```
dotnet list package --vulnerable
```
. Vulnerable packages are urgent: update, test, deploy.
Categorize — patch (batch-safe), minor (one at a time), major (one at a time, read release notes first).
Update incrementally — one package, then
```
dotnet build && dotnet test
```
before the next. Batched updates make failures unattributable.
Check fit — consult
```
knowledge/package-recommendations.md
```
before adding new packages; prefer built-in .NET alternatives. Moving off MediatR (commercial license from v13)? Follow the step-by-step guide in
```
knowledge/mediatr-to-mediator-migration.md
```
.
Rollback — git revert the package bump; never downgrade other packages to compensate.

审计 —— 执行
```
dotnet list package --outdated
```
和
```
dotnet list package --vulnerable
```
。易受攻击的包需优先处理：更新、测试、部署。
分类 —— 补丁版本（可批量更新）、次要版本（逐个更新）、主要版本（逐个更新，先阅读发布说明）。
增量更新 —— 更新一个包后，执行
```
dotnet build && dotnet test
```
，再进行下一个包的更新。批量更新会导致故障无法追溯。
适配检查 —— 添加新包前参考
```
knowledge/package-recommendations.md
```
文档；优先选择.NET内置替代方案。若要从MediatR（v13起为商业许可）迁移？请遵循
```
knowledge/mediatr-to-mediator-migration.md
```
中的分步指南。
回滚 —— 使用git撤销包版本升级；绝不要通过降级其他包来补偿问题。

MCP Tools Used

使用的MCP工具

```
find_symbol
```
/
```
find_references
```
— locate entities, assess schema-change impact
```
get_type_hierarchy
```
— entity inheritance for TPH/TPT/TPC
```
get_project_graph
```
— TFM audit before version upgrades
```
get_diagnostics
```
— catch warnings after migration generation or upgrades

```
find_symbol
```
/
```
find_references
```
—— 定位实体，评估架构变更影响
```
get_type_hierarchy
```
—— 检查实体的TPH/TPT/TPC继承关系
```
get_project_graph
```
—— 版本升级前审计TFM
```
get_diagnostics
```
—— 迁移生成或升级后捕获警告

Example

示例

User: /migrate

Claude: Checking migration state...
  Last applied: 20250710_AddOrderTable
  Model changes detected: new ShippingAddress property on Order entity.

  Creating migration: AddOrderShippingAddress
  Reviewing SQL (dotnet ef migrations script --idempotent)...
  - ALTER TABLE "Orders" ADD "ShippingStreet" text NULL
  - ALTER TABLE "Orders" ADD "ShippingCity" text NULL
  No data loss. No locking risk. Safe to apply.

  Applying migration... Done. Build: green. Tests: 34/34 passed.

  Rollback (if needed):
  dotnet ef database update AddOrderTable --project src/Infrastructure --startup-project src/Api

用户: /migrate

Claude: 正在检查迁移状态...
  最后已应用的迁移: 20250710_AddOrderTable
  检测到模型变更: Order实体新增ShippingAddress属性。

  创建迁移: AddOrderShippingAddress
  正在审核SQL（执行dotnet ef migrations script --idempotent）...
  - ALTER TABLE "Orders" ADD "ShippingStreet" text NULL
  - ALTER TABLE "Orders" ADD "ShippingCity" text NULL
  无数据丢失，无锁风险，可安全应用。

  正在应用迁移... 完成。构建: 成功。测试: 34/34通过。

  回滚步骤（如需）:
  dotnet ef database update AddOrderTable --project src/Infrastructure --startup-project src/Api

migrate

Original

Translation

/migrate

/migrate

What

概述

When

适用场景

How

操作流程

Flow A: EF Core Schema Migration (primary)

流程A：EF Core架构迁移（核心）

GOOD

规范示例

BAD — names the entity, not the change

不规范示例——仅命名实体，未描述变更

Flow B: .NET Version Upgrade

流程B：.NET版本升级

Flow C: NuGet Package Updates

流程C：NuGet包更新

MCP Tools Used

使用的MCP工具

Example

示例

Related

相关内容