升级到 .NET 10 时需要注意的重大变更

原创于 2025-12-22 09:17:20 发布 · 1.1k 阅读

7 ·

CC 4.0 BY-SA版权

文章标签：

#.net #.Net 10

.NET10 专栏收录该内容

2 篇文章

订阅专栏

IActionContextAccessor 和 ActionContextAccessor 已过时

IPNetwork 和 ForwardedHeadersOptions.KnownNetworks 已过时

Razor运行时编译已过时

WebHostBuilder、IWebHost 和 WebHost 已过时

默认的 .NET 容器镜像现在使用 Ubuntu

创建新实例时取消 URI 长度限制

X509证书和公钥参数可以为空

结论

变革之风正吹向 .NET 10，许多团队正在调整方向，准备迎接崭新而充满挑战的征程。激动人心的时刻即将到来。由于 .NET 10 标志着 SDK 和运行时的长期支持 (LTS) 版本正式发布，现在正是制定计划和策略的绝佳时机。毕竟，在升级过程中，我们的资源、开发人员的周期和精力都是有限的。您肯定不希望在升级过程中遭遇任何意想不到的波涛汹涌。

如果您喜欢此文章，请收藏、点赞、评论，谢谢，祝您快乐每一天。

在这篇文章中，Duende 仔细研究了目前已知的.NET 10 重大变更，并总结了一些升级时需要注意的事项。希望大部分变更都能顺利完成升级，但有些变更可能会让你感到束手无策，甚至陷入挫败感。接下来，我们将按顺序逐一介绍这些变更，并解释为什么你需要将它们标记在你的升级计划中。

ASP.NET Core 管道可配置以满足各种需求。许多 Duende 客户将 OAuth 保护的 API 端点与 ASP.NET Core MVC 或 Razor Pages UI 混合使用。因此，许多 .NET 开发人员都会注意到一个典型现象：他们的 API 端点意外触发了质询响应，试图将调用者重定向到 Duende IdentityServer 实例。大多数开发人员并不希望发生这种重定向行为。调用者可能希望看到验证401 Unauthorized或403 Forbidden响应——毕竟这是一个 API！

在 .NET 10 中，任何使用 Cookie 身份验证并标记有IApiEndpointMetadata接口的终结点将不再重定向到登录或访问被拒绝的 URI。此更改包括ApiController终结点、处理传入 JSON 请求或传出 JSON 响应的 Minimal API 终结点、使用 `<T>` 的终结点TypedResults以及 SignalR 终结点。

虽然大多数 Duende 用户会欢迎这一变化，但这仍然与以往的行为有所不同。也就是说，这一变化可能会影响到已部署的系统。请注意这一变化，并在升级时进行相应的测试。

IActionContextAccessor 和 ActionContextAccessor 已过时

.NET 现在已将IActionContextAccessor这些ActionContextAccessor抽象标记为过时。虽然 Duende IdentityServer 本身并不直接使用这些抽象，但一些客户可能会在部署的自定义配置中使用这些抽象。

由于 ASP.NET Core 已过渡到端点路由，您可以将任何使用替换IActionContextAccessor为HttpContextAccessor或IHttpContextAccessor。

public class MyService
{
private readonly IHttpContextAccessor _httpContextAccessor;

public MyService(IHttpContextAccessor httpContextAccessor)
{
_httpContextAccessor = httpContextAccessor;
}

public void DoSomething()
{
var httpContext = _httpContextAccessor.HttpContext;
var endpoint = httpContext?.GetEndpoint();
var actionDescriptor = endpoint?.Metadata.GetMetadata<ActionDescriptor>();

// Use action descriptor metadata.
}
}

请注意，此HttpContext功能仅在活动 Web 请求的生命周期内可用。

IPNetwork 和 ForwardedHeadersOptions.KnownNetworks 已过时

许多 Duende 客户，尤其是使用企业版的客户，都非常依赖转发标头来部署负载均衡的安全解决方案。这需要对 ASP.NET Core 应用程序进行相应的配置。配置过程包括设置ForwardedHeadersMiddlware其选项。

