.NET 10 知识整理

本文以 .NET 10（LTS，2025-11-11 发布，支持至 2028-11-14） 为基准整理。写于 2026-11-11：此时 .NET 11（STS）刚于 11-10 发布，而 .NET 8、.NET 9 已在同日结束支持——生产环境的主力目标是 .NET 10，不是最新的 .NET 11。

定位：一份按目录检索的体系化速查笔记，不是入门教程，也不是 release notes 的翻译。默认读者写过 C# 和 ASP.NET Core，想把「版本、语言、运行时、库、框架、工具链、升级」这几层串成一张图。

姊妹篇：EF Core 知识整理 单独展开 ORM 那一层，本文第 7 节只做索引。

1. 版本坐标：先搞清楚自己在哪

1.1 发布节奏与支持策略

当前（2026-11-11）关键日期：

要点：「最新版」≠「该升级的版本」。企业应用跟 LTS 走，隔一个 LTS 升一次（8 → 10 → 12）是成本最低的路线；STS 适合能保持年度升级节奏的团队。另外官方要求在支持期内持续安装最新补丁，停留在旧补丁版本不符合支持条件。

1.2 版本号怎么读

global.json 钉住 SDK，避免 CI 与本机版本漂移：

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature"
  },
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}

注意 dnx 脚本会绕过 global.json 的 SDK 选择（官方列为 .NET 10 行为变更），在严格锁定版本的 CI 里别混用。

2. 平台组成与日常命令

.NET 10 不是「一个框架」，而是几层东西的合称：

平台特定的 TFM 别写错：

日常命令（.NET 10 新增名词优先写法，旧写法仍可用但脚本里建议统一）：

dotnet --info                         # 看清 SDK / 运行时 / RID
dotnet new webapi -n Api && cd Api
dotnet package add Serilog            # 旧：dotnet add package
dotnet package list --vulnerable --include-transitive
dotnet reference add ../Shared/Shared.csproj   # 旧：dotnet add reference
dotnet build -c Release
dotnet publish -c Release -o ./out
dotnet completions script zsh         # 原生补全脚本，支持 bash/fish/nushell/powershell/zsh
dotnet clean --cli-schema             # 输出命令树的 JSON，供脚本 / 工具集成

共享框架 vs NuGet 包：Microsoft.AspNetCore.App 是共享框架（随运行时，不写版本号）；Microsoft.EntityFrameworkCore.*、Microsoft.Extensions.* 独立发 NuGet 包。升级时前者跟运行时走，后者必须手动把整套 Microsoft.* 包升到 10.x 同一版本，混用大版本是典型故障源。

3. C# 14：语法层面的增量

C# 14 随 .NET 10 SDK 提供，只支持 net10.0（语言版本可单独设，但新特性依赖新 BCL 时不能降级）。

3.1 field 关键字：从自动属性平滑过渡到自定义访问器

public string Email
{
    get;
    set => field = value?.Trim().ToLowerInvariant() ?? string.Empty;
}

public SqlConnection Connection
{
    get => field ??= new SqlConnection("...");
}

不用再手写 backing field，也能只给其中一个访问器写 body。坑：类里若已有名为 field 的标识符会产生歧义，用 @field 或 this.field 区分，或改名。这是官方明确提示的潜在源码级 breaking change。

3.2 扩展成员（extension 块）

以前只能扩展实例方法，现在能扩展属性、静态成员、运算符：

public static class Enumerable
{
    extension<TSource>(IEnumerable<TSource> source)   // 实例扩展成员
    {
        public bool IsEmpty => !source.Any();
        public IEnumerable<TSource> Where(Func<TSource, bool> p) { /* ... */ }
    }

    extension<TSource>(IEnumerable<TSource>)          // 静态扩展成员
    {
        public static IEnumerable<TSource> Identity => Enumerable.Empty<TSource>();
        public static IEnumerable<TSource> operator +(
            IEnumerable<TSource> left, IEnumerable<TSource> right) => left.Concat(right);
    }
}

// 调用：sequence.IsEmpty / IEnumerable<int>.Identity

System.Numerics.Tensors 就用它给 Tensor<T> 提供了 tensor + tensor 这类运算（仅当 T 实现对应泛型数学接口时可用）。

3.3 其他特性速查

4. 运行时与 JIT：这一版的重心

.NET 10 运行时改进集中在「去抽象化（de-abstraction）」：把高层语法带来的虚调用、堆分配消除掉，让写得好懂的代码接近手写优化代码。

