.NET 10 到 .NET 11 迁移实战指南基于 migrate-dotnet10-to-dotnet11 技能的系统化升级路径【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills导读本文围绕当前仓库中migrate-dotnet10-to-dotnet11技能文档展开系统梳理将 .NET 10 项目迁移至 .NET 11net11.0的完整工作流从环境评估、Target Framework 更新到 C# 15 编译器源码级破坏性变更、运行时/核心库行为变更、EF Core 11 与 ASP.NET Core 11 专项适配再到 Docker 与 CI/CD 基础设施升级与最终验证。读完本文你将掌握一套可复用的迁移清单与每个破坏性变更的具体修复方案能够直接指导真实仓库完成迁移并保证构建与测试通过。注意.NET 11 目前处于预览阶段本文所述破坏性变更覆盖截至Preview 3的内容后续预览版本可能引入更多变更。技能定位这是一份「迁移技能」而非「新建项目指南」在 SKILL.md 的 frontmatter 中该技能被明确标注为MIGRATION skill适用场景When to Use将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 编译器引入的破坏性变更。不适用场景When Not to Use项目已目标net11.0且构建干净迁移已完成从 .NET 9 或更早版本升级需先处理 9→10 的破坏性变更从 .NET Framework 迁移属于另一项更大的工程直接以 .NET 11 起步的新项目无需迁移。核心原则迁移信息以技能自带的 reference 文档为权威来源do not fetch web pages or other external sources并通过「按逻辑边界提交」的提交策略更新 TFM 后、修复构建错误后、处理行为变更后、更新基础设施后各提交一次保证每个提交聚焦且可评审。输入参数输入是否必需说明项目或解决方案路径是待迁移的.csproj、.sln或.slnx入口点构建命令否构建方式如dotnet build或仓库构建脚本未提供时自动检测测试命令否测试运行方式如dotnet test未提供时自动检测项目类型提示否是否使用 ASP.NET Core、EF Core、Cosmos DB 等未提供时从 PackageReferences 与 SDK 属性自动检测六步迁移工作流Step 1项目评估Assess the project在动手修改任何文件之前先建立清晰的基线识别构建与测试方式查找构建脚本、.sln/.slnx文件或单个.csproj。确认 SDK 版本运行dotnet --version确认已安装 .NET 11 SDK若未安装立即停止并告知用户。判定技术领域通过以下线索快速定位可能受影响的模块SDK 属性Microsoft.NET.Sdk.Web→ ASP.NET CoreMicrosoft.NET.Sdk.WindowsDesktop且含UseWPF或UseWindowsForms→ WPF/WinFormsPackageReferencesMicrosoft.EntityFrameworkCore.*→ EF CoreMicrosoft.EntityFrameworkCore.Cosmos→ Cosmos DB providerDockerfile 存在→ 容器镜像变更相关加密 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 原生库→ 输出文件名lib前缀变化。记录相关 reference 文档加载对照表见 Step 3。先做一次干净构建dotnet build --no-incremental或删除bin/obj在当前的net10.0目标上建立干净的基线并记录所有既有警告便于与迁移后的输出对比。Step 2更新目标框架Update the Target Framework在每个.csproj若集中管理则在Directory.Build.props中修改!-- Before -- TargetFrameworknet10.0/TargetFramework !-- After -- TargetFrameworknet11.0/TargetFramework对于多目标项目在TargetFrameworks中添加net11.0或替换net10.0。将所有Microsoft.Extensions.*、Microsoft.AspNetCore.*、Microsoft.EntityFrameworkCore.*等微软包引用更新到11.0.x版本。若使用中央包管理Central Package ManagementDirectory.Packages.props则在此集中更新版本号。运行dotnet restore先解决所有还原错误再继续。运行dotnet build捕获全部错误与警告留待 Step 3 处理。Step 3修复源码级破坏与编译错误Fix source-breaking changes根据项目技术领域按需加载对应 reference 文档Reference 文件加载时机csharp-compiler-dotnet10to11.md总是加载C# 15 编译器破坏性变更core-libraries-dotnet10to11.md总是加载适用于所有 .NET 11 项目sdk-msbuild-dotnet10to11.md总是加载SDK 与构建工具变更aspnetcore-dotnet10to11.md项目使用 ASP.NET CoreOpenAPI、Blazorefcore-dotnet10to11.md项目使用 Entity Framework Corecryptography-dotnet10to11.md项目使用加密 API、mTLS或目标为 macOSruntime-jit-dotnet10to11.md部署到老旧硬件、嵌入式设备或使用 NativeAOTC# 15 编译器源码级破坏性变更随 .NET 11 SDK 发布的 Roslyn 编译器默认对所有net11.0项目启用 C# 15以下变更需要逐条排查1. Span 集合表达式 safe-context 改为declaration-block影响中集合表达式的SpanT/ReadOnlySpanT类型 safe-context 修正为declaration-block此前编译器错误地使用function-member。在内层作用域创建 span 集合表达式并赋给外层变量时会报错// 破坏——新错误 scoped Spanint items1 default; foreach (var x in new[] { 1, 2 }) { Spanint items [x]; if (x 1) items1 items; // error: safe-context is declaration-block } // 修复方案 1改用数组类型 foreach (var x in new[] { 1, 2 }) { int[] items [x]; if (x 1) items1 items; // ok通过 int[] 转换为 Spanint } // 修复方案 2将集合表达式移到外层作用域 Spanint items [0]; foreach (var x in new[] { 1, 2 }) { items[0] x; if (x 1) items1 items; // ok }2.ref readonly合成的委托与局部函数需要InAttribute影响低编译器为ref readonly返回的方法/λ 合成委托类型时现在会正确发出需要System.Runtime.InteropServices.InAttribute的元数据若该特性不可用则报 CS0518class RefHelper { private static int value 42; public void M() { // 若 InAttribute 不可用可能触发 CS0518 var methodDelegate this.MethodWithRefReadonlyReturn; var lambdaDelegate ref readonly int () ref value; } }局部函数同理ref readonly int local() ref x;也可能报 CS0518。修复方式相同——确保引用了定义InAttribute的程序集通常由默认运行时引用提供。3. 特性中的nameof(this.)被禁止影响低自 C# 12 起被「意外允许」的nameof(this.P)写法现在按语言规范被正式禁止// 修复去掉 this. 限定符 class C { string P; [System.Obsolete(nameof(P))] void M() { } }4. 集合表达式中的with()语义变化C# 15影响低当LangVersion≥ 15 时集合表达式元素中的with(...)被解释为构造器/工厂参数新的「collection expression arguments」特性而非调用名为with的方法object x, y, z ...; object[] items; items [with(x, y), z]; // C# 14调用 with() 方法C# 15报错 items [with(x, y), z]; // 修复转义为调用名为 with 的方法5.dynamic右操作数与接口左操作数的/||被禁止影响低接口类型作为/||左操作数、dynamic作为右操作数时编译器现在直接报错 CS7083此前编译通过但运行期抛RuntimeBinderExceptionvoid M() { I1 x new C1(); dynamic y new C1(); _ x y; // error CS7083 } // 修复将左操作数转换为具体类型或 dynamic _ (C1)x y; // valid _ (dynamic)x y; // valid6. switch 表达式臂中when的解析变化影响低(X.Y) when现在被解析为常量模式(X.Y)后接when子句此前被解析为将when强制转换为(X.Y)的转型表达式可能导致既有代码编译失败或语义变化需检查所有使用when的 switch 表达式并调整语法。7. 顺带了解C# 15 新增「collection expression arguments」特性非破坏性该特性正是导致上述with()变更的根源它允许在集合表达式首元素使用with(...)传构造参数Liststring names [with(capacity: values.Count * 2), .. values]; HashSetstring set [with(StringComparer.OrdinalIgnoreCase), Hello, HELLO];核心库与 SDK/MSBuild 的源码级变更8. SYSLIB0063NamedPipeClientStream的isConnected参数被弃用影响高对TreatWarningsAsErrors项目isConnected参数从未产生任何实际效果——从已有SafePipeHandle创建的管道总是已连接的。.NET 11 提供了不带该参数的新构造函数// .NET 10无警告编译 var pipe new NamedPipeClientStream(PipeDirection.InOut, isAsync: true, isConnected: true, safePipeHandle); // .NET 11SYSLIB0063 警告TreatWarningsAsErrors 时为错误 // 修复移除 isConnected 参数 var pipe new NamedPipeClientStream(PipeDirection.InOut, isAsync: true, safePipeHandle);9.Microsoft.OpenApi升级到 v3影响中Microsoft.AspNetCore.OpenApi的依赖从Microsoft.OpenApi2.x 升级到 3.x带来 OpenAPI 3.2.0 文档生成能力但 v2→v3 存在破坏性 API 变更。直接使用OpenApiDocument、OpenApiSchema、OpenApiOperation等类型的代码会产生编译错误。若仅使用 ASP.NET Core OpenAPI 集成.WithOpenApi()、MapOpenApi()而不直接操作对象模型则无需改动。10. EF Core Design 包不再传递依赖影响低Microsoft.EntityFrameworkCore.Tools与.Tasks不再传递依赖.Design依赖该传递引用的项目需显式添加PackageReference IncludeMicrosoft.EntityFrameworkCore.Design Version11.0.0 PrivateAssetsall /11.EFOptimizeContextMSBuild 属性移除影响低EFOptimizeContexttrue/EFOptimizeContext不再存在代码生成改由EFScaffoldModelStage与EFPrecompileQueriesStage控制当PublishAOTtrue时发布阶段自动生成。12. 其他 SDK 级行为变更影响低PackAsTooltrue搭配自定义NuspecFile时产生新警告NETSDK1235TreatWarningsAsErrors项目会失败需移除自定义NuspecFile或确认.nuspec兼容后压制警告dotnet publish --self-contained现在会正确解析传入值如--self-contained false真正产生框架依赖发布需复查构建脚本中的传值是否符合预期。Step 4处理运行时行为变更Address behavioral changes这些变更可以正常编译但会改变运行期行为需逐项评估影响1. DeflateStream/GZipStream 空负载写出头/尾影响中即使未写入任何数据DeflateStream与GZipStream现在也会输出合法的格式头/尾此前空负载产生 0 字节输出// .NET 10输出流为空0 字节 // .NET 11输出流包含合法头/尾 using var ms new MemoryStream(); using (var gz new GZipStream(ms, CompressionMode.Compress, leaveOpen: true)) { // 什么也不写 } // ms.Length 在 .NET 10 为 0在 .NET 11 大于 0修复若代码通过「输出是否为空」判断「没有数据被压缩」应改判未压缩字节数或调整长度检查以计入头/尾。2. MemoryStream 最大容量更新与异常行为变化影响中——复查创建超大 MemoryStream 或依赖特定容量异常类型的代码。3. TAR 头部校验和验证影响中——TAR 读取 API 现在校验头部校验和损坏或手工构造的 TAR 文件可能读取失败需为校验和失败增加错误处理using var reader new TarReader(stream); var entry reader.GetNextEntry(); // 损坏文件可能抛异常4.ZipArchive.CreateAsync改为急切加载影响低——条目由惰性加载改为急切加载超大归档的内存占用可能上升。5.Environment.TickCount与 Windows 超时行为一致影响低——依赖特定回绕/比较模式的代码可能需要调整。6. macOS 移除 DSA影响中仅 macOS——DSA 签名/验证在 macOS 上抛异常建议迁移至 ECDSA推荐、RSA 或 Ed25519Windows/Linux 上 DSA 仍可用但属遗留算法// .NET 11 的 macOS 上破坏 using var dsa DSA.Create(); var signature dsa.SignData(data, HashAlgorithmName.SHA256); // 修复改用其他算法 using var ecdsa ECDsa.Create(); var signature ecdsa.SignData(data, HashAlgorithmName.SHA256);7. 日本历法最小支持日期修正影响低——使用极早期日本历法日期的代码可能受影响。8. 最低硬件要求更新影响对老旧硬件部署为高——详见下文「硬件基线」小节。9. .NET Framework 应用不再自动设置 Mono 启动目标影响低——在 Linux 上通过 Mono 运行 .NET Framework 应用需显式指定。10.BackgroundService未处理异常将终止宿主影响中Preview 3——ExecuteAsync()抛出的未处理异常现在向上传播并停止宿主此前被静默吞掉// .NET 10异常被静默吞掉宿主继续运行 // .NET 11异常传播宿主停止 protected override async Task ExecuteAsync(CancellationToken stoppingToken) { throw new InvalidOperationException(oops); // 现在会杀死宿主 } // 修复为不应因失败而崩溃宿主的后台服务添加异常处理 protected override async Task ExecuteAsync(CancellationToken stoppingToken) { try { // ... 工作内容 ... } catch (Exception ex) when (ex is not OperationCanceledException) { _logger.LogError(ex, Background service failed); } }11. ZipArchive 读取时校验 CRC32影响低-中Preview 3——损坏或截断的 ZIP 归档此前被静默接受现在抛出InvalidDataException处理部分写入或遗留归档时需增加错误处理。12. TarWriter 为硬链接输出 HardLink 条目影响低Preview 3——归档目录中同一 inode 多次出现时现在写入指向首次出现的HardLink条目而非重复文件数据消费 .NET 产出 tar 归档的读取方需处理HardLink条目类型。13. AIA 证书下载默认禁用影响中Preview 3——服务端客户端证书链验证不再默认通过 AIA 在线下载中间 CA。使用 mTLS 且客户端证书依赖 AIA URL 获取中间 CA 的场景需在服务端预装完整证书链或让客户端发送包含中间 CA 的完整链或通过X509ChainPolicy.DisableCertificateDownloads false重新启用 AIA 下载。14. BlazorVirtualize默认OverscanCount从 3 改为 15影响低Preview 3——为支持可变高度条目测量VirtualizeTItem默认OverscanCount变为 15QuickGrid仍保持 3。性能敏感场景请显式设置Virtualize OverscanCount3 /。15.Microsoft.Data.SqlClient升级到 7.0Entra ID 认证分离影响中Preview 3——核心包移除了 Azure/Entra ID 认证依赖Azure.Core、Azure.Identity、Microsoft.Identity.Client。使用ActiveDirectoryDefault、ActiveDirectoryManagedIdentity等认证方式时需添加PackageReference IncludeMicrosoft.Data.SqlClient.Extensions.Azure Version7.0.0 /16.SqlVectorT默认排除出 SELECT影响低Preview 3——实体物化时向量属性返回null但仍可用于WHERE/ORDER BY向量搜索需用显式投影引入向量值.Select(b new { b.Id, b.Embedding })。17. SQLitePCLRaw 加密 bundle 移除影响中Preview 3——SQLitePCLRaw 3.0Microsoft.Data.Sqlite11 使用移除了bundle_e_sqlcipher等 bundle 包需改用 SQLite Encryption ExtensionSEE、Zetetic 的 SQLCipher 或SQLite3MultipleCiphers-NuGet。18. NativeAOT Unix 原生库输出带lib前缀影响低Preview 3——Linux/macOS 上的共享/原生库输出遵循 Unix 惯例增加lib前缀如libMyLib.so取代MyLib.so需同步更新构建脚本、部署流水线或按旧文件名引用的 P/Invoke 声明。专属领域补充EF Core 11 与运行时/硬件基线EF Core Cosmos 同步 I/O 完全移除影响中Preview 1——EF Core 10 中同步 I/O 默认不支持但可特殊 opt-inEF Core 11 中调用任何同步 I/O API 都总是抛异常且没有 opt-in 恢复旧行为。受影响的 API 包括ToList()、First()、Single()、Count()等同步 LINQ 运算符与SaveChanges()。原因是同步阻塞异步方法sync-over-async会导致死锁与性能问题而 Cosmos SDK 仅支持异步// EF Core 11 中破坏——总是抛异常 var items context.Items.ToList(); context.SaveChanges(); // 修复改用异步等价物 var items await context.Items.ToListAsync(); await context.SaveChangesAsync();完整映射ToList()→ToListAsync()、First()→FirstAsync()、Single()→SingleAsync()、Count()→CountAsync()、SaveChanges()→SaveChangesAsync()、Any()→AnyAsync()。同时注意方法需返回TaskT且调用方需改为await。此外Preview 1Cosmos 拥有的空集合现在返回空集合而非null需将if (entity.Items is null)改为if (entity.Items.Count 0)Preview 3程序集中无迁移时调用Migrate()/MigrateAsync()默认抛异常而非静默记录可用options.ConfigureWarnings(w w.Ignore(RelationalEventId.MigrationsNotFound))压制。最低硬件要求影响对老旧硬件部署为高——.NET 11 更新了 x86/x64 与 Arm64 的最低硬件基线x86/x64JIT/AOT 最低要求从x86-64-v1提升到x86-64-v2新增要求CX16、POPCNT、SSE3、SSSE3、SSE4.1、SSE4.2Windows/Linux 的 ReadyToRunR2R目标提升到x86-64-v3新增AVX、AVX2、BMI1、BMI2、F16C、FMA、LZCNT、MOVBE达不到 R2R 目标的硬件启动时会有额外 JIT 开销。Arm64Windows 基线提升为要求LSELoad-Store ExclusiveR2R 目标更新为armv8.2-a RCPCLinux 最低硬件不变仍支持 Raspberry PiR2R 目标更新为armv8.0-a LSEApple 无变化。从 .NET 11 起在老旧硬件上运行会直接失败并打印The current CPU is missing one or more of the baseline instruction sets.修复验证所有部署目标满足新要求——x86/x64 上约 2013 年及之后的 CPU 均可Windows Arm64 需确认 LSE 支持所有兼容 Windows 11 的 Arm64 设备均可。上述硬件最低要求的完整对照表各 OS 的 JIT/AOT 最低要求与 R2R 目标见 runtime-jit-dotnet10to11.md。Step 5更新基础设施Update infrastructure1. Dockerfile将基础镜像从 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.02. 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-v2Windows Arm64 为LSE。Step 6验证Verify完整干净构建dotnet build --no-incremental运行全部测试dotnet test若应用容器化构建并测试容器镜像冒烟测试重点检查空流的压缩行为TAR 文件读取校验和验证与 HardLink 条目EF Core Cosmos DB 操作必须异步macOS 上的 DSA 使用高内存占用的 MemoryStream 使用Span 集合表达式赋值BackgroundService 异常处理mTLS / 客户端证书链验证EF Core SQL Server 搭配 Entra ID 认证Unix 上 NativeAOT 输出文件名。复查 diff确保没有引入非预期的行为变更。Reference 文档体系references/目录按技术领域组织破坏性变更详情迁移时只加载与项目相关的 referenceReference 文件加载时机csharp-compiler-dotnet10to11.md总是加载C# 15 编译器破坏性变更core-libraries-dotnet10to11.md总是加载适用于所有 .NET 11 项目sdk-msbuild-dotnet10to11.md总是加载SDK 与构建工具变更aspnetcore-dotnet10to11.md项目使用 ASP.NET CoreOpenAPI、Blazorefcore-dotnet10to11.md项目使用 Entity Framework Corecryptography-dotnet10to11.md项目使用加密 API、mTLS或目标为 macOSruntime-jit-dotnet10to11.md部署到老旧硬件、嵌入式设备或使用 NativeAOT仓库内的验证样例本技能在仓库中配有对应的评测用例 tests/dotnet-upgrade/migrate-dotnet10-to-dotnet11/eval.yaml其中覆盖了典型的迁移场景可作为理解各变更落点的实战参考控制台应用 压缩/TARGZipStream空负载写出头/尾、TAR 校验和验证、ZipArchive.CreateAsync急切加载、MemoryStream 容量上限C# 15 编译器变更Span safe-context、nameof(this.)、with()集合表达式元素EF Core Cosmos 同步 API确认同步 I/O 完全移除且无 opt-in老旧硬件部署x86-64-v2基线导致 2012 年硬件启动失败、Raspberry Pi 4Arm64 Linux仍受支持、Surface Pro XSQ1满足 LSEmacOS DSA运行时DSA.Create()失败改用 ECDSA/RSATFM Docker global.json 基础更新dynamic运算符与ref readonly委托CS7083 与 CS0518BackgroundService 异常与 ZipArchive CRC32EF Core SQL Server Entra ID 认证与 Design 依赖ASP.NET Core OpenAPI 定制与 Blazor VirtualizemTLS 与 AIA 证书链验证。将这些场景与上文各 Step 一一对应即可在真实迁移中快速定位每个编译错误与运行期异常属于哪类破坏性变更并套用对应的修复模式。整体遵循「按逻辑边界提交」的策略确保 .NET 10 → .NET 11 的升级过程可控、可评审、可回退。【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考