在 .NET 10 中，当KnownNetworks在中使用时ForwardHeaderOptions，您将开始收到过时的警告，引导您改用KnownIpNetworks。

app.UseForwardedHeaders(new ForwardedHeadersOptions
{
KnownIpNetworks.Add(new(IPAddress.Loopback, 8))
});

借助 Duende IdentityServer，您可以使用发现文档来验证在暂存环境中是否正确设置和处理转发标头。

Razor运行时编译已过时

开发者过去会使用 Razor 的运行时编译功能来创建更快的反馈循环。此前，该功能会.cshtml在运行时重新编译已更改的文件。这种技术避免了通常耗时的重启阶段。.NET 现在已AddRazorRuntimeCompilation将此方法标记为过时，转而采用基于工具的热重载（Hot Reload），开发者可以在 Visual Studio、VS Code 的 C# 开发工具包和 JetBrains Rider 中找到该功能。

如果您继续使用此功能，您将看到以下警告信息。

warning ASPDEPR003: Razor run-time compilation is obsolete and is not recommended for production scenarios.
For production scenarios, use the default build time compilation. For development scenarios, use Hot Reload instead.
For more information, visit https://aka.ms/aspnet/deprecate/003.

如果开发者将警告视为错误，则可能会遇到构建失败的情况，直到他们解决此特定问题为止。虽然我们的模板中未使用 Razor 运行时编译，但我们可以想象开发者可能为了改进工作流程而添加了此功能。

WebHostBuilder、IWebHost 和 WebHost 已过时

这个问题对我们影响最大，因为 Duende 的源代码WebHostBuilder在我们的代码库和测试套件中都有使用。请放心，我们目前正在进行现代化改造，并将为 .NET 10 做好准备。不过，如果您现有的 Duende IdentityServer 部署是基于之前的模板，则需要对代码进行一些调整以避免这些警告。

warning ASPDEPR004: WebHostBuilder is deprecated in favor of HostBuilder and WebApplicationBuilder. For more information, visit https://aka.ms/aspnet/deprecate/004.

正如消息中所述，您需要从WebHostBuilder`over` 迁移到HostBuilder`or` WebApplicationBuilder。如果您正在将其IWebHost作为依赖项注入，请考虑切换到 ` IHostor` 或创建一个有针对性的抽象来传递所需信息。

默认的 .NET 容器镜像现在使用 Ubuntu

在之前的版本中，.NET 团队使用基于 Debian 的容器镜像。从 .NET 10 开始，.NET 团队已将基础镜像更改为 Ubuntu。更改的原因是 Ubuntu 的支持周期更长，这意味着容器内的 .NET 版本会比运行应用程序的 Linux 发行版更早停止支持。虽然不太可能出现明显的差异，但谨慎总比后悔好。

创建新实例时取消 URI 长度限制

长度限制的更改通常对开发者来说是件好事，但也可能导致更多运行时问题。从 .NET 10 开始，创建超过 65,000 个字符的Uri字符串时不再抛出运行时异常。Uri

new Uri($"https://host/{new string('a', 100_000)}")

虽然现在可以创建大型Uri实例，但目标服务器必须能够接收这些大型有效负载。如果不能，则可能会出现异常。请运用常识和判断力。

X509证书和公钥参数可以为空

对类行为的微小改动X509Certificate都可能导致运行时异常，您应该注意这一点。

X 509Certificate、X509Certificate2和PublicKey类公开了有关主体公钥信息的信息。主体公钥信息的属性之一是算法参数。主体公钥信息并非必须包含算法参数。以前，这表示为一个空字节数组，这不符合 ASN.1 的要求。尝试对其进行编码或解码会导致异常。为了更清晰地表示缺少密钥参数的情况，null现在返回空值，并且返回算法参数的成员已被注释为返回可为空的值。

使用证书时，请记住要编写防御性代码，并检查结果是否为空。

byte[] parameters = certificate.GetKeyAlgorithmParameters();
if (parameters == null)
{
// Handle the absence of algorithm parameters
}

在使用 Duende IdentityServer 时，我们的一些客户会将X509Certificate代码实例与 Duende IdentityModel 结合使用。现在是时候检查并确认是否已启用并遵循正确的空值检查了。