diff --git a/aspnetcore/release-notes/aspnetcore-11.md b/aspnetcore/release-notes/aspnetcore-11.md index 8a5d11882b51..fa1dcaf263a1 100644 --- a/aspnetcore/release-notes/aspnetcore-11.md +++ b/aspnetcore/release-notes/aspnetcore-11.md @@ -5,7 +5,7 @@ author: wadepickett description: Learn about the new features in ASP.NET Core in .NET 11. ms.author: wpickett ms.custom: mvc -ms.date: 06/09/2026 +ms.date: 07/19/2026 uid: aspnetcore-11 --- # What's new in ASP.NET Core in .NET 11 @@ -30,6 +30,10 @@ This section describes new features for Blazor Hybrid. This section describes new features for SignalR. +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/signalr-authentication-refresh-preview-6.md)] + +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/signalr-cancel-hub-invocations-preview-6.md)] + ## Minimal APIs This section describes new features for Minimal APIs. @@ -38,6 +42,10 @@ This section describes new features for Minimal APIs. [!INCLUDE[](~/release-notes/aspnetcore-11/includes/csharp-unions-preview-6.md)] +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/async-validation-minimal-apis-preview-6.md)] + +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/short-circuit-endpoints-attribute-preview-6.md)] + ## OpenAPI This section describes new features for OpenAPI. @@ -52,6 +60,8 @@ This section describes new features for OpenAPI. [!INCLUDE[](~/release-notes/aspnetcore-11/includes/openapi-schema-improvements-preview-5.md)] +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/openapi-3-2-default-preview-6.md)] + ## Authentication and authorization This section describes new features for authentication and authorization. @@ -60,6 +70,8 @@ This section describes new features for authentication and authorization. [!INCLUDE[](~/release-notes/aspnetcore-11/includes/infer-passkey-display-name-preview2.md)] +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/user-jwts-file-based-apps-preview-6.md)] + ## Miscellaneous This section describes miscellaneous new features in .NET 11. diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/async-validation-minimal-apis-preview-6.md b/aspnetcore/release-notes/aspnetcore-11/includes/async-validation-minimal-apis-preview-6.md new file mode 100644 index 000000000000..43d90a70feb8 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-11/includes/async-validation-minimal-apis-preview-6.md @@ -0,0 +1,75 @@ +### Async validation for minimal APIs + +Minimal API validation now supports asynchronous validators end-to-end ([dotnet/aspnetcore #66487](https://github.com/dotnet/aspnetcore/pull/66487), [dotnet/aspnetcore #67183](https://github.com/dotnet/aspnetcore/pull/67183)). Preview 5 shipped the building blocks for asynchronous form validation in Blazor. Preview 6 adds new asynchronous `DataAnnotations` APIs in the base libraries (`AsyncValidationAttribute` and `IAsyncValidatableObject`), and `Microsoft.Extensions.Validation` now runs them when an endpoint validates a request. + +The simplest way to add an asynchronous rule is a custom validation attribute. Derive from `AsyncValidationAttribute` and implement `IsValidAsync` to query a database or call a remote API without blocking a thread. The synchronous `IsValid` is abstract too; throw from it when the attribute validates asynchronously only: + +```csharp +using System.ComponentModel.DataAnnotations; +using Microsoft.Extensions.DependencyInjection; + +public sealed class UniqueEmailAttribute : AsyncValidationAttribute +{ + // Synchronous IsValid. This attribute validates asynchronously only. + protected override ValidationResult? IsValid(object? value, ValidationContext context) => + throw new InvalidOperationException("Validate this attribute with IsValidAsync."); + + protected override async Task IsValidAsync( + object? value, ValidationContext context, CancellationToken cancellationToken) + { + var users = context.GetRequiredService(); + + if (value is string email && await users.EmailExistsAsync(email, cancellationToken)) + { + return new ValidationResult("That email is already registered."); + } + + return ValidationResult.Success; + } +} +``` + +Apply `[UniqueEmail]` to a property like any built-in validation attribute. + +For validation that spans several properties or the whole object, implement `IAsyncValidatableObject` and return results as an `IAsyncEnumerable`. Because `IAsyncValidatableObject` extends `IValidatableObject`, also implement the synchronous `Validate` method. When a type validates asynchronously only, throw from `Validate` so its validation isn't silently skipped by the synchronous APIs: + +```csharp +using System.ComponentModel.DataAnnotations; +using System.Runtime.CompilerServices; + +public class ReservationRequest : IAsyncValidatableObject +{ + [Required] + public string Email { get; set; } = ""; + + public DateOnly Date { get; set; } + + // Synchronous IValidatableObject. This type validates asynchronously only. + public IEnumerable Validate(ValidationContext context) => + throw new InvalidOperationException("Validate this type with ValidateAsync."); + + public async IAsyncEnumerable ValidateAsync( + ValidationContext context, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + var rooms = context.GetRequiredService(); + + if (!await rooms.HasAvailabilityAsync(Date, cancellationToken)) + { + yield return new ValidationResult( + "No rooms are available on that date.", [nameof(Date)]); + } + } +} +``` + +Register validation and the framework validates the request before the endpoint runs: + +```csharp +builder.Services.AddValidation(); + +app.MapPost("/reservations", (ReservationRequest request) => + Results.Ok(request)); +``` + +Validators run concurrently where possible: asynchronous attributes on the same member start together, collection items validate in parallel, and the framework preserves the existing ordering between member, type, and `IValidatableObject` validation. diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/csharp-unions-preview-6.md b/aspnetcore/release-notes/aspnetcore-11/includes/csharp-unions-preview-6.md index db6a9dea622f..e94b9227b1ac 100644 --- a/aspnetcore/release-notes/aspnetcore-11/includes/csharp-unions-preview-6.md +++ b/aspnetcore/release-notes/aspnetcore-11/includes/csharp-unions-preview-6.md @@ -10,4 +10,6 @@ app.MapGet("/value", () => new UnionIntString(42)); Union types aren't supported for non-body binding sources such as route values, query strings, headers, and form fields. +For OpenAPI, an endpoint that returns a union is described with an `anyOf` schema listing each case type. Unlike polymorphic types, union cases don't carry a `$type` discriminator, so each case reuses its standalone component (for example, `#/components/schemas/Dog`) instead of a duplicated, prefixed one. ApiExplorer detects a union through `JsonTypeInfoKind.Union`, so the schema also flows through to Swashbuckle and NSwag. When multiple cases serialize to the same JSON shape, disambiguate them with a `[JsonUnion]` classifier. SignalR unions require the JSON hub protocol; the MessagePack and `Newtonsoft.Json` protocols don't support unions. + For examples and additional information that apply to Blazor apps, see the [Component parameters section in the Components overview article](xref:blazor/components/index#component-parameters) and the [Pass parameters section of the Dynamically-rendered ASP.NET Core Razor components article](xref:blazor/components/dynamiccomponent). diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/openapi-3-2-default-preview-6.md b/aspnetcore/release-notes/aspnetcore-11/includes/openapi-3-2-default-preview-6.md new file mode 100644 index 000000000000..f75e8fa87528 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-11/includes/openapi-3-2-default-preview-6.md @@ -0,0 +1,12 @@ +### OpenAPI 3.2 by default + +Generated OpenAPI documents now target OpenAPI 3.2 by default. Documents continue to generate as before. Set the document version explicitly if you need to target an earlier version for tooling that doesn't yet support OpenAPI 3.2. + +To target an earlier version, specify it when calling : + +```csharp +builder.Services.AddOpenApi(options => +{ + options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_1; +}); +``` diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/short-circuit-endpoints-attribute-preview-6.md b/aspnetcore/release-notes/aspnetcore-11/includes/short-circuit-endpoints-attribute-preview-6.md new file mode 100644 index 000000000000..af13f1b18497 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-11/includes/short-circuit-endpoints-attribute-preview-6.md @@ -0,0 +1,26 @@ +### Short-circuit endpoints with an attribute + +The new `[ShortCircuit]` attribute marks an endpoint to run immediately after routing, skipping the rest of the middleware pipeline. This is the attribute form of the existing `ShortCircuit()` endpoint convention, so it can be applied directly to MVC controllers and actions. + + + +Short-circuiting is useful for endpoints that don't need authentication, CORS, or other middleware—for example a health check or a `robots.txt` response, and it avoids the cost of running that middleware. The endpoint still runs and produces its response. Pass an optional status code, such as `[ShortCircuit(404)]`, to set the response status code. + +```csharp +[ApiController] +[Route("robots.txt")] +[ShortCircuit] +public class RobotsController : ControllerBase +{ + [HttpGet] + public IActionResult Get() => Content("User-agent: *\nDisallow:", "text/plain"); +} +``` + +The same attribute works on minimal API endpoints, and the existing `ShortCircuit()` convention continues to work unchanged: + +```csharp +app.MapGet("/health", [ShortCircuit] () => "Healthy"); +``` + +Thank you [@Porozhniakov](https://github.com/Porozhniakov) for contributing this feature! diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/signalr-authentication-refresh-preview-6.md b/aspnetcore/release-notes/aspnetcore-11/includes/signalr-authentication-refresh-preview-6.md new file mode 100644 index 000000000000..88300301494d --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-11/includes/signalr-authentication-refresh-preview-6.md @@ -0,0 +1,45 @@ +### SignalR authentication refresh + +SignalR connections can refresh authentication without dropping the connection when the access token expires. The server exposes a `/refresh` endpoint alongside `/negotiate` and reports the token lifetime in the negotiate response. The .NET client re-authenticates before the token expires, so a hub connection that previously closed when its bearer token aged out can stay open. This feature is implemented for the .NET client; the JavaScript/TypeScript client and Azure SignalR Service support are in progress. + + + +Enable the feature per hub on the server: + +```csharp +app.MapHub("/chat", options => +{ + options.EnableAuthenticationRefresh = true; + + // Optional: decide whether a given connection can refresh. + options.OnAuthenticationRefresh = context => ValueTask.FromResult(true); +}); +``` + +A hub can react to a refreshed identity by overriding `OnAuthenticationRefreshedAsync`: + +```csharp +public class ChatHub : Hub +{ + public override Task OnAuthenticationRefreshedAsync() + { + // The connection's User has been updated with the refreshed token. + return Task.CompletedTask; + } +} +``` + +Automatic refresh is on by default in the .NET client and is configurable with `WithAuthenticationRefresh`: + +```csharp +var connection = new HubConnectionBuilder() + .WithUrl("https://example.com/chat") + .WithAuthenticationRefresh(options => + { + // EnableAutoRefresh is true by default. + options.RefreshBeforeExpiration = TimeSpan.FromMinutes(1); + options.OnAuthenticationRefreshed = context => Task.CompletedTask; + options.OnAuthenticationRefreshFailed = context => Task.CompletedTask; + }) + .Build(); +``` diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/signalr-cancel-hub-invocations-preview-6.md b/aspnetcore/release-notes/aspnetcore-11/includes/signalr-cancel-hub-invocations-preview-6.md new file mode 100644 index 000000000000..91835b6a16ca --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-11/includes/signalr-cancel-hub-invocations-preview-6.md @@ -0,0 +1,22 @@ +### Cancel hub invocations from the client + +The SignalR client can cancel a regular, non-streaming hub method invocation. Previously only streaming invocations could be canceled from the client. Now, when you pass a to and cancel it, the client sends a cancellation message, and the hub method's `CancellationToken` parameter is triggered on the server. + +```csharp +// Client — canceling the token cancels the server-side invocation. +using var cts = new CancellationTokenSource(); +var work = connection.InvokeAsync("LongRunningWork", cts.Token); +// ... +cts.Cancel(); +``` + +```csharp +// Hub — accept a CancellationToken to observe client cancellation. +public class WorkHub : Hub +{ + public async Task LongRunningWork(CancellationToken cancellationToken) + { + await Task.Delay(TimeSpan.FromMinutes(5), cancellationToken); + } +} +``` diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/user-jwts-file-based-apps-preview-6.md b/aspnetcore/release-notes/aspnetcore-11/includes/user-jwts-file-based-apps-preview-6.md new file mode 100644 index 000000000000..5a8d63f84852 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-11/includes/user-jwts-file-based-apps-preview-6.md @@ -0,0 +1,7 @@ +### `dotnet user-jwts` supports file-based apps + +The `dotnet user-jwts` tool creates signed development JWTs so you can call an app's authenticated endpoints without setting up a real identity provider. The `create` command generates a token, stores its signing key in the app's user secrets, and prints the token to use as a bearer token. It now works with file-based apps (a single `app.cs` with no project file) through the new `--file` option: + +```bash +dotnet user-jwts create --file app.cs +```