要点：这些基本都是免费的运行时升级收益，不用改代码。所以「升级到 .NET 10 后先跑一轮基准」比「手工把 foreach 改成 for」有意义得多。反过来，别为了微优化牺牲可读性去迎合 JIT 的旧限制——限制正在被逐版移除。

5. 基础库新增 API（按领域速查）

5.1 序列化：System.Text.Json

var strict = new JsonSerializerOptions
{
    Strict = true   // 组合：拒绝未映射成员、拒绝重复属性、区分大小写、
                    // RespectNullableAnnotations、RespectRequiredConstructorParameters
};

var opts = new JsonSerializerOptions { AllowDuplicateProperties = false };
// {"Value":1,"Value":-1} 在旧行为下结果为 -1；禁用重复属性后抛 JsonException

• JsonSerializerOptions.Strict 与 JsonSerializerOptions.Default 读兼容：默认选项序列化的内容，可以用 Strict 反序列化。
• 新增 PipeReader 重载：DeserializeAsync<T>(pipe.Reader)、DeserializeAsyncEnumerable<T>(pipe.Reader)、SerializeAsync(pipe.Writer, ...)，省掉 PipeReader → Stream 转换。ASP.NET Core 的 MVC / Minimal API 已在内部自动用上，应用无需改代码。
• source generator 支持 [JsonSourceGenerationOptions(ReferenceHandler = JsonKnownReferenceHandler.Preserve)] 处理循环引用。

5.2 后量子密码（PQC）

设计变化：这些类型不继承 AsymmetricAlgorithm，改用静态工厂（GenerateKey / ImportFromPem）与静态 IsSupported 属性。平台要求 OpenSSL 3.5+ 或带 PQC 支持的 Windows CNG（.NET 10 新增）。

MLDsa / SlhDsa / CompositeMLDsa 仍标记 [Experimental]（诊断 SYSLIB5006），标准与 OID 未最终定稿，短期别放进长期存档的签名格式。其他新增：Aes.DecryptKeyWrapPadded（AES-KWP / RFC 5649）、X509Certificate.ExportPkcs12 可选 Pbes2Aes256Sha256、X509Certificate2Collection.FindByThumbprint 支持非 SHA-1 摘要、PemEncoding.FindUtf8。

5.3 网络与全球化

• WebSocketStream：把 WebSocket 包成 Stream，WebSocketStream.Create(...) 用于流式协议，CreateReadableMessageStream / CreateWritableMessageStream 用于单条消息；Dispose() 自动完成关闭握手，省掉自己处理分帧、缓冲、编解码的胶水代码。
• macOS 客户端 TLS 1.3：opt-in，走 Apple Network.framework：

AppContext.SetSwitch("System.Net.Security.UseNetworkFramework", true);
// 或环境变量 DOTNET_SYSTEM_NET_SECURITY_USENETWORKFRAMEWORK=1

启用后 TLS 1.0/1.1 可能不可用，且缓冲、读写完成、取消语义与旧 Secure Transport 不同；官方特别提示别依赖零字节读判断数据是否就绪。

• CompareOptions.NumericOrdering："2" < "10"、"02" == "2"（数值比较）。不适用于 IndexOf / LastIndexOf / StartsWith / EndsWith / IsPrefix / IsSuffix 这类索引型操作。
• ISOWeek 新增 DateOnly 重载；TimeSpan.FromMilliseconds 新增单参数 long 重载，解决 LINQ 表达式树无法处理可选参数的问题（原双参数重载的第二参数改为必填）。

5.4 集合、ZIP、诊断

6. ASP.NET Core 10

升级集成测试时先跑一遍：302 → 401/403 的行为变化最容易让断言批量变红。

7. EF Core 10：只做索引

EF Core 10 随 .NET 10 发布，与运行时同生命周期，但需要 .NET 10 SDK 构建、.NET 10 运行时运行，不支持更早的 .NET 版本，也不支持 .NET Framework。

主要变化：LeftJoin / RightJoin 运算符、命名查询过滤器、复杂类型映射 JSON 并在 LINQ 中过滤、SQL Server 2025 / Azure SQL 矢量搜索、ExecuteUpdateAsync 支持普通 lambda、日志内联常量默认脱敏、集合参数化翻译改进（Contains 生成的 SQL 文本变化，会让 SQL Server 计划缓存失效）。

完整梳理见本站《EF Core 知识整理》；升级前务必看官方 EF Core 10 breaking changes 与 Provider 兼容性（第三方 Provider 未跟上时不能升级）。

