migrate-dotnet10-to-dotnet11

.NET 10 → .NET 11 迁移

将 .NET 10 项目或解决方案迁移到 .NET 11，并系统地解决所有重大变更。最终项目将以 net11.0 为目标框架，能够顺利构建、通过测试，并涵盖 .NET 11 引入的所有行为变更、源代码不兼容变更和二进制不兼容变更。

注意： .NET 11 目前处于预览阶段。本技能涵盖截至 Preview 3 文档中记录的重大变更。

适用场景

• 将 TargetFramework 从 net10.0 升级到 net11.0
• 更新 .NET 11 SDK 后解决构建错误或新增警告
• 适配 .NET 11 运行时、ASP.NET Core 11 或 EF Core 11 的行为变更
• 更新 .NET 11 的 CI/CD 管道、Dockerfile 或部署脚本
• SDK 升级后修复 C# 15 编译器的重大变更

不适用场景

• 项目已以 net11.0 为目标框架且构建顺利——迁移已完成
• 从 .NET 9 或更早版本升级——请先处理 .NET 9→10 的重大变更
• 从 .NET Framework 迁移——这是另一项规模更大的工作
• 从头开始创建并以 .NET 11 为目标框架的项目（无需迁移）

输入

输入	必需	说明
项目或解决方案路径	是	要迁移的 .csproj、.sln 或 .slnx 入口文件
构建命令	否	构建方式（例如 dotnet build、仓库构建脚本）。未提供时自动检测
测试命令	否	测试运行方式（例如 dotnet test）。未提供时自动检测
项目类型提示	否	项目是否使用 ASP.NET Core、EF Core、Cosmos DB 等。未提供时根据 PackageReferences 和 SDK 属性自动检测

工作流

有关 .NET 11 重大变更的信息，请直接依据已加载的参考文档作答。 可按需检查本地仓库（项目/解决方案文件、源代码、配置、构建/测试脚本），以确定适用哪些变更。请勿从网页或其他外部来源获取重大变更信息——已加载的参考资料是权威来源。重点在于确定适用的重大变更并提供具体修复方案。

提交策略： 在每个逻辑边界处提交——更新 TFM 后（步骤 2）、解决构建错误后（步骤 3）、处理行为变更后（步骤 4）以及更新基础设施后（步骤 5）。这样可以让每次提交的范围清晰，便于审查。

步骤 1：评估项目

1. 确定项目的构建和测试方式。查找构建脚本、.sln/.slnx 文件或单个 .csproj 文件。
2. 运行 dotnet --version，确认已安装 .NET 11 SDK。如果未安装，请停止并告知用户。
3. 检查以下内容，确定项目使用的技术领域：
   • SDK 属性：Microsoft.NET.Sdk.Web → ASP.NET Core；带有 <UseWPF> 或 <UseWindowsForms> 的 Microsoft.NET.Sdk.WindowsDesktop → WPF/WinForms
   • PackageReferences：Microsoft.EntityFrameworkCore.* → EF Core；Microsoft.EntityFrameworkCore.Cosmos → Cosmos DB 提供程序
   • 是否存在 Dockerfile → 可能需要进行容器相关更改
   • 是否使用加密 API → macOS 上的 DSA 受影响；AIA 证书下载相关更改可能适用
   • 是否使用压缩 API → DeflateStream/GZipStream/ZipArchive 相关更改可能适用
   • 是否使用 TAR API → 标头校验和验证及 HardLink 条目相关更改可能适用
   • 是否将 NamedPipeClientStream 与 SafePipeHandle 搭配使用 → SYSLIB0063 构造函数过时相关更改可能适用
   • 是否使用 BackgroundService → 未处理的异常现在会导致主机停止
   • 是否直接使用 Microsoft.OpenApi → ASP.NET Core OpenAPI 中 v3 API 的破坏性更改可能适用
   • EF Core SQL Server 是否使用 Entra ID 身份验证 → SqlClient 7.0 身份验证依赖项相关更改可能适用
   • Unix 上是否存在 NativeAOT 原生库 → 输出文件名前缀已更改
4. 记录哪些参考文档适用（参见步骤 3 中的参考文档加载表）。
5. 在当前 net10.0 目标框架上执行一次干净构建（运行 dotnet build --no-incremental 或删除 bin/obj），以建立干净的基线。记录所有已有警告。

步骤 2：更新目标框架

1. 在每个 .csproj 文件中（或在集中管理的 Directory.Build.props 中），将以下内容更改为：

   <TargetFramework>net10.0</TargetFramework>
   

   改为：

   <TargetFramework>net11.0</TargetFramework>
   

   对于多目标项目，将 net11.0 添加到 <TargetFrameworks> 中，或替换 net10.0。

