.NET 9 升级到 .NET 10 迁移实战:dotnet-upgrade 技能下的破坏性变更处理指南
.NET 9 升级到 .NET 10 迁移实战:dotnet-upgrade 技能下的破坏性变更处理指南
本文以 migrate-dotnet9-to-dotnet10 技能 为核心骨架,系统讲解如何将一个 net9.0 项目或解决方案完整迁移到 net10.0。你将掌握一整套六步工作流:从项目评估、目标框架升级,到编译错误修复、行为变更排查、基础设施更新与安全审查,并深入理解 .NET 10 / C# 14 / ASP.NET Core 10 / EF Core 10 带来的源代码不兼容与二进制不兼容变更,能够真正把迁移做到"构建干净、测试通过、行为无回归"。
技能定位:何时使用、何时不用
该技能的目标非常明确:将 .NET 9 项目或解决方案升级到 .NET 10,并系统性地解决所有破坏性变更,最终交付一个目标为 net10.0、构建干净、测试通过、且覆盖 .NET 10 发布中每一项行为性、源代码不兼容性与二进制不兼容性变更的项目。
适用场景:
- 将
<TargetFramework>从net9.0升级到net10.0; - 更新 .NET 10 SDK 后解决新出现的构建错误或新警告;
- 适配 .NET 10 运行时、ASP.NET Core 10 或 EF Core 10 的行为变化;
- 更新 CI/CD 流水线、Dockerfile 或部署脚本以支持 .NET 10;
- 从社区版
System.Linq.Async包迁移到内置的System.Linq.AsyncEnumerable。
明确不适用(Do NOT Use For)的场景:
- 项目已经以
net10.0为目标且构建干净——迁移已完成; - 从 .NET 8 或更早版本升级——必须先使用 migrate-dotnet8-to-dotnet9 技能 先到达
net9.0,再回到本技能完成net9.0→net10.0的迁移; - 从 .NET Framework 迁移——那是一个独立的、更庞大的工程;
- 直接以 .NET 10 起步的新项目(无需迁移)。
输入参数方面,技能接受四个可选输入:项目或解决方案路径(必填,.csproj / .sln / .slnx 入口点)、构建命令(可选,如 dotnet build,未提供时自动探测)、测试命令(可选,如 dotnet test,未提供时自动探测)以及项目类型提示(可选,是否使用 ASP.NET Core、EF Core、WinForms、WPF、容器等,未提供时根据 PackageReferences 和 SDK 特性自动探测)。
迁移前的项目评估(Step 1)
迁移的第一步不是改代码,而是摸清项目现状:
- 识别构建与测试方式:查找构建脚本、
.sln/.slnx文件或独立的.csproj文件; - 确认 SDK 版本:运行
dotnet --version确认 .NET 10 SDK 已安装;若未安装,立即停止并告知用户; - 判断技术领域,依据以下信号逐项排查:
- SDK 特性:
Microsoft.NET.Sdk.Web→ ASP.NET Core;Microsoft.NET.Sdk.WindowsDesktop且带<UseWPF>或<UseWindowsForms>→ WPF / WinForms; - PackageReferences:
Microsoft.EntityFrameworkCore.*→ EF Core;Microsoft.Data.Sqlite→ Sqlite;Microsoft.Extensions.Hosting→ 泛型宿主 / BackgroundService; - Dockerfile 存在 → 容器变更相关;
- P/Invoke 或原生互操作 → 互操作变更相关;
System.Linq.Async包引用 → 需要 AsyncEnumerable 迁移;System.Text.Json多态使用 → 序列化变更相关;
- SDK 特性:
- 记录需要加载哪些参考文档(对应 Step 3 的加载表);
- 建立干净基线:在当前的
net9.0目标上执行一次干净构建(dotnet build --no-incremental或删除bin/obj),记录已有的警告,避免与升级产生的新警告混淆。
更新目标框架(Step 2)
修改 TargetFramework:在每个 .csproj(或集中管理的 Directory.Build.props)中:
<!-- Before -->
<TargetFramework>net9.0</TargetFramework>
<!-- After -->
<TargetFramework>net10.0</TargetFramework>
多目标项目在 <TargetFrameworks> 中追加 net10.0 或替换 net9.0。
同步升级 Microsoft 包版本:将所有 Microsoft.Extensions.*、Microsoft.AspNetCore.*、Microsoft.EntityFrameworkCore.* 等包引用升级到 10.0.x 版本;若使用集中包管理(Central Package Management,Directory.Packages.props),统一在此更新版本。
运行 dotnet restore 并关注三类问题:
- NU1510:NuGet 将直接引用剪枝(prune)——说明该包已被共享框架包含,此时应删除显式的
<PackageReference>; - 无版本号的 PackageReference 现在会报错——每个
<PackageReference>都必须有Version(或使用 CPM),不再隐式解析到最新版; - NuGet 传递依赖审计——
dotnet restore现在会审计传递依赖,需要审阅任何新增的漏洞警告。
随后执行干净构建,收集所有错误与新警告,进入 Step 3 处理。参考 SDK/MSBuild 参考文档 可看到这些行为背后的完整变更清单。
解决编译错误与源代码不兼容变更(Step 3)
根据项目类型加载对应参考文档,逐项处理编译错误与新警告。技能给出了明确的参考文档加载策略:
| 项目使用场景 | 加载参考文档 |
|---|---|
| 任意 .NET 10 项目 | csharp-compiler-dotnet9to10.md |
| 任意 .NET 10 项目 | core-libraries-dotnet9to10.md |
| 任意 .NET 10 项目 | sdk-msbuild-dotnet9to10.md |
| ASP.NET Core | aspnet-core-dotnet9to10.md |
| Entity Framework Core | efcore-dotnet9to10.md |
| 加密 API | cryptography-dotnet9to10.md |
| Generic Host / BackgroundService / 配置 | extensions-hosting-dotnet9to10.md |
| System.Text.Json / XmlSerializer / HttpClient / 网络 | serialization-networking-dotnet9to10.md |
| Windows Forms 或 WPF | winforms-wpf-dotnet9to10.md |
| Docker / 单文件 / 原生互操作 | containers-interop-dotnet9to10.md |
System.Linq.Async 与内置 AsyncEnumerable 的冲突
.NET 10 在核心库中加入了 System.Linq.AsyncEnumerable,为 IAsyncEnumerable<T> 提供完整 LINQ 支持,替代社区包 System.Linq.Async。引用该包的项目将出现歧义错误。修复方式:
- 删除
System.Linq.Async包引用,或升级到 v7.0.0; - 若是传递依赖,用
<ExcludeAssets>抑制:
<PackageReference Include="System.Linq.Async" Version="6.0.1">
<ExcludeAssets>compile</ExcludeAssets>
</PackageReference>
- 将
SelectAwait调用改名为新 API 使用的Select。
新弃用警告 SYSLIB0058–SYSLIB0062
.NET 10 引入了一批使用自定义诊断 ID 的弃用警告(抑制 CS0618 无法压制它们),逐一处理:
| 诊断 | 弃用内容 | 替代方案 |
|---|---|---|
| SYSLIB0058 | SslStream.KeyExchangeAlgorithm / CipherAlgorithm / HashAlgorithm 及强度属性 |
SslStream.NegotiatedCipherSuite。安全提示:若原代码用这些属性拒绝弱密码套件(如 RC4、3DES、NULL),必须用新 API 保留等价的校验逻辑 |
| SYSLIB0059 | SystemEvents.EventsThreadShutdown |
AppDomain.ProcessExit |
| SYSLIB0060 | Rfc2898DeriveBytes 构造函数 |
静态方法 Rfc2898DeriveBytes.Pbkdf2 |
| SYSLIB0061 | Queryable.MaxBy / MinBy 接受 IComparer<TSource> 的重载 |
接受 IComparer<TKey> 的新重载 |
| SYSLIB0062 | XsltSettings.EnableScript |
无(XSLT 脚本已被弃用) |
C# 14:属性访问器中的 field 上下文关键字
field 在属性的 get / set / init 访问器中成为上下文关键字(半自动属性特性)。产生两个诊断:
- CS9258(警告):
field绑定到合成的后备字段而非既有成员(例如类中名为field的字段),需用this.field或@field引用; - CS9272(错误):访问器内的局部变量或嵌套函数参数禁止命名为
field。
// BREAKS —— CS9272 错误
public object Property
{
get
{
int field = 0; // error: 'field' is a keyword in a property accessor
return @field;
}
}
// 同样 BREAKS —— CS9272 错误
public string Name
{
get
{
payload.TryGetProperty("field", out var field); // error: local named 'field'
return field.GetString();
}
}
修复选项:重命名变量(如 fieldValue、fieldElem);用 @field 转义(可编译但可读性差);类成员用 this.field 限定。
C# 14:extension 上下文关键字
自 C# 14 起 extension 是扩展容器的上下文关键字,名为 extension 的类型、构造函数、返回类型、别名与类型参数都会编译失败:
// C# 14 中 BREAKS
class extension { } // type cannot be named "extension"
using extension = SomeNamespace.Foo; // alias cannot be named "extension"
class C<extension> { } // type parameter cannot be named "extension"
修复:重命名,或转义为 @extension。另有两项低影响源码变更:lambda 参数中的 scoped 一律视为修饰符(ref struct 类型名为 scoped 时用 @scoped 转义);名为 partial 的类型不能作为返回类型(用 @partial 转义)。
C# 14:span 参数的重载解析
C# 14 引入了新的内置 span 转换与类型推断规则,导致不同重载被选中或产生新的歧义错误,常见受影响模式:
// 歧义 —— Assert.Equal<T>(T[], T[]) 与 Assert.Equal<T>(ReadOnlySpan<T>, Span<T>)
var x = new long[] { 1 };
Assert.Equal([2], x); // ambiguous
Assert.Equal([2], x.AsSpan()); // fix
// Enumerable.Reverse 现在解析为 MemoryExtensions.Reverse(原地、返回 void)
int[] arr = [1, 2, 3];
var reversed = arr.Reverse(); // BREAKS:解析到 Span 扩展而非 Enumerable
var reversed = Enumerable.Reverse(arr); // fix
// ReadOnlySpan 优先于 Span —— MemoryMarshal.Cast 可能失败
Span<ulong> y = MemoryMarshal.Cast<double, ulong>(x); // BREAKS
Span<ulong> y = MemoryMarshal.Cast<double, ulong>(x.AsSpan()); // fix
// 协变数组导致 ArrayTypeMismatchException
string[] s = ["a"];
object[] o = s;
C.R(o); // BREAKS at runtime:Span<T> ctor 抛出 ArrayTypeMismatchException
C.R(o.AsEnumerable()); // fix
修复选项:添加 .AsSpan() / .AsEnumerable() 或显式转换来消除歧义;显式调用静态方法(如 Enumerable.Reverse(arr));API 作者可使用 [OverloadResolutionPriority] 特性。特别要注意:表达式树内对数组调用 .Contains() 可能绑定到 MemoryExtensions.Contains 而不是 Enumerable.Contains,导致运行时异常,修复方式为:
// Fails —— 绑定到 MemoryExtensions.Contains
M((array, num) => array.Contains(num));
// Fix 选项:
M((array, num) => ((IEnumerable<int>)array).Contains(num));
M((array, num) => array.AsEnumerable().Contains(num));
M((array, num) => Enumerable.Contains(array, num));
C# 14 编译器行为变更
- 枚举器释放后状态置为 "after":
Dispose()后调用MoveNext()现在正确返回false且不再执行用户代码,此前状态机允许在释放后继续执行; await foreach报告模式化释放诊断:枚举器类型上过时的DisposeAsync方法现在会在await foreach中报告诊断,此前被静默忽略;or模式冗余警告:由于优先级导致第二个模式冗余时会告警,如o is not null or 42中的42是冗余的,应写为is not (null or 42)。
ASP.NET Core 10 的弃用与迁移
使用 Microsoft.NET.Sdk.Web 的项目需要处理一批弃用:
WebHostBuilder/IWebHost/WebHost弃用——迁移到现代宿主模型:
// Before (.NET 9)
var host = new WebHostBuilder()
.UseKestrel()
.UseStartup<Startup>()
.Build();
// After (.NET 10)
var builder = WebApplication.CreateBuilder(args);
// Configure services in builder.Services
var app = builder.Build();
// Configure middleware pipeline
app.Run();
若仍使用 Startup 类,WebApplication 模型可通过 builder.Host.ConfigureWebHostDefaults(...) 或内联配置支持;
IActionContextAccessor/ActionContextAccessor弃用——改为通过依赖注入或HttpContext访问ActionContext;WithOpenApi()扩展方法弃用——改用 ASP.NET Core 10 内置的 OpenAPI 文档生成;<IncludeOpenAPIAnalyzers>属性弃用——从.csproj中移除,新 OpenAPI 基础设施已不再需要这些分析器;IPNetwork与ForwardedHeadersOptions.KnownNetworks弃用——改用运行时新类型System.Net.IPNetwork与新属性KnownIpNetworks:
// Before
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
KnownNetworks = { new IPNetwork(IPAddress.Parse("10.0.0.0"), 8) }
});
// After
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
KnownIpNetworks = { new System.Net.IPNetwork(IPAddress.Parse("10.0.0.0"), 8) }
});
- Razor 运行时编译弃用——
AddRazorRuntimeCompilation()弃用,Razor 视图与页面应预编译,开发期用热重载(dotnet watch); Microsoft.Extensions.ApiDescription.Client包弃用——改用内置的 OpenAPI 客户端生成工具。
Microsoft.OpenApi v2.x 破坏性 API 变更
Microsoft.AspNetCore.OpenApi 10.0 依赖 Microsoft.OpenApi v2.x,相比 v1.x 有大量破坏性 API 变更,使用转换器(transformer)自定义 OpenAPI 文档生成或直接操作 OpenAPI 模型的项目需要改代码。
命名空间变更——Microsoft.OpenApi.Models 与 Microsoft.OpenApi.Any 被彻底移除:原位于这两个命名空间的所有类型(OpenApiSchema、OpenApiParameter、OpenApiResponse、OpenApiSecurityScheme 等)都移到了根命名空间 Microsoft.OpenApi:
// Before (.NET 9 —— Microsoft.OpenApi v1.x)
using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
// After (.NET 10 —— Microsoft.OpenApi v2.x)
using Microsoft.OpenApi; // ALL model types are here now
using System.Text.Json.Nodes; // replaces OpenApiAny types
关键 API 变更:
OpenApiString/OpenApiAny类型移除——改用System.Text.Json.Nodes.JsonNode:
// Before
parameter.Schema.Example = new OpenApiString("1.0");
// After
parameter.Schema.Example = JsonNode.Parse("\"1.0\"");
OpenApiSecurityScheme.Reference被替换——直接使用OpenApiSecuritySchemeReference:
// Before
var scheme = new OpenApiSecurityScheme
{
Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" }
};
// After
var scheme = new OpenApiSecuritySchemeReference("oauth2", null);
- 集合变为可空——
operation.Parameters、operation.Responses、document.Components.SecuritySchemes等集合属性可能为 null,必须判空或初始化:
operation.Responses ??= new OpenApiResponses();
operation.Parameters?.FirstOrDefault(p => p.Name == "api-version");
document.Components ??= new();
document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
OpenApiSchema.Nullable移除——OpenAPI 3.1 使用 JSON Schema 的type: ["string", "null"]而非nullable: true,设置.Nullable = false的 schema 转换器可直接删除;- 安全需求值要求
List<string>——从string[]的隐式转换可能失效:[oAuthScheme] = scopes.ToList(); - 部分位置使用接口类型——部分属性改用接口(如
IOpenApiSecurityScheme而非OpenApiSecurityScheme),转换器代码中需检查编译错误。
SDK 与 NuGet 变更
dotnet new sln默认生成 SLNX 格式(XML 的.slnx而非经典.sln),需旧格式时用dotnet new sln --format sln,并确保工具链(Visual Studio、Rider 等)支持 SLNX;- 文件级指令中的双引号被禁止:
#r、#load不再接受带双引号的路径,写为#r MyLib.dll而非#r "MyLib.dll"; dnx.ps1从 .NET SDK 中移除,删除相关引用;project.json不再被dotnet restore支持,改用 PackageReference 格式;- 无运行时资产的 NuGet 包被排除出
deps.json; dotnet package list/dotnet package search的 HTTP 源现在报错(改用 HTTPS);dotnet watch日志改输出到 stderr;--interactive在用户场景默认true,脚本中需显式--interactive false;- 默认工作负载管理模式改为 workload sets;
PrunePackageReference会私有化直接可剪枝引用(PrivateAssets="All");dotnet nuget sign弃用 SHA-1 指纹,改用 SHA-256;NUGET_ENABLE_ENHANCED_HTTP_RETRY环境变量被移除(增强重试始终开启)。
EF Core 10 源代码变更
ExecuteUpdateAsync现在接受普通 lambda——从Expression<Func<...>>改为Action<...>,动态构建表达式树的代码不再编译,但可大幅简化:
// Before (.NET 9) —— 为动态 setter 手工构建表达式树
Expression<Func<SetPropertyCalls<Blog>, SetPropertyCalls<Blog>>> setters =
s => s.SetProperty(b => b.Views, 8);
if (nameChanged)
{
var blogParameter = Expression.Parameter(typeof(Blog), "b");
setters = Expression.Lambda<Func<SetPropertyCalls<Blog>, SetPropertyCalls<Blog>>>(
Expression.Call(
instance: setters.Body,
methodName: nameof(SetPropertyCalls<Blog>.SetProperty),
typeArguments: [typeof(string)],
arguments:
[
Expression.Lambda<Func<Blog, string>>(
Expression.Property(blogParameter, nameof(Blog.Name)), blogParameter),
Expression.Constant("foo")
]),
setters.Parameters);
}
await context.Blogs.ExecuteUpdateAsync(setters);
// After (.NET 10) —— 带条件分支的简单 lambda
await context.Blogs.ExecuteUpdateAsync(s =>
{
s.SetProperty(b => b.Views, 8);
if (nameChanged)
{
s.SetProperty(b => b.Name, "foo");
}
});
IDiscriminatorPropertySetConvention签名变更——参数从IConventionEntityTypeBuilder改为IConventionTypeBaseBuilder,需更新自定义约定实现;IRelationalCommandDiagnosticsLogger方法增加logCommandText参数——如CommandReaderExecuting、CommandReaderExecuted等新增string logCommandText(脱敏 SQL,用于日志),需更新自定义实现;用command.CommandText获取实际执行 SQL,用logCommandText做日志记录;- 多目标项目运行 EF 工具必须指定框架:
dotnet ef migrations add MyMigration --framework net10.0,否则报 "The project targets multiple frameworks..." 错误; - 复杂类型列名唯一化:多个复杂类型含同名属性时列名追加数字后缀,可用
HasColumnName()显式配置;嵌套复杂类型列名使用全路径:EntityType.Complex.NestedComplex.Property映射为Complex_NestedComplex_Property(原为NestedComplex_Property),都会生成列重命名迁移。
WinForms / WPF 源代码变更
- 同时引用 WPF 和 WinForms 时必须消歧
MenuItem与ContextMenu:用全限定名System.Windows.Forms.MenuItem或System.Windows.Controls.MenuItem; HtmlElement.InsertAdjacentElement参数重命名:命名参数orientation:不再编译,改用位置参数;- WPF 空
ColumnDefinitions/RowDefinitions被禁止:XAML 中空的<Grid.ColumnDefinitions/>会报错,应删除; DynamicResource错误用法导致崩溃:错误使用(如应使用StaticResource的上下文、引用不存在的资源)从静默忽略变为运行时崩溃,需审计所有DynamicResource。
加密 API 变更
MLDsa/SlhDsa的SecretKey成员重命名为PrivateKey:ExportMLDsaSecretKey→ExportMLDsaPrivateKey、SecretKeySizeInBytes→PrivateKeySizeInBytes,SlhDsa同理;Rfc2898DeriveBytes构造函数弃用(SYSLIB0060):
// Before
using var deriveBytes = new Rfc2898DeriveBytes(password, salt, iterations, HashAlgorithmName.SHA256);
byte[] key = deriveBytes.GetBytes(32);
// After
byte[] key = Rfc2898DeriveBytes.Pbkdf2(password, salt, iterations, HashAlgorithmName.SHA256, 32);
CoseSigner.Key可空——使用前判空:signer.Key?.SignatureAlgorithm ?? throw new InvalidOperationException("Key is null");X509Certificate.GetKeyAlgorithmParameters()与PublicKey.EncodedParameters可返回 null,消费处需判空;- 环境变量从
CLR_OPENSSL_VERSION_OVERRIDE重命名为DOTNET_OPENSSL_VERSION_OVERRIDE。
每完成一批修复后重新构建,循环直至构建干净。
处理行为变更(Step 4)
行为变更不会导致构建错误,但会改变运行时行为。逐一审查适用的变更,判断之前是否依赖了旧行为。
高影响行为变更(优先检查)
- SIGTERM 信号处理移除——.NET 运行时不再注册默认的 SIGTERM/SIGHUP 处理器(Windows 上不再处理
CTRL_SHUTDOWN_EVENT/CTRL_CLOSE_EVENT),依赖 SIGTERM 触发AppDomain.ProcessExit或AssemblyLoadContext.Unloading的代码将失效:- ASP.NET Core 与泛型宿主应用不受影响(它们注册自己的处理器);
- 控制台应用与无泛型宿主的容器化应用必须显式注册:
using var sigterm = PosixSignalRegistration.Create(
PosixSignal.SIGTERM, _ => Environment.Exit(0));
using var sighup = PosixSignalRegistration.Create(
PosixSignal.SIGHUP, _ => Environment.Exit(0));
BackgroundService.ExecuteAsync完全在后台线程运行——首个await之前的同步代码不再阻塞启动;若启动顺序重要,将代码移到StartAsync或构造函数,或实现IHostedLifecycleService(StartingAsync在StartAsync前、StartedAsync在StartAsync后执行);- 配置 null 值被保留——JSON 的
null不再转换为空字符串;非默认值初始化的属性会被覆盖为null,需审查配置绑定代码:
| 场景 | .NET 9 行为 | .NET 10 行为 |
|---|---|---|
"StringProperty": null |
绑定为 ""(空字符串) |
绑定为 null(覆盖构造函数默认值) |
"IntProperty": null |
忽略(保留构造函数默认值) | 绑定为 null(若 int?) |
"Array": [null, null] |
绑定为 ["", ""] |
绑定为 [null, null] |
"Array": [] |
忽略(null) |
绑定为空数组 [] |
需要旧行为时:在 JSON 配置中用 "" 替换 null,或删除 null 条目跳过绑定;
4. Microsoft.Data.Sqlite 的 DateTimeOffset 变更(全部为高影响):
GetDateTimeOffset无偏移时假设 UTC(此前假设本地时区);- 向 REAL 列写入
DateTimeOffset前先转换为 UTC; GetDateTime带偏移时返回 UTC 且DateTimeKind.Utc(此前为Local);- 临时缓解:
AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", true)可回退到 .NET 9 行为,但仍应审查所有读写 SQLite 的日期时间代码(新行为与 SQLite "时间戳为 UTC" 的约定一致);
- EF Core 参数化集合——集合上的
.Contains()从 JSON/OPENJSON 翻译改为多个标量参数WHERE x IN (@p1, @p2, @p3),大型集合可能影响查询性能。缓解:全局UseParameterizedCollectionMode(ParameterTranslationMode.Parameter)回退到 JSON 参数模式,或单查询用EF.Parameter(ids).Contains(b.Id); - EF Core 在 Azure SQL 上的 json 数据类型——Azure SQL 或兼容级别 ≥170 时 JSON 列映射为
json而非nvarchar(max),会生成变更既有列的迁移。注意 SQL Server 不支持对 JSON 数组使用DISTINCT;缓解:UseAzureSql(connStr, o => o.UseCompatibilityLevel(160))或对属性显式HasColumnType("nvarchar(max)"); - System.Text.Json 属性名冲突校验——多态类型中与元数据名(
$type、$id、$ref或自定义TypeDiscriminatorPropertyName)冲突的属性在序列化时抛出InvalidOperationException(此前产生无效 JSON):
// 现在在序列化时抛出 InvalidOperationException
[JsonPolymorphic(TypeDiscriminatorPropertyName = "Type")]
[JsonDerivedType(typeof(Dog), "dog")]
public abstract class Animal
{
[JsonIgnore] // 修复:抑制冲突属性
public abstract string Type { get; }
}
其他需要审查的行为变更
BufferedStream.WriteByte不再隐式刷新——需要时显式调用Flush();- 默认分布式上下文传播器更新为 W3C 标准——依赖旧传播格式的系统需显式配置;
- 泛型数学中的移位行为保持一致——依赖旧不一致行为的自定义类型需更新;
DriveInfo.DriveFormat返回真实的 Linux 文件系统类型名(如ext4);GnuTarEntry/PaxTarEntry默认不再包含 atime/ctime——需要时显式设置;- LDAP
DirectoryControl解析更严格——无效数据现在抛出异常; - 单文件应用默认不再在可执行文件目录查找原生库——
DllImportSearchPath.AssemblyDirectory只搜索程序集目录; [DllImport("lib")]配合[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]不再能找到应用目录中的库,修复为DllImportSearchPath.System32 | DllImportSearchPath.AssemblyDirectory;- 将实现
IDispatchEx的 COM 对象转换为IReflect现在失败——改用dynamic或显式 COM 互操作接口; MailAddress强制校验连续点——user..name@example.com被拒绝;- 浏览器 HTTP 客户端默认启用流式响应;
Uri长度限制移除——若Uri曾被用作拒绝超长不可信输入的长度门槛,需添加显式长度校验(安全考量);- ASP.NET Core 对已知 API 端点禁用 Cookie 登录重定向——
[ApiController]端点、读写 JSON 的 minimal API、SignalR hub 与返回TypedResults的端点直接返回401,由IApiEndpointMetadata控制,可在特定端点手动添加或检查该元数据; XmlSerializer不再忽略[Obsolete]属性——审计含敏感数据(废弃密码字段、遗留 PII、内部值)的过时属性,用[XmlIgnore]防止意外暴露(安全考量);dotnet restore审计传递包;dotnet watch与 CLI 的非命令相关数据输出到 stderr;StatusStrip默认使用 System RenderMode(WinForms);TreeView复选框图片截断修复(WinForms);DynamicResource错误用法崩溃(WPF);[InlineArray]结构体不能再有显式[StructLayout(Size = ...)]——程序集无法加载;ActivitySource.CreateActivity/StartActivity采样行为变化;MacCatalyst 版本规范化不同(影响 .NET MAUI);FilePatternMatch.Stem变为非空string;Type.MakeGenericSignatureType参数校验更严格。
更新基础设施(Step 5)
Dockerfile 基础镜像切换
.NET 10 默认容器镜像标签从 Debian 切换为 Ubuntu 24.04(Noble Numbat),不再提供 Debian 镜像:
# Before
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
FROM mcr.microsoft.com/dotnet/aspnet:9.0
# After
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
FROM mcr.microsoft.com/dotnet/aspnet:10.0
需要检查:Dockerfile 中的 RUN apt-get 命令(Ubuntu 与 Debian 共享 apt 但包与版本可能不同)、Debian 特有的原生库依赖、假设 Debian 的自定义基础镜像层、引用 Debian 特定标签的 CI/CD 脚本。
CI/CD 与 global.json
更新 SDK 版本引用。若使用 global.json:
{
"sdk": {
"version": "10.0.100"
}
}
环境变量重命名
DOTNET_OPENSSL_VERSION_OVERRIDE取代旧名(Linux 上指定首选 OpenSSL 库版本);DOTNET_ICU_VERSION_OVERRIDE取代旧名(全球化相关);NUGET_ENABLE_ENHANCED_HTTP_RETRY已移除(增强重试始终开启)。
OpenSSL 要求
Unix 上现在要求 OpenSSL 1.1.1 或更高版本(可用 openssl version 检查);macOS 上不再支持 OpenSSL 加密原语,改用平台原生加密(Apple Security framework)。X500DistinguishedName 校验更严格,畸形名称可能抛异常;Composite ML-DSA 更新到 draft-08,早期草稿的密钥与签名格式不兼容。
解决方案文件格式
dotnet new sln 在脚本中现在生成 SLNX 格式,需要旧格式时传 --format sln。
验证与安全审查(Step 6)
- 完整干净构建:
dotnet build --no-incremental; - 运行全部测试:
dotnet test; - 容器化应用:构建并测试容器镜像;
- 冒烟测试,重点验证:
- 信号处理 / 优雅停机行为;
- 后台服务启动顺序;
- 含 null 值的配置绑定;
- Sqlite 的日期时间处理;
- 多态类型的 JSON 序列化;
- 集合上使用
.Contains()的 EF Core 查询;
- 安全审查——确认迁移没有削弱安全控制:
SslStreamAPI 迁移(SYSLIB0058)后保留 TLS 密码套件校验逻辑;- 含敏感数据的过时属性已从序列化中排除(
[XmlIgnore]、[JsonIgnore]); - 若
Uri曾作为长度门槛,输入校验仍拒绝超大 URI; - 异常处理器在返回
true前发出安全相关遥测(认证失败、访问违规)——当IExceptionHandler.TryHandleAsync返回true时,异常诊断中间件不再为该异常发出诊断事件,若被处理异常包含安全相关事件(认证失败、授权违规、注入尝试),抑制诊断会造成安全监控与审计盲区; - 连接字符串设置不泄露版本信息的显式
Application Name(EF Core 10 会向连接字符串注入包含 EF 与 SqlClient 版本信息的Application Name,导致混合数据访问时的连接池分裂、TransactionScope中的分布式事务升级,以及版本信息泄露——请显式设置); dotnet restore漏洞审计结果被处理而非压制;
- 审查 diff,确保没有引入非预期行为变更。
参考文档清单与测试佐证
该技能的 references/ 目录按技术领域组织了详细的破坏性变更信息,迁移时按需加载(完整表格见 SKILL.md):csharp-compiler-dotnet9to10.md(C# 14 编译器)、core-libraries-dotnet9to10.md(核心库)、sdk-msbuild-dotnet9to10.md(SDK/MSBuild)、aspnet-core-dotnet9to10.md、efcore-dotnet9to10.md、cryptography-dotnet9to10.md、extensions-hosting-dotnet9to10.md、serialization-networking-dotnet9to10.md、winforms-wpf-dotnet9to10.md、containers-interop-dotnet9to10.md。
本仓库还为此技能提供了 评估测试配置,包含 16 个覆盖上述全部主题的实测场景,可作为迁移自查清单使用:无泛型宿主的控制台应用(System.Linq.Async + SIGTERM + BufferedStream + 自定义传播器)eval.yaml#L7-L19、C# 14 span 重载导致表达式树运行时异常 eval.yaml#L39-L58、ASP.NET Core 旧宿主与 OpenAPI 转换器迁移 eval.yaml#L60-L165、EF Core 的 Azure SQL JSON 列与 ExecuteUpdateAsync eval.yaml#L166-L253、Sqlite 时区处理 eval.yaml#L254-L273、配置 null 绑定与 ProviderAliasAttribute 程序集迁移 eval.yaml#L274-L312、加密与 OpenSSL eval.yaml#L313-L343、SDK/NuGet 工具链变更 eval.yaml#L344-L393、JSON 多态冲突与 XmlSerializer eval.yaml#L394-L464、WinForms/WPF 桌面应用 eval.yaml#L465-L521、容器化单文件应用与 P/Invoke eval.yaml#L522-L593、SslStream 与 SystemEvents 弃用 eval.yaml#L594-L620、NU1510 与 InlineArray eval.yaml#L621-L644、C# 14 field / extension / 枚举器释放 eval.yaml#L645-L714,以及 Blazor WASM 的泛型数学移位、流式响应与 HTTP/3 裁剪 eval.yaml#L715-L767。
遵循"每个逻辑边界提交一次"的提交策略——更新 TFM 后(Step 2)、解决构建错误后(Step 3)、处理行为变更后(Step 4)、更新基础设施后(Step 5)各提交一次,让每个提交聚焦、可审查。最终交付的,是一个以 net10.0 为目标、构建干净、测试通过、行为无回归的迁移成果。