.NET 11 ASP.NET Core 中的新增功能

本文重点介绍了 .NET 11 中 ASP.NET Core 中最重要的更改，并提供了相关文档的链接。

本文将在提供新的预览版时更新。

Blazor

本部分介绍 Blazor的新功能。

新`DisplayName`组件，以及对`[Display]`和`[DisplayName]`属性的支持

该 DisplayName 组件可用于显示元数据属性中的属性名称：

[Required, DisplayName("Production Date")]
public DateTime ProductionDate { get; set; }

模型类属性上的[Display]属性是被支持的：

[Required, Display(Name = "Production Date")]
public DateTime ProductionDate { get; set; }

在两种方法中， [Display] 建议使用此属性，使其他属性可用。该 [Display] 属性还允许为本地化分配资源类型。当这两个属性都存在时， [Display] 优先于 [DisplayName]。如果两个属性都不存在，则组件会回退到属性名称。

在标签或表头中使用 DisplayName 组件：

<label>
    <DisplayName For="@(() => Model!.ProductionDate)" />
    <InputDate @bind-Value="Model!.ProductionDate" />
</label>

Blazor Web 脚本启动选项格式现在支持 Blazor Server 和 Blazor WebAssembly 脚本

Blazor Web App自 .NET 8 发布以来传递给blazor.web.js使用的脚本（Blazor.start()） options 对象使用以下格式：

Blazor.start({
  ssr: { ... },
  circuit: { ... },
  webAssembly: { ... },
});

现在， Blazor Server （blazor.server.js）和 Blazor WebAssembly （blazor.webassembly.js）脚本可以使用相同的选项格式。

以下示例显示了以前的选项格式，该格式仍受支持：

Blazor.start({
  loadBootResource: function (...) {
      ...
    },
  });

上述示例的新支持选项格式：

Blazor.start({
  webAssembly: {
    loadBootResource: function (...) {
      ...
    },
  },
});

有关详细信息，请参阅 ASP.NET Core Blazor 启动。

新的 `BasePath` 组件

Blazor Web Apps 可以使用新的 BasePath 组件（<BasePath />）来自动呈现应用基路径（<base href>）HTML 标记。有关详细信息，请参阅 ASP.NET Core Blazor 应用基路径。

从JS组件中删除了内联`NavMenu`事件处理程序

项目模板的JS中的NavMenu组件不再包含切换导航链接显示的内联Blazor Web App事件处理程序。从项目模板生成的应用现在使用并置 JS 模块方法显示或隐藏呈现页面上的导航栏。新方法可改进内容安全策略（CSP）符合性，因为它不需要 CSP 包含内联 JS的不安全哈希。

若要将现有应用迁移到 .NET 11，包括采用导航栏切换器的新 JS 模块方法，请参阅从 .NET 10 中的 ASP.NET Core 迁移到 .NET 11 中的 ASP.NET Core。

`NavigateTo` 和 `NavLink` 支持相对导航

新的参数（默认值：）适用于和组件，使您能够导航到相对于当前页面路径的 URI，而非应用程序的基 URI。

请考虑以下嵌套端点：

/docs
- /getting-started
  - /installation
  - /configuration

当浏览器的 URI 是/docs/getting-started/installation时，如果你希望将用户导航至/docs/getting-started/configuration，NavigateTo("/configuration")会在应用的根目录重定向至/configuration，而不是/docs/getting-started/configuration处的相对路径。设置所需导航的 RelativeToCurrentUri 与 NavigateTo 或 NavLink 组件。

Navigation.NavigateTo("/configuration", new NavigationOptions
{
    RelativeToCurrentUri = true
});

<NavLink href="configuration" RelativeToCurrentUri="true">Configuration</NavLink>

在静态服务器端呈现期间在 HTTP 请求之间保留临时数据（静态 SSR）

若要在静态服务器端呈现（静态 SSR）期间在 HTTP 请求之间保留临时数据， Blazor 支持 TempData。 TempData 非常适合在表单提交后快速消息、在重定向期间传递数据（POST-Redirect-GET 模式）和一次性通知等方案。

当在应用的Program文件中调用 TempData 时，TempData 是可用的，并通过[CascadingParameter]属性作为级联值提供。

[CascadingParameter]
public ITempData? TempData { get; set; }

有关详细信息，请参阅 ASP.NET 核心 Blazor 服务器端状态管理。

Blazor Hybrid

本部分介绍 Blazor Hybrid的新功能。

当预览功能可用时，此部分中会显示发行说明。

SignalR

本部分介绍 SignalR的新功能。

最小 API

本部分介绍最小 API 的新功能。

OpenAPI

本部分介绍 OpenAPI 的新功能。

描述二进制文件响应

ASP.NET Core 11 引入了对为返回二进制文件响应的作生成 OpenAPI 说明的支持。此支持将 FileContentResult 结果类型映射到包含 type: string 和 format: binary的 OpenAPI 架构。

最小 API
Controllers

使用Produces<T>扩展方法与T的FileContentResult一起指定响应类型和内容类型：

app.MapPost("/filecontentresult", () =>
{
    var content = "This endpoint returns a FileContentResult!"u8.ToArray();
    return TypedResults.File(content);
})
.Produces<FileContentResult>(contentType: MediaTypeNames.Application.Octet);

使用ProducesResponseType<T>属性与T和FileContentResult一起指定响应类型和内容类型：

[HttpPost("filecontentresult")]
[ProducesResponseType<FileContentResult>(StatusCodes.Status200OK, MediaTypeNames.Application.Octet)]
public IActionResult PostFileContentResult()
{
    var content = "This endpoint returns a FileContentResult!"u8.ToArray();
    return new FileContentResult(content, MediaTypeNames.Application.Octet);
}

生成的 OpenAPI 文档将终结点响应描述为：