2. 将所有 Microsoft.Extensions.*、Microsoft.AspNetCore.*、Microsoft.EntityFrameworkCore.* 及其他 Microsoft 包引用更新到 11.0.x 版本。如果使用集中式包管理（Directory.Packages.props），请在该文件中更新版本。

3. 运行 dotnet restore。继续之前，先修复所有还原错误。

4. 运行 dotnet build。记录所有错误和警告，以便在步骤 3 中处理。

步骤 3：修复源代码兼容性和编译变更

根据项目的技术领域加载参考文档：

参考文件	加载时机
references/csharp-compiler-dotnet10to11.md	始终加载（C# 15 编译器重大变更）
references/core-libraries-dotnet10to11.md	始终加载（适用于所有 .NET 11 项目）
references/sdk-msbuild-dotnet10to11.md	始终加载（SDK 和构建工具变更）
references/aspnetcore-dotnet10to11.md	项目使用 ASP.NET Core（OpenAPI、Blazor）
references/efcore-dotnet10to11.md	项目使用 Entity Framework Core
references/cryptography-dotnet10to11.md	项目使用加密 API、mTLS，或以 macOS 为目标
references/runtime-jit-dotnet10to11.md	部署到较旧硬件或嵌入式设备，或使用 NativeAOT

系统地逐一处理每个构建错误。常见模式：

1. C# 15 Span 集合表达式的安全上下文 — Span<T>/ReadOnlySpan<T> 类型的集合表达式现在具有 declaration-block 安全上下文。将 Span 集合表达式赋值给外层作用域中的变量会导致错误。请改用数组类型，或将表达式移到正确的作用域中。

2. ref readonly 委托/局部函数需要 InAttribute — 如果从返回 ref readonly 的方法合成委托，或使用 ref readonly 局部函数，请确保 System.Runtime.InteropServices.InAttribute 可用。

3. 特性中的 nameof(this.) — 移除 this. 限定符；使用 nameof(P)，而不是 nameof(this.P)。

4. 集合表达式中的 with()（C# 15） — with(...) 现在会被视为构造函数参数，而非方法调用。若要调用名为 with 的方法，请使用 @with(...)。

5. 左操作数为接口的动态 &&/|| — 当 &&/|| 的左操作数为接口类型，右操作数为 dynamic 时，现在会在编译时出错。请转换为具体类型或 dynamic。

6. 移除 EF Core Cosmos 同步 I/O — Cosmos 提供程序上的 ToList()、SaveChanges() 等方法始终会抛出异常。请改用对应的异步方法。

7. SYSLIB0063：NamedPipeClientStream 的 isConnected 参数已弃用 — 接受 bool isConnected 的构造函数重载已弃用。请移除 isConnected 参数，并使用新的 3 参数构造函数。将 TreatWarningsAsErrors 设为 true 的项目将无法构建。

8. when switch 表达式分支解析 — (X.Y) when 现在会被解析为带有 when 子句的常量模式，而非强制转换表达式，这可能导致现有代码编译失败或含义改变。请检查使用 when 的 switch 表达式，并根据需要调整语法。

9. Microsoft.OpenApi v3 重大变更 — Microsoft.AspNetCore.OpenApi 现在依赖 Microsoft.OpenApi 3.x。直接使用 Microsoft.OpenApi 类型（OpenApiDocument、OpenApiSchema 等）的代码会出现编译错误。请参阅 v3 升级指南。

10. EF Core Design 包不再是传递依赖 — Microsoft.EntityFrameworkCore.Tools 和 .Tasks 不再依赖 .Design。如有需要，请显式添加 PackageReference。

11. 已移除 EFOptimizeContext MSBuild 属性 — 请替换为 <EFScaffoldModelStage> 和 <EFPrecompileQueriesStage>。

第 4 步：处理行为变化

这些更改可以成功编译，但会改变运行时行为。请逐项检查并确定其影响：

1. DeflateStream/GZipStream 空负载 — 现在即使负载为空，也会写入标头和页脚。如果代码会检查输出是否为零长度，请更新检查逻辑。

2. MemoryStream 最大容量 — 最大容量已更新，异常行为也发生了变化。请检查创建大型 MemoryStream 或依赖特定异常类型的代码。

3. TAR 标头校验和验证 — TAR 读取 API 现在会验证校验和。损坏或手工构造的 TAR 文件可能无法读取。

4. ZipArchive.CreateAsync 提前加载 — ZipArchive.CreateAsync 会提前加载条目。对于大型存档，这可能会影响内存使用量。

5. Environment.TickCount 一致性 — 现在与 Windows 超时行为保持一致。依赖特定计数器行为的代码可能需要调整。

6. macOS 已移除 DSA — 在 macOS 上执行 DSA 加密操作会抛出异常。请改用其他算法（RSA、ECDSA）。