8. SDK 与工具链：file-based apps 是最大变化

8.1 单文件 C# 应用

不用 .csproj，一个 .cs 文件即可构建、运行、发布：

#!/usr/bin/env -S dotnet --
#:sdk Microsoft.NET.Sdk.Web
#:package Spectre.Console@*
#:package Serilog@4.0.0
#:project ../Shared/Shared.csproj
#:property PublishAot=false
#:property TargetFramework=net10.0

using Spectre.Console;
AnsiConsole.MarkupLine("[green]Hello, .NET 10[/]");

命令：

dotnet run --file app.cs          # 最明确：当前目录有 .csproj 时也不会误跑项目
dotnet run app.cs                 # 简写；目录里有项目文件时会优先跑项目并把 app.cs 当参数
dotnet app.cs                     # shorthand
dotnet run app.cs -- arg1 arg2    # 应用参数放在 -- 之后
dotnet publish app.cs             # 默认 Native AOT，产物在同级 artifacts/ 下
dotnet project convert app.cs     # 转成 .csproj + .cs，原文件保持不变

shebang 用 #!/usr/bin/env -S dotnet --（-S 拆分参数，-- 防止 dotnet 吞掉应用参数）；文件需 LF 换行、无 BOM、chmod +x。发布默认开启 Native AOT，用到不兼容的反射/包时用 #:property PublishAot=false 关掉。

8.2 其他 SDK 变化

9. 部署形态怎么选

可观测性配套：ActivitySource / Meter 现在可带 telemetry schema URL；默认 trace context propagator 改为 W3C 标准（.NET 10 行为变更，跨系统链路追踪需核对）；dotnet-counters / dotnet-trace / OpenTelemetry 与 ASP.NET Core 新指标直接对接。

10. 从 .NET 8 / 9 升级：检查清单

按这个顺序做，别一上来就改 TFM：

1. 装 SDK：本机与 CI 都升到 .NET 10 SDK；更新 global.json、CI 的 actions/setup-dotnet / UseDotNet@2。
2. 改 TFM：<TargetFramework>net10.0</TargetFramework>，注意 Directory.Build.props 里常有集中定义。
3. 升包：把所有 Microsoft.AspNetCore.*（若显式引用）、Microsoft.EntityFrameworkCore.*、Microsoft.Extensions.* 一起升到 10.x；检查第三方 Provider / 库是否已有 .NET 10 版本。
4. 处理 NuGet 审计：net10.0+ 下 NuGetAuditMode 默认 all（旧为 direct），传递依赖漏洞也会报 NU1901–NU1904；TreatWarningsAsErrors 的项目会直接 restore 失败。用 dotnet nuget why <package> 定位依赖链，或用 <NuGetAuditSuppress Include="https://github.com/advisories/XXXX" /> 精确豁免，别全局关 NuGetAudit。
5. 消除新告警：PackageReference 不写版本现在报错；框架已提供的直接引用会触发 NU1510（删掉即可）。
6. 核对行为变化（编译器不会提醒，最容易漏）：

7. 验证：dotnet build -warnaserror 跑通 → 全量测试 → 基准对比（JIT 改进通常是白捡的性能）→ 检查生成的迁移 SQL 与 OpenAPI 文档 → 灰度发布观察 GC 暂停、启动时间、401/403 比例。
8. 最后更新部署：容器基础镜像、服务器 / PaaS 运行时栈、监控告警规则。

官方 Breaking changes in .NET 10 页面明确标注「work in progress, not a complete list」，升级前把 ASP.NET Core 10 / EF Core 10 各自的 breaking changes 页面一起看。

11. 反模式速查

12. 参考

• .NET 10 新增功能总览：https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/overview
• 运行时改进：https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/runtime
• 基础库新增 API：https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/libraries
• SDK 与 CLI 改进：https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/sdk
• file-based apps：https://learn.microsoft.com/dotnet/core/sdk/file-based-apps
• C# 14 新增功能：https://learn.microsoft.com/dotnet/csharp/whats-new/csharp-14
• ASP.NET Core 10 发行说明：https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-10.0
• .NET 10 中断性变更：https://learn.microsoft.com/dotnet/core/compatibility/10
• .NET 支持策略与生命周期：https://dotnet.microsoft.com/platform/support/policy/dotnet-core
• NuGet 安全审计与 NuGetAuditMode：https://learn.microsoft.com/nuget/concepts/auditing-packages
• EF Core 10 新增功能：https://learn.microsoft.com/ef/core/what-is-new/ef-core-10.0/whatsnew