.NET 9 升级到 .NET 10 迁移实战:dotnet-upgrade 技能下的破坏性变更处理指南

原创2026-09-17 16:22:571,699 阅读
文章标签:AI 技能AI 插件AI 评测模型评测人工智能开发工具

.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)

迁移的第一步不是改代码,而是摸清项目现状:

  1. 识别构建与测试方式:查找构建脚本、.sln / .slnx 文件或独立的 .csproj 文件;
  2. 确认 SDK 版本:运行 dotnet --version 确认 .NET 10 SDK 已安装;若未安装,立即停止并告知用户;
  3. 判断技术领域,依据以下信号逐项排查:
    • 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 多态使用 → 序列化变更相关;
  4. 记录需要加载哪些参考文档(对应 Step 3 的加载表);
  5. 建立干净基线:在当前的 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 变更:

  1. OpenApiString / OpenApiAny 类型移除——改用 System.Text.Json.Nodes.JsonNode:
// Before
parameter.Schema.Example = new OpenApiString("1.0");
// After
parameter.Schema.Example = JsonNode.Parse("\"1.0\"");
  1. OpenApiSecurityScheme.Reference 被替换——直接使用 OpenApiSecuritySchemeReference:
// Before
var scheme = new OpenApiSecurityScheme
{
    Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" }
};
// After
var scheme = new OpenApiSecuritySchemeReference("oauth2", null);
  1. 集合变为可空——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>();
  1. OpenApiSchema.Nullable 移除——OpenAPI 3.1 使用 JSON Schema 的 type: ["string", "null"] 而非 nullable: true,设置 .Nullable = false 的 schema 转换器可直接删除;
  2. 安全需求值要求 List<string>——从 string[] 的隐式转换可能失效:[oAuthScheme] = scopes.ToList();
  3. 部分位置使用接口类型——部分属性改用接口(如 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)

行为变更不会导致构建错误,但会改变运行时行为。逐一审查适用的变更,判断之前是否依赖了旧行为。

高影响行为变更(优先检查)

  1. 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));
  1. BackgroundService.ExecuteAsync 完全在后台线程运行——首个 await 之前的同步代码不再阻塞启动;若启动顺序重要,将代码移到 StartAsync 或构造函数,或实现 IHostedLifecycleService(StartingAsync 在 StartAsync 前、StartedAsync 在 StartAsync 后执行);
  2. 配置 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" 的约定一致);
  1. EF Core 参数化集合——集合上的 .Contains() 从 JSON/OPENJSON 翻译改为多个标量参数 WHERE x IN (@p1, @p2, @p3),大型集合可能影响查询性能。缓解:全局 UseParameterizedCollectionMode(ParameterTranslationMode.Parameter) 回退到 JSON 参数模式,或单查询用 EF.Parameter(ids).Contains(b.Id);
  2. 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)");
  3. 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)

  1. 完整干净构建:dotnet build --no-incremental;
  2. 运行全部测试:dotnet test;
  3. 容器化应用:构建并测试容器镜像;
  4. 冒烟测试,重点验证:
    • 信号处理 / 优雅停机行为;
    • 后台服务启动顺序;
    • 含 null 值的配置绑定;
    • Sqlite 的日期时间处理;
    • 多态类型的 JSON 序列化;
    • 集合上使用 .Contains() 的 EF Core 查询;
  5. 安全审查——确认迁移没有削弱安全控制:
    • SslStream API 迁移(SYSLIB0058)后保留 TLS 密码套件校验逻辑;
    • 含敏感数据的过时属性已从序列化中排除([XmlIgnore]、[JsonIgnore]);
    • 若 Uri 曾作为长度门槛,输入校验仍拒绝超大 URI;
    • 异常处理器在返回 true 前发出安全相关遥测(认证失败、访问违规)——当 IExceptionHandler.TryHandleAsync 返回 true 时,异常诊断中间件不再为该异常发出诊断事件,若被处理异常包含安全相关事件(认证失败、授权违规、注入尝试),抑制诊断会造成安全监控与审计盲区;
    • 连接字符串设置不泄露版本信息的显式 Application Name(EF Core 10 会向连接字符串注入包含 EF 与 SqlClient 版本信息的 Application Name,导致混合数据访问时的连接池分裂、TransactionScope 中的分布式事务升级,以及版本信息泄露——请显式设置);
    • dotnet restore 漏洞审计结果被处理而非压制;
  6. 审查 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 为目标、构建干净、测试通过、行为无回归的迁移成果。

登录后查看全文
skills