7. Japanese Calendar 最小日期 — 已修正最小支持日期。使用非常早期 Japanese Calendar 日期的代码可能会受到影响。

8. 最低硬件要求 — x86/x64 基准已提升至 x86-64-v2；Windows Arm64 需要 LSE。请确认部署目标满足要求。

9. .NET Framework 的 Mono 启动目标 — 不再自动设置。如果在 Linux 上使用 Mono 运行 .NET Framework 应用，请明确指定。

10. 未处理的 BackgroundService 异常会停止主机 — ExecuteAsync() 引发的异常现在会向上传播并导致主机崩溃。对于不应导致应用程序停止的后台服务，请添加 try/catch。

11. ZipArchive CRC32 验证 — ZIP 读取现在会验证 CRC32 校验和。以前可以成功读取的损坏或截断存档现在会抛出 InvalidDataException。

12. TarWriter 会生成 HardLink 条目 — 现在，硬链接文件会写为 HardLink 条目，而不是重复数据。读取 .NET 生成的 tar 存档时，使用方必须处理 HardLink 条目。

13. 已禁用 AIA 证书下载 — 默认情况下，服务器端客户端证书验证不再通过 AIA 下载中间 CA。请预先安装完整证书链，或让客户端发送中间证书。

14. Blazor Virtualize 的 OverscanCount 默认值已更改 — 默认 OverscanCount 已从 3 更改为 15。如果性能敏感，请显式设置。

15. Microsoft.Data.SqlClient 7.0 — Entra ID 身份验证已分离 — 已从核心 SqlClient 包中移除 Azure/Entra ID 身份验证依赖项。如果使用 Entra ID 身份验证，请添加 Microsoft.Data.SqlClient.Extensions.Azure。

16. SELECT 不再包含 SqlVector<T> — 不再自动加载向量属性。请使用显式投影来包含向量值。

17. 已移除 SQLitePCLRaw 加密捆绑包 — SQLitePCLRaw 3.0 中已移除 bundle_e_sqlcipher 和其他加密捆绑包。

18. NativeAOT Unix 原生库的 lib 前缀 — Linux/macOS 上的输出文件名现在包含 lib 前缀（例如，libMyLib.so）。

第 5 步：更新基础设施

1. Dockerfiles：将基础映像从 10.0 更新为 11.0：

   # Before
   FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
   FROM mcr.microsoft.com/dotnet/aspnet:10.0
   # After
   FROM mcr.microsoft.com/dotnet/sdk:11.0 AS build
   FROM mcr.microsoft.com/dotnet/aspnet:11.0
   

2. CI/CD 管道：更新 SDK 版本引用。如果使用 global.json，请更新现有文件中的 sdk.version，同时保留其他键（例如 rollForward 和测试配置）：

    {
      "sdk": {
   -    "version": "10.0.100",
   -    "rollForward": "latestFeature"
   +    "version": "11.0.100-preview.3",
   +    "rollForward": "latestFeature"
      },
      "otherSettings": {
        "...": "..."
      }
    }
   

3. 硬件部署目标：确认所有部署目标均满足更新后的最低硬件要求（x86/x64 需要 x86-64-v2，Windows Arm64 需要 LSE）。

步骤 6：验证

1. 执行完整的干净构建：dotnet build --no-incremental
2. 运行所有测试：dotnet test
3. 如果应用已容器化，则构建并测试容器映像
4. 对应用进行冒烟测试，特别注意：
   • 空流的压缩行为
   • TAR 文件读取（校验和验证及 HardLink 条目）
   • EF Core Cosmos DB 操作（必须为异步）
   • 在 macOS 上使用 DSA
   • 占用大量内存的 MemoryStream 用法
   • Span 集合表达式赋值
   • BackgroundService 异常处理
   • mTLS / 客户端证书链验证
   • 使用 Entra ID 身份验证的 EF Core SQL Server
   • Unix 上的 NativeAOT 输出文件名
5. 检查差异，确保没有引入意外的行为更改

参考文档

references/ 文件夹包含按技术领域整理的详细破坏性更改信息。仅加载与待迁移项目相关的参考文档：

参考文件	加载时机
references/csharp-compiler-dotnet10to11.md	始终加载（C# 15 编译器破坏性更改）
references/core-libraries-dotnet10to11.md	始终加载（适用于所有 .NET 11 项目）
references/sdk-msbuild-dotnet10to11.md	始终加载（SDK 和构建工具更改）
references/aspnetcore-dotnet10to11.md	项目使用 ASP.NET Core（OpenAPI、Blazor）时
references/efcore-dotnet10to11.md	项目使用 Entity Framework Core 时
references/cryptography-dotnet10to11.md	项目使用加密 API、mTLS 或面向 macOS 时
references/runtime-jit-dotnet10to11.md	部署到较旧的硬件、嵌入式设备或使用 NativeAOT 时