responses:
  '200':
    description: OK
    content:
      application/octet-stream:
        schema:
          $ref: '#/components/schemas/FileContentResult'

FileContentResult 在 components/schemas 中定义为：

components:
  schemas:
    FileContentResult:
      type: string
      format: binary

OpenAPI 3.2.0 支持（中断性变更）

Microsoft.AspNetCore.OpenApi 现在通过更新对 Microsoft.OpenApi 3.3.1 的依赖来支持 OpenAPI 3.2.0。此更新包括基础库中的重大更改。有关详细信息，请参阅 Microsoft.OpenApi 升级指南。

若要生成 OpenAPI 3.2.0 文档，请在调用 AddOpenApi时指定版本：

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_2;
});

后续更新利用 3.2.0 规范中的新功能，例如流式处理事件的项架构支持。

感谢你 @baywet 此贡献！

身份验证和授权

本部分介绍身份验证和授权的新功能。

`TimeProvider` ASP.NET Core 中的支持 Identity

ASP.NET Core Identity 现在使用TimeProvider而不是DateTimeDateTimeOffset用于所有与时间相关的操作。此更改使 Identity 组件更具可测试性，并在测试和专用方案中更好地控制时间。

以下示例演示如何使用假 TimeProvider 来测试 Identity 功能：

// In tests
var fakeTimeProvider = new FakeTimeProvider(
    new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero));

services.AddSingleton<TimeProvider>(fakeTimeProvider);
services.AddIdentity<IdentityUser, IdentityRole>();

// Identity will now use the fake time provider

通过使用 TimeProvider，可以更轻松地为时间敏感 Identity 功能（如令牌过期、锁定持续时间和安全戳验证）编写确定性测试。

从验证器推断密码显示名称

ASP.NET Core Identity 现在会根据其 AAGUID（Authenticator 证明 GUID）自动推断密钥的友好显示名称。内置的映射涵盖了最常用的密码验证器，包括 Google Password Manager、iCloud Keychain、Windows Hello、1Password 和 Bitwarden。

对于已知的验证器，会自动分配名称，而不会提示用户。对于未知的验证器，用户将被重定向到重命名页面。通过将条目添加到项目中的 PasskeyAuthenticators 字典来扩展映射。

其他

本部分介绍 .NET 11 中的其他新功能。

`IOutputCachePolicyProvider` 接口

ASP.NET .NET 11 中的 Core 提供 [IOutputCachePolicyProvider]（https://source.dot.net/#Microsoft.AspNetCore.OutputCaching/[IOutputCachePolicyProvider.cs]（https://source.dot.net/#Microsoft.AspNetCore.OutputCaching/IOutputCachePolicyProvider.cs)' 接口来实现自定义输出缓存策略选择逻辑）。通过使用此接口，应用可以确定默认的基础缓存策略、检查命名策略是否存在，并支持必须动态解析策略的高级方案。这些示例包括从外部配置源、数据库中加载策略，或应用特定于租户的缓存规则。

以下代码显示了 IOutputCachePolicyProvider 接口：

public interface IOutputCachePolicyProvider
{
    IReadOnlyList<IOutputCachePolicy> GetBasePolicies();
    ValueTask<IOutputCachePolicy?> GetPolicyAsync(string policyName);
}

感谢你 @lqlive 此贡献！

WSL 中的自动信任开发证书

开发证书设置现在会自动信任 WSL（适用于 Linux 的 Windows 子系统）环境中的证书。在 WSL 中运行dotnet dev-certs https --trust时，证书会自动在 WSL 环境和 Windows 中安装并被信任，从而无需手动配置信任。

# Automatically trusts certificates in both WSL and Windows
dotnet dev-certs https --trust

此改进简化了使用 WSL 时的开发体验，消除了在 Windows 上的 Linux 环境中工作的开发人员的常见摩擦点。

感谢你 @StickFun 此贡献！

ASP.NET Core 的本机 OpenTelemetry 跟踪

ASP.NET Core 现在原生支持将 OpenTelemetry 语义约定属性添加到 HTTP 服务器事件，以符合 OpenTelemetry HTTP 服务器范围规范。默认情况下，包括所有必需的属性，匹配以前只能通过库提供的 OpenTelemetry.Instrumentation.AspNetCore 元数据。

若要收集内置跟踪数据，请在 OpenTelemetry 配置中订阅 Microsoft.AspNetCore 活动源：

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource("Microsoft.AspNetCore")
        .AddConsoleExporter());

不需要其他工具库（例如 OpenTelemetry.Instrumentation.AspNetCore）。框架现在直接填充请求活动上的语义约定属性，例如http.request.method，url.path和http.response.status_codeserver.address。

如果不希望向活动添加 OpenTelemetry 属性，可以通过将 Microsoft.AspNetCore.Hosting.SuppressActivityOpenTelemetryData AppContext 开关设置为 true关闭它。

性能改进

Kestrel 的 HTTP/1.1 请求解析器现在使用不抛出异常的代码路径来处理格式不正确的请求。分析器返回一个结果结构体，以指示成功、不完整或错误状态，而不是在每次解析失败时引发 BadHttpRequestException。在出现许多格式不正确的请求（例如端口扫描、恶意流量或配置不当的客户端）的情况下，这消除了昂贵的异常处理开销，并将吞吐量提高到 20-40%。对有效的请求处理没有影响。

HTTP 日志记录中间件现在对其实例 ResponseBufferingStream 进行池化，这在启用响应正文日志记录或拦截器时减少了每个请求的分配。

重大更改

使用《.NET 中的重大变化》中的文章，以帮助您在将应用程序升级到 .NET 的较新版本时查找可能适用的重大变化。

反馈

此页面是否有帮助？

Last updated on 2026-03-12