What's new in ASP.NET Core in .NET 10

This article highlights the most significant changes in ASP.NET Core in .NET 10 with links to relevant documentation.

Blazor

This section describes new features for Blazor.

New and updated Blazor Web App security samples

We've added and updated the Blazor Web App security samples linked in the following articles:

• Secure an ASP.NET Core Blazor Web App with OpenID Connect (OIDC)
• Secure an ASP.NET Core Blazor Web App with Microsoft Entra ID
• Secure an ASP.NET Core Blazor Web App with Windows Authentication

All of our OIDC and Entra sample solutions now include a separate web API project (MinimalApiJwt) to demonstrate how to configure and call an external web API securely. Calling web APIs is demonstrated with a token handler and named HTTP client for an OIDC identity provider or Microsoft Identity Web packages/API for Microsoft Entra ID.

The sample solutions are configured in C# code in their Program files. To configure the solutions from app settings files (for example, appsettings.json) see the new Supply configuration with the JSON configuration provider (app settings) section of the OIDC or Entra articles.

Our Entra article and sample apps also include new guidance on the following approaches:

• How to use an encrypted distributed token cache for web farm hosting scenarios.
• How to use Azure Key Vault with Azure Managed Identities for data protection.

QuickGrid RowClass parameter

Apply a stylesheet class to a row of the grid based on the row item using the new RowClass parameter. In the following example, the GetRowCssClass method is called on each row to conditionally apply a stylesheet class based on the row item:

    ...


@code {
    private string GetRowCssClass(MyGridItem item) =>
        item.IsArchived ? "row-archived" : null;
}

For more information, see ASP.NET Core Blazor `QuickGrid` component.

Blazor script as static web asset

In prior releases of .NET, the Blazor script is served from an embedded resource in the ASP.NET Core shared framework. In .NET 10 or later, the Blazor script is served as a static web asset with automatic compression and fingerprinting.

The Blazor script (blazor.web.js or blazor.server.js) is included by the framework if the project contains at least one Razor component file (.razor). If your app requires the Blazor script but doesn't contain at least one component, add the following MSBuild property to the app's project file to force unconditional script inclusion:

true

For more information, see the following resources:

• ASP.NET Core Blazor project structure
• ASP.NET Core Blazor static files

Route template highlights

The [Route] attribute now supports route syntax highlighting to help visualize the structure of the route template:

NavigateTo no longer scrolls to the top for same-page navigations

Previously, NavigationManager.NavigateTo scrolled to the top of the page for same-page navigations. This behavior has been changed in .NET 10 so that the browser no longer scrolls to the top of the page when navigating to the same page. This means the viewport is no longer reset when making updates to the address for the current page, such as changing the query string or fragment.

Reconnection UI component added to the Blazor Web App project template

The Blazor Web App project template now includes a ReconnectModal component, including collocated stylesheet and JavaScript files, for improved developer control over the reconnection UI when the client loses the WebSocket connection to the server. The component doesn't insert styles programmatically, ensuring compliance with stricter Content Security Policy (CSP) settings for the style-src policy. In prior releases, the default reconnection UI was created by the framework in a way that could cause CSP violations. Note that the default reconnection UI is still used as fallback when the app doesn't define the reconnection UI, such as by using the project template's ReconnectModal component or a similar custom component.

New reconnection UI features:

• Apart from indicating the reconnection state by setting a specific CSS class on the reconnection UI element, the new components-reconnect-state-changed event is dispatched for reconnection state changes.
• Code can better differentiate the stages of the reconnection process with the new reconnection state "retrying," indicated by both the CSS class and the new event.

For more information, see ASP.NET Core Blazor SignalR guidance.

Ignore the query string and fragment when using NavLinkMatch.All

The NavLink component now ignores the query string and fragment when using the NavLinkMatch.All value for the Match parameter. This means that the link retains the active class if the URL path matches but the query string or fragment change. To revert to the original behavior, use the Microsoft.AspNetCore.Components.Routing.NavLink.EnableMatchAllForQueryStringAndFragment AppContext switch set to true.

You can also override the ShouldMatch method on NavLink to customize the matching behavior:

public class CustomNavLink : NavLink
{
    protected override bool ShouldMatch(string currentUriAbsolute)
    {
        // Custom matching logic
    }
}

For more information, see ASP.NET Core Blazor navigation.

Close QuickGrid column options

You can now close the QuickGrid column options UI using the new HideColumnOptionsAsync method.

The following example uses the HideColumnOptionsAsync method to close the column options UI as soon as the title filter is applied:

    
        
            
        
    
    
    


@code {
    private QuickGrid? movieGrid;
    private string titleFilter = string.Empty;
    private IQueryable movies = new List { ... }.AsQueryable();
    private IQueryable filteredMovies => 
        movies.Where(m => m.Title!.Contains(titleFilter));
}

HttpClient response streaming enabled by default

In prior Blazor releases, response streaming for HttpClient requests was opt-in. Now, response streaming is enabled by default.

This is a breaking change because calling HttpContent.ReadAsStreamAsync for an HttpResponseMessage.Content (response.Content.ReadAsStreamAsync()) returns a BrowserHttpReadStream and no longer a MemoryStream. BrowserHttpReadStream doesn't support synchronous operations, such as Stream.Read(Span). If your code uses synchronous operations, you can opt-out of response streaming or copy the Stream into a MemoryStream yourself.

To opt-out of response streaming globally, use either of the following approaches:

• Add the property to the project file with a value of false:

  false
  

• Set the DOTNET_WASM_ENABLE_STREAMING_RESPONSE environment variable to false or 0.

To opt-out of response streaming for an individual request, set SetBrowserResponseStreamingEnabled to false on the HttpRequestMessage (requestMessage in the following example):

requestMessage.SetBrowserResponseStreamingEnabled(false);

For more information, see HttpClient and HttpRequestMessage with Fetch API request options (Call web API article).

Client-side fingerprinting

The release of .NET 9 introduced server-side fingerprinting of static assets in Blazor Web Apps with the introduction of Map Static Assets routing endpoint conventions (MapStaticAssets), the ImportMap component, and the ComponentBase.Assets property (@Assets["..."]) to resolve fingerprinted JavaScript (JS) modules. For .NET 10, you can opt-into client-side fingerprinting of JS modules for standalone Blazor WebAssembly apps.

In standalone Blazor WebAssembly apps during build and publish, the framework overrides placeholders in index.html with values computed during build to fingerprint static assets. A fingerprint is placed into the blazor.webassembly.js script file name.

The following markup must be present in the wwwroot/index.html file to adopt the fingerprinting feature:

    ...
+   



    ...
-   
+   

In the project file (.csproj), add the property set to true:

  
    net10.0
    enable
    enable
+   true
  

In the following example, all developer-supplied JS files are modules with a .js file extension.

A module named scripts.js in the app's wwwroot/js folder is fingerprinted by adding #[.{fingerprint}] before the file extension (.js):

Specify the fingerprint expression with the property in the app's project file (.csproj):

Any JS file (*.js) in index.html with the fingerprint marker is fingerprinted by the framework, including when the app is published.

If you adopt the .mjs file extension for JS modules, set the file extension with the Pattern parameter:

Files are placed into the import map:

• Automatically for Blazor Web App client-side rendering (CSR).
• When opting-into module fingerprinting in standalone Blazor WebAssembly apps per the preceding instructions.

When resolving the import for JavaScript interop, the import map is used by the browser resolve fingerprinted files.

Preloaded Blazor framework static assets

In Blazor Web Apps, framework static assets are automatically preloaded using Link headers, which allows the browser to preload resources before the initial page is fetched and rendered.

In standalone Blazor WebAssembly apps, framework assets are scheduled for high priority downloading and caching early in browser index.html page processing when:

• The OverrideHtmlAssetPlaceholders MSBuild property in the app's project file (.csproj) is set to true:

  
    true
  
  

• The following element containing rel="preload" is present in the content of wwwroot/index.html:

For more information, see ASP.NET Core Blazor static files.

Set the environment in standalone Blazor WebAssembly apps

The Blazor-Environment header and Properties/launchSettings.json file (ASPNETCORE_ENVIRONMENT environment variable) are no longer used to control the environment in standalone Blazor WebAssembly apps.

Starting in .NET 10, set the environment with the property in the app's project file (.csproj).

The following example sets the app's environment to Staging:

Staging

The default environments are:

• Development for build.
• Production for publish.

For more information, see ASP.NET Core Blazor environments.

Boot configuration file inlined

Blazor's boot configuration, which prior to the release of .NET 10 existed in a file named blazor.boot.json, has been inlined into the dotnet.js script. This only affects developers who are interacting directly with the blazor.boot.json file, such as when developers are:

• Checking file integrity for published assets with the troubleshoot integrity PowerShell script per the guidance in ASP.NET Core Blazor WebAssembly caching and integrity check failures.
• Changing the file name extension of DLL files when not using the default Webcil file format per the guidance in Host and deploy ASP.NET Core Blazor WebAssembly.

Currently, there's no documented replacement strategy for the preceding approaches. If you require either of the preceding strategies, open a new documentation issue describing your scenario using the Open a documentation issue link at the bottom of either article.

Declarative model for persisting state from components and services

You can now declaratively specify state to persist from components and services using the [PersistentState] attribute. Public (public) properties with this attribute are automatically persisted using the PersistentComponentState service during prerendering. The state is retrieved when the component renders interactively or the service is instantiated.

In previous Blazor releases, persisting component state during prerendering using the PersistentComponentState service involved a significant amount of code, as the following example demonstrates:

@page "/movies"
@implements IDisposable
@inject IMovieService MovieService
@inject PersistentComponentState ApplicationState

@if (MoviesList == null)
{
    
Loading...
}
else
{
    
        ...
    
}

@code {
    public List? MoviesList { get; set; }
    private PersistingComponentStateSubscription? persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        if (!ApplicationState.TryTakeFromJson>(nameof(MoviesList), 
            out var movies))
        {
            MoviesList = await MovieService.GetMoviesAsync();
        }
        else
        {
            MoviesList = movies;
        }

        persistingSubscription = ApplicationState.RegisterOnPersisting(() =>
        {
            ApplicationState.PersistAsJson(nameof(MoviesList), MoviesList);
            return Task.CompletedTask;
        });
    }

    public void Dispose() => persistingSubscription?.Dispose();
}

This code can now be simplified using the new declarative model:

@page "/movies"
@inject IMovieService MovieService

@if (MoviesList == null)
{
    
Loading...
}
else
{
    
        ...
    
}

@code {
    [PersistentState]
    public List? MoviesList { get; set; }

    protected override async Task OnInitializedAsync()
    {
        MoviesList ??= await MovieService.GetMoviesAsync();
    }
}

Use public properties because reflection is used by the framework for tasks such as trimming unused code and source generation.

State can be serialized for multiple components of the same type, and you can establish declarative state in a service for use around the app by calling RegisterPersistentService on the Razor components builder (AddRazorComponents) with a custom service type and render mode. For more information, see ASP.NET Core Blazor prerendered state persistence.

New JavaScript interop features

Blazor adds support for the following JS interop features:

• Create an instance of a JS object using a constructor function and get the IJSObjectReference/IJSInProcessObjectReference .NET handle for referencing the instance.
• Read or modify the value of a JS object property, both data and accessor properties.

The following asynchronous methods are available on IJSRuntime and IJSObjectReference with the same scoping behavior as the existing IJSRuntime.InvokeAsync method:

• InvokeConstructorAsync(string identifier, object?[]? args): Invokes the specified JS constructor function asynchronously. The function is invoked with the new operator. In the following example, jsInterop.TestClass is a class with a constructor function, and classRef is an IJSObjectReference:

  var classRef = await JSRuntime.InvokeConstructorAsync("jsInterop.TestClass", "Blazor!");
  var text = await classRef.GetValueAsync("text");
  var textLength = await classRef.InvokeAsync("getTextLength");
  

• GetValueAsync(string identifier): Reads the value of the specified JS property asynchronously. The property can't be a set-only property. A JSException is thrown if the property doesn't exist. The following example returns a value from a data property:

  var valueFromDataPropertyAsync = await JSRuntime.GetValueAsync(
    "jsInterop.testObject.num");
  

• SetValueAsync(string identifier, TValue value): Updates the value of the specified JS property asynchronously. The property can't be a get-only property. If the property isn't defined on the target object, the property is created. A JSException is thrown if the property exists but isn't writable or when a new property can't be added to the object. In the following example, num is created on testObject with a value of 30 if it doesn't exist:

  await JSRuntime.SetValueAsync("jsInterop.testObject.num", 30);
  

Overloads are available for each of the preceding methods that take a CancellationToken argument or TimeSpan timeout argument.

The following synchronous methods are available on IJSInProcessRuntime and IJSInProcessObjectReference with the same scoping behavior as the existing IJSInProcessObjectReference.Invoke method:

• InvokeConstructor(string identifier, object?[]? args): Invokes the specified JS constructor function synchronously. The function is invoked with the new operator. In the following example, jsInterop.TestClass is a class with a constructor function, and classRef is an IJSInProcessObjectReference:

  var inProcRuntime = ((IJSInProcessRuntime)JSRuntime);
  var classRef = inProcRuntime.InvokeConstructor("jsInterop.TestClass", "Blazor!");
  var text = classRef.GetValue("text");
  var textLength = classRef.Invoke("getTextLength");
  

• GetValue(string identifier): Reads the value of the specified JS property synchronously. The property can't be a set-only property. A JSException is thrown if the property doesn't exist. The following example returns a value from a data property:

  var inProcRuntime = ((IJSInProcessRuntime)JSRuntime);
  var valueFromDataProperty = inProcRuntime.GetValue(
    "jsInterop.testObject.num");
  

• SetValue(string identifier, TValue value): Updates the value of the specified JS property synchronously. The property can't be a get-only property. If the property isn't defined on the target object, the property is created. A JSException is thrown if the property exists but isn't writable or when a new property can't be added to the object. In the following example, num is created on testObject with a value of 20 if it doesn't exist:

  var inProcRuntime = ((IJSInProcessRuntime)JSRuntime);
  inProcRuntime.SetValue("jsInterop.testObject.num", 20);
  

For more information, see the following sections of the Call JavaScript functions from .NET methods article:

• Create an instance of a JS object using a constructor function
• Read or modify the value of a JS object property

Blazor WebAssembly performance profiling and diagnostic counters

New performance profiling and diagnostic counters are available for Blazor WebAssembly apps. For more information, see the following articles:

• ASP.NET Core Blazor WebAssembly browser developer tools diagnostics
• ASP.NET Core Blazor WebAssembly Event Pipe diagnostics

Opt-in to avoiding a NavigationException during static server-side rendering with NavigationManager.NavigateTo

Calling NavigationManager.NavigateTo during static server-side rendering (static SSR) throws a NavigationException, interrupting execution before being converted to a redirection response. This can cause confusion during debugging and is inconsistent with interactive rendering behavior, where code after NavigateTo continues to execute normally.

In .NET 10, you can set the MSBuild property to true in the app's project file in order to avoid throwing the exception during static SSR:

  true

With the MSBuild property set, calling NavigationManager.NavigateTo during static SSR no longer throws a NavigationException. Instead, it behaves consistently with interactive rendering by performing the navigation without throwing an exception. Code after NavigationManager.NavigateTo executes before the redirection occurs.

The .NET 10 Blazor Web App project template sets the MSBuild property to true by default. We recommend that apps updating to .NET 10 use the new MSBuild property and avoid the prior behavior.

If the MSBuild property is used, code that relied on NavigationException being thrown should be updated. In the default Blazor Identity UI of the Blazor Web App project template before the release of .NET 10, the IdentityRedirectManager throws an InvalidOperationException after calling RedirectTo to ensure that the method wasn't invoked during interactive rendering. This exception and the [DoesNotReturn] attributes should now be removed when the MSBuild property is used. For more information, see Migrate from ASP.NET Core in .NET 9 to ASP.NET Core in .NET 10.

Blazor router has a NotFoundPage parameter

Blazor now provides an improved way to display a "Not Found" page when navigating to a non-existent page. You can specify a page to render when NavigationManager.NotFound (described in the next section) is invoked by passing a page type to the Router component using the NotFoundPage parameter. The feature supports routing, works across status code pages re-execution middleware, and is compatible even with non-Blazor scenarios.

The NotFound render fragment (...) isn't supported in .NET 10 or later.

    
        
        
    
    This content is ignored because NotFoundPage is defined.

The Blazor project template now includes a NotFound.razor page by default. This page automatically renders whenever NotFound is called in your app, making it easier to handle missing routes with a consistent user experience.

For more information, see ASP.NET Core Blazor navigation.

Not Found responses using NavigationManager for static SSR and global interactive rendering

The NavigationManager now includes a NotFound method to handle scenarios where a requested resource isn't found during static server-side rendering (static SSR) or global interactive rendering:

• Static server-side rendering (static SSR): Calling NotFound sets the HTTP status code to 404.

• Interactive rendering: Signals the Blazor router (Router component) to render Not Found content.

• Streaming rendering: If enhanced navigation is active, streaming rendering renders Not Found content without reloading the page. When enhanced navigation is blocked, the framework redirects to Not Found content with a page refresh.

Streaming rendering can only render components that have a route, such as a NotFoundPage assignment (NotFoundPage="...") or a status code pages re-execution middleware page assignment (UseStatusCodePagesWithReExecute). DefaultNotFound 404 content ("Not found" plain text) doesn't have a route, so it can't be used during streaming rendering.

NotFound content rendering uses the following, regardless if the response has started or not (in order):

• If NotFoundEventArgs.Path is set, render the contents of the assigned page.
• If Router.NotFoundPage is set, render the assigned page.
• A status code pages re-execution middleware page, if configured.
• No action if none of the preceding approaches are adopted.

Status code pages re-execution middleware with UseStatusCodePagesWithReExecute takes precedence for browser-based address routing problems, such as an incorrect URL typed into the browser's address bar or selecting a link that has no endpoint in the app.

You can use the NavigationManager.OnNotFound event for notifications when NotFound is invoked.

For more information and examples, see ASP.NET Core Blazor navigation.

Support for Not Found responses in apps without Blazor's router

Apps that implement a custom router can use NotFound. There are two ways to inform the renderer what page should be rendered when NotFound is called.

The recommended approach that works regardless of the response state is to call UseStatusCodePagesWithReExecute. When NotFound is called, the middleware renders the path passed to the method:

app.UseStatusCodePagesWithReExecute(
    "/not-found", createScopeForStatusCodePages: true);

If you don't want to use UseStatusCodePagesWithReExecute, the app can still support NotFound for responses that have already started. Subscribe to OnNotFoundEvent in the router and assign the Not Found page path to NotFoundEventArgs.Path to inform the renderer what content to render when NotFound is called.

CustomRouter.razor:

@using Microsoft.AspNetCore.Components
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Http
@implements IDisposable
@inject NavigationManager NavigationManager

@code {
    protected override void OnInitialized() =>
        NavigationManager.OnNotFound += OnNotFoundEvent;

    [CascadingParameter]
    public HttpContext? HttpContext { get; set; }

    private void OnNotFoundEvent(object sender, NotFoundEventArgs e)
    {
        // Only execute the logic if HTTP response has started
        // because setting NotFoundEventArgs.Path blocks re-execution
        if (HttpContext?.Response.HasStarted == false)
        {
            return;
        }

        e.Path = GetNotFoundRoutePath();
    }

    // Return the path of the Not Found page that you want to display
    private string GetNotFoundRoutePath()
    {
        ...
    }

    public void Dispose() => NavigationManager.OnNotFound -= OnNotFoundEvent;
}

If you use both approaches in your app, the Not Found path specified in the OnNotFoundEvent handler takes precedence over the path configured in the re-execution middleware.

Metrics and tracing

This release introduces comprehensive metrics and tracing capabilities for Blazor apps, providing detailed observability of the component lifecycle, navigation, event handling, and circuit management.

For more information, see ASP.NET Core Blazor performance best practices.

JavaScript bundler support

Blazor's build output isn't compatible with JavaScript bundlers, such as Gulp, Webpack, and Rollup. Blazor can now produce bundler-friendly output during publish by setting the WasmBundlerFriendlyBootConfig MSBuild property to true.

For more information, see Host and deploy ASP.NET Core Blazor.

Blazor WebAssembly static asset preloading in Blazor Web Apps

We replaced headers with a ResourcePreloader component () for preloading WebAssembly assets in Blazor Web Apps. This permits the app base path configuration () to correctly identify the app's root.

Removing the component disables the feature if the app is using a loadBootResource callback to modify URLs.

The Blazor Web App template adopts the feature by default in .NET 10, and apps upgrading to .NET 10 can implement the feature by placing the ResourcePreloader component after the base URL tag () in the App component's head content (App.razor):

    ...
    
+   
    ...

For more information, see Host and deploy ASP.NET Core server-side Blazor apps.

Improved form validation

Blazor now has improved form validation capabilities, including support for validating properties of nested objects and collection items.

To create a validated form, use a DataAnnotationsValidator component inside an EditForm component, just as before.

To opt into the new validation feature:

1. Call the AddValidation extension method in the Program file where services are registered.
2. Declare the form model types in a C# class file, not in a Razor component (.razor).
3. Annotate the root form model type with the [ValidatableType] attribute.

Without following the preceding steps, the validation behavior remains the same as in previous .NET releases.

The following example demonstrates customer orders with the improved form validation (details omitted for brevity):

In Program.cs, call AddValidation on the service collection to enable the new validation behavior:

builder.Services.AddValidation();

In the following Order class, the [ValidatableType] attribute is required on the top-level model type. The other types are discovered automatically. OrderItem and ShippingAddress aren't shown for brevity, but nested and collection validation works the same way in those types if they were shown.

Order.cs:

[ValidatableType]
public class Order
{
    public Customer Customer { get; set; } = new();
    public List OrderItems { get; set; } = [];
}

public class Customer
{
    [Required(ErrorMessage = "Name is required.")]
    public string? FullName { get; set; }

    [Required(ErrorMessage = "Email is required.")]
    public string? Email { get; set; }

    public ShippingAddress ShippingAddress { get; set; } = new();
}

In the following OrderPage component, the DataAnnotationsValidator component is present in the EditForm component.

OrderPage.razor:

    

    
Customer Details
    

        
            Full Name
            
        
        
    

    @* ... form continues ... *@


@code {
    public Order? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    // ... code continues ...
}

The requirement to declare the model types outside of Razor components (.razor files) is due to the fact that both the new validation feature and the Razor compiler itself are using a source generator. Currently, output of one source generator can't be used as an input for another source generator.

Validation support now includes:

• Validation of nested complex objects and collections is now supported.
  • This includes validation rules defined by property attributes, class attributes, and the IValidatableObject implementation.
  • The [SkipValidation] attribute can exclude properties or types from validation.
• Validation now uses a source generator-based implementation instead of reflection-based implementation for improved performance and compatibility with ahead-of-time (AOT) compilation.

The DataAnnotationsValidator component now has the same validation order and short-circuiting behavior as System.ComponentModel.DataAnnotations.Validator. The following rules are applied when validating an instance of type T:

1. Member properties of T are validated, including recursively validating nested objects.
2. Type-level attributes of T are validated.
3. The IValidatableObject.Validate method is executed, if T implements it.

If one of the preceding steps produces a validation error, the remaining steps are skipped.

Use validation models from a different assembly

You can validate forms with models defined in a different assembly, such as a library or the .Client project of a Blazor Web App, by creating a method in the library or .Client project that receives an IServiceCollection instance as an argument and calls AddValidation on it.

• In the app, call both the method and AddValidation.

For more information, see Validation in ASP.NET Core.

Custom Blazor cache and BlazorCacheBootResources MSBuild property removed

Now that all Blazor client-side files are fingerprinted and cached by the browser, Blazor's custom caching mechanism and the BlazorCacheBootResources MSBuild property have been removed from the framework. If the client-side project's project file contains the MSBuild property, remove the property, as it no longer has any effect:

- ...

For more information, see ASP.NET Core Blazor WebAssembly caching and integrity check failures.

Web Authentication API (passkey) support for ASP.NET Core Identity

Web Authentication (WebAuthn) API support, known widely as passkeys, is a modern, phishing-resistant authentication method that improves security and user experience by leveraging public key cryptography and device-based authentication. ASP.NET Core Identity now supports passkey authentication based on WebAuthn and FIDO2 standards. This feature allows users to sign in without passwords, using secure, device-based authentication methods, such as biometrics or security keys.

The Blazor Web App project template provides out-of-the-box passkey management and login functionality.

For more information, see the following articles:

• Enable Web Authentication API (WebAuthn) passkeys
• Implement passkeys in ASP.NET Core Blazor Web Apps

Circuit state persistence

During server-side rendering, Blazor Web Apps can now persist a user's session (circuit) state when the connection to the server is lost for an extended period of time or proactively paused, as long as a full-page refresh isn't triggered. This allows users to resume their session without losing unsaved work in the following scenarios:

• Browser tab throttling
• Mobile device users switching apps
• Network interruptions
• Proactive resource management (pausing inactive circuits)
• Enhanced navigation

For more information, see ASP.NET Core Blazor server-side state management.

Hot Reload for Blazor WebAssembly and .NET on WebAssembly

The SDK migrated to a general purpose Hot Reload for WebAssembly scenarios. There's a new MSBuild property WasmEnableHotReload that's true by default for the Debug configuration (Configuration == "Debug") that enables Hot Reload.

For other configurations with custom configuration names, set the value to true in the app's project file to enable Hot Reload:

  true

To disable Hot Reload for the Debug configuration, set the value to false:

  false

Updated PWA service worker registration to prevent caching issues

The service worker registration in the Blazor Progressive Web Application (PWA) project template now includes the updateViaCache: 'none' option, which prevents caching issues during service worker updates.

- navigator.serviceWorker.register('service-worker.js');
+ navigator.serviceWorker.register('service-worker.js', { updateViaCache: 'none' });

The option ensures that:

• The browser doesn't use cached versions of the service worker script.
• Service worker updates are applied reliably without being blocked by HTTP caching.
• PWA applications can update their service workers more predictably.

This addresses caching issues that can prevent service worker updates from being applied correctly, which is particularly important for PWAs that rely on service workers for offline functionality.

We recommend using the option set to none in all PWAs, including those that target .NET 9 or earlier.

Serialization extensibility for persistent component state

Implement a custom serializer with PersistentComponentStateSerializer. Without a registered custom serializer, serialization falls back to the existing JSON serialization.

The custom serializer is registered in the app's Program file. In the following example, the CustomUserSerializer is registered for the TUser type:

builder.Services.AddSingleton, 
    CustomUserSerializer>();

The type is automatically persisted and restored with the custom serializer:

[PersistentState] 
public User? CurrentUser { get; set; } = new();

OwningComponentBase now implements IAsyncDisposable

OwningComponentBase now includes support for asynchronous disposal, improving resource management. There are new DisposeAsync and DisposeAsyncCore methods with an updated Dispose method to handle both synchronous and asynchronous disposal of the service scope.

New InputHidden component to handle hidden input fields in forms

The new InputHidden component provides a hidden input field for storing string values.

In the following example, a hidden input field is created for the form's Parameter property. When the form is submitted, the value of the hidden field is displayed:

    
    Submit


@if (submitted)
{
    
Hello @Parameter!
}

@code {
    private bool submitted;

    [SupplyParameterFromForm] 
    public string Parameter { get; set; } = "stranger";

    private void Submit() => submitted = true;
}

Persistent component state support for enhanced navigation

Blazor now supports handling persistent component state during enhanced navigation. State persisted during enhanced navigation can be read by interactive components on the page.

By default, persistent component state is only loaded by interactive components when they're initially loaded on the page. This prevents important state, such as data in an edited webform, from being overwritten if additional enhanced navigation events to the same page occur after the component is loaded.

If the data is read-only and doesn't change frequently, opt-in to allow updates during enhanced navigation by setting AllowUpdates = true on the [PersistentState] attribute. This is useful for scenarios such as displaying cached data that's expensive to fetch but doesn't change often. The following example demonstrates the use of AllowUpdates for weather forecast data:

[PersistentState(AllowUpdates = true)]
public WeatherForecast[]? Forecasts { get; set; }

protected override async Task OnInitializedAsync()
{
    Forecasts ??= await ForecastService.GetForecastAsync();
}

To skip restoring state during prerendering, set RestoreBehavior to SkipInitialValue:

[PersistentState(RestoreBehavior = RestoreBehavior.SkipInitialValue)]
public string NoPrerenderedData { get; set; }

To skip restoring state during reconnection, set RestoreBehavior to SkipLastSnapshot. This can be useful to ensure fresh data after reconnection:

[PersistentState(RestoreBehavior = RestoreBehavior.SkipLastSnapshot)]
public int CounterNotRestoredOnReconnect { get; set; }

Call PersistentComponentState.RegisterOnRestoring to register a callback for imperatively controlling how state is restored, similar to how PersistentComponentState.RegisterOnPersisting provides full control of how state is persisted.

Blazor WebAssembly respects the current UI culture setting

In .NET 9 or earlier, standalone Blazor WebAssembly apps load UI globalization resources based on CultureInfo.DefaultThreadCurrentCulture. If you want to additionally load globalization data for your localization culture defined by CultureInfo.DefaultThreadCurrentUICulture, upgrade the app to .NET 10 or later.

Blazor Hybrid

This section describes new features for Blazor Hybrid.

New .NET MAUI Blazor Hybrid with a Blazor Web App and ASP.NET Core Identity article and sample

A new article and sample app has been added for .NET MAUI Blazor Hybrid and Web App using ASP.NET Core Identity.

For more information, see the following resources:

• .NET MAUI Blazor Hybrid and Web App with ASP.NET Core Identity
• MauiBlazorWebIdentity sample app (dotnet/blazor-samples GitHub repository)

SignalR

This section describes new features for SignalR.

Minimal APIs

This section describes new features for Minimal APIs.

Treating empty string in form post as null for nullable value types

When using the [FromForm] attribute with a complex object in Minimal APIs, empty string values in a form post are now converted to null rather than causing a parse failure. This behavior matches the processing logic for form posts not associated with complex objects in Minimal APIs.

using Microsoft.AspNetCore.Http;

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapPost("/todo", ([FromForm] Todo todo) => TypedResults.Ok(todo));

app.Run();

public class Todo
{
  public int Id { get; set; }
  public DateOnly? DueDate { get; set; } // Empty strings map to `null`
  public string Title { get; set; }
  public bool IsCompleted { get; set; }
}

Thanks to @nvmkpk for contributing this change!

Validation support in Minimal APIs

Support for validation in Minimal APIs is now available. This feature allows you to request validation of data sent to your API endpoints. Enabling validation allows the ASP.NET Core runtime to perform any validations defined on the:

• Query
• Header
• Request body

Validations are defined using attributes in the DataAnnotations namespace. Developers customize the behavior of the validation system by:

• Creating custom [Validation] attribute implementations.
• Implementing the IValidatableObject interface for complex validation logic.

If validation fails, the runtime returns a 400 Bad Request response with details of the validation errors.

Enable built-in validation support for Minimal APIs

Enable the built-in validation support for Minimal APIs by calling the AddValidation extension method to register the required services in the service container for your application:

builder.Services.AddValidation();

The implementation automatically discovers types that are defined in Minimal API handlers or as base types of types defined in Minimal API handlers. An endpoint filter performs validation on these types and is added for each endpoint.

Validation can be disabled for specific endpoints by using the DisableValidation extension method, as in the following example:

app.MapPost("/products",
    ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name)
        => TypedResults.Ok(productId))
    .DisableValidation();

Validation with record types

Minimal APIs also support validation with C# record types. Record types can be validated using attributes from the System.ComponentModel.DataAnnotations namespace, similar to classes. For example:

public record Product(
    [Required] string Name,
    [Range(1, 1000)] int Quantity);

When using record types as parameters in Minimal API endpoints, validation attributes are automatically applied in the same way as class types:

app.MapPost("/products", (Product product) =>
{
    // Endpoint logic here
    return TypedResults.Ok(product);
});

Minimal API Validation integration with IProblemDetailsService

Error responses from the validation logic for Minimal APIs can now be customized by an IProblemDetailsService implementation provided in the application services collection (Dependency Injection container). This enables more consistent and user-specific error responses.

Support for Server-Sent Events (SSE)

ASP.NET Core now supports returning a ServerSentEvents result using the TypedResults.ServerSentEvents API. This feature is supported in both Minimal APIs and controller-based apps.

Server-Sent Events is a server push technology that allows a server to send a stream of event messages to a client over a single HTTP connection. In .NET the event messages are represented as SseItem objects, which may contain an event type, an ID, and a data payload of type T.

The TypedResults class has a new static method called ServerSentEvents that can be used to return a ServerSentEvents result. The first parameter to this method is an IAsyncEnumerable> that represents the stream of event messages to be sent to the client.

The following example illustrates how to use the TypedResults.ServerSentEvents API to return a stream of heart rate events as JSON objects to the client:

app.MapGet("/json-item", (CancellationToken cancellationToken) =>
{
    async IAsyncEnumerable GetHeartRate(
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            var heartRate = Random.Shared.Next(60, 100);
            yield return HeartRateRecord.Create(heartRate);
            await Task.Delay(2000, cancellationToken);
        }
    }

    return TypedResults.ServerSentEvents(GetHeartRate(cancellationToken),
                                                  eventType: "heartRate");
});

For more information, see:

• Server-Sent Events on MDN.
• Minimal API sample app using the TypedResults.ServerSentEvents API to return a stream of heart rate events as string, ServerSentEvents, and JSON objects to the client.
• Controller API sample app using the TypedResults.ServerSentEvents API to return a stream of heart rate events as string, ServerSentEvents, and JSON objects to the client.

Validation APIs moved to Microsoft.Extensions.Validation

The validation APIs have moved to the Microsoft.Extensions.Validation namespace and NuGet package. This change makes the APIs usable outside of ASP.NET Core HTTP scenarios. The public APIs and behavior remain unchanged—only the package and namespace are different. Existing projects don't require code changes, as old references redirect to the new implementation.

Enhanced validation for classes and records

Validation attributes can now be applied to both classes and records with consistent code generation and validation behavior. This enhancement improves flexibility when designing models using records in ASP.NET Core apps.

Community contribution: Thanks to @marcominerva!

OpenAPI

This section describes new features for OpenAPI.

OpenAPI 3.1 support

ASP.NET Core has added support for generating OpenAPI version 3.1 documents in .NET 10. Despite the minor version bump, OpenAPI 3.1 is a significant update to the OpenAPI specification, in particular with full support for JSON Schema draft 2020-12.

Some of the changes you will see in the generated OpenAPI document include:

• Nullable types no longer have the nullable: true property in the schema.
• Instead of a nullable: true property, they have a type keyword whose value is an array that includes null as one of the types.
• Properties or parameters defined as a C# int or long now appear in the generated OpenAPI document without the type: integer field and have a pattern field limiting the value to digits. This happens when the NumberHandling property in the JsonSerializerOptions is set to AllowReadingFromString, the default for ASP.NET Core Web apps. To enable C# int and long to be represented in the OpenAPI document as type: integer, set the NumberHandling property to Strict.

With this feature, the default OpenAPI version for generated documents is3.1. The version can be changed by explicitly setting the OpenApiVersion property of the OpenApiOptions in the configureOptions delegate parameter of AddOpenApi:

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

When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the --openapi-version in the OpenApiGenerateDocumentsOptions MSBuild item:

    net10.0
    enable
    enable
    true
    
    --openapi-version OpenApi3_1

OpenAPI 3.1 support was primarily added in the following PR.

OpenAPI 3.1 breaking changes

Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0. This new version has some breaking changes from the previous version. The breaking changes may impact apps if they have any document, operation, or schema transformers. Breaking changes in this iteration include the following:

• Entities within the OpenAPI document, like operations and parameters, are typed as interfaces. Concrete implementations exist for the inlined and referenced variants of an entity. For example, an IOpenApiSchema can either be an inlined OpenApiSchema or an OpenApiSchemaReference that points to a schema defined elsewhere in the document.
• The Nullable property has been removed from the OpenApiSchema type. To determine if a type is nullable, evaluate if the OpenApiSchema.Type property sets JsonSchemaType.Null.

One of the most significant changes is that the OpenApiAny class has been dropped in favor of using JsonNode directly. Transformers that use OpenApiAny need to be updated to use JsonNode. The following diff shows the changes in schema transformer from .NET 9 to .NET 10:

options.AddSchemaTransformer((schema, context, cancellationToken) =>
{
    if (context.JsonTypeInfo.Type == typeof(WeatherForecast))
    {
-       schema.Example = new OpenApiObject
+       schema.Example = new JsonObject
        {
-           ["date"] = new OpenApiString(DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")),
+           ["date"] = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"),
-           ["temperatureC"] = new OpenApiInteger(0),
+           ["temperatureC"] = 0,
-           ["temperatureF"] = new OpenApiInteger(32),
+           ["temperatureF"] = 32,
-           ["summary"] = new OpenApiString("Bracing"),
+           ["summary"] = "Bracing",
        };
    }
    return Task.CompletedTask;
});

Note that these changes are necessary even when only configuring the OpenAPI version to 3.0.

OpenAPI in YAML

ASP.NET now supports serving the generated OpenAPI document in YAML format. YAML can be more concise than JSON, eliminating curly braces and quotation marks when these can be inferred. YAML also supports multi-line strings, which can be useful for long descriptions.

To configure an app to serve the generated OpenAPI document in YAML format, specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in the following example:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi("/openapi/{documentName}.yaml");
}

Support for:

• YAML is currently only available for the OpenAPI served from the OpenAPI endpoint.
• Generating OpenAPI documents in YAML format at build time is added in a future preview.

See this PR which added support for serving the generated OpenAPI document in YAML format.

Response description on ProducesResponseType for API controllers

The ProducesAttribute, ProducesResponseTypeAttribute, and ProducesDefaultResponseTypeAttribute now accept an optional string parameter, Description, that sets the description of the response:

[HttpGet(Name = "GetWeatherForecast")]
[ProducesResponseType>(StatusCodes.Status200OK,
    Description = "The weather forecast for the next 5 days.")]
public IEnumerable Get()
{

Generated OpenAPI data:

"responses": {
  "200": {
    "description": "The weather forecast for the next 5 days.",
    "content": {

This functionality is supported in both API controllers and Minimal APIs. For Minimal APIs, the Description property is correctly set even when the attribute's type and the inferred return type aren't an exact match.

Community contribution (dotnet/aspnetcore #58193) by Sander ten Brinke.

Populate XML doc comments into OpenAPI document

ASP.NET Core OpenAPI document generation will now include metadata from XML doc comments on method, class, and member definitions in the OpenAPI document. You must enable XML doc comments in your project file to use this feature. You can do this by adding the following property to your project file:

  
    true
  

At build-time, the OpenAPI package will leverage a source generator to discover XML comments in the current application assembly and any project references and emit source code to insert them into the document via an OpenAPI document transformer.

Note that the C# build process does not capture XML doc comments placed on lambda expresions, so to use XML doc comments to add metadata to a Minimal API endpoint, you must define the endpoint handler as a method, put the XML doc comments on the method, and then reference that method from the MapXXX method. For example, to use XML doc comments to add metadata to a Minimal API endpoint originally defined as a lambda expression:

app.MapGet("/hello", (string name) =>$"Hello, {name}!");

Change the MapGet call to reference a method:

app.MapGet("/hello", Hello);

Define the Hello method with XML doc comments:

static partial class Program
{
    /// 

    /// Sends a greeting.
    /// 
    /// 
    /// Greeting a person by their name.
    /// 
    /// The name of the person to greet.
    /// A greeting.
    public static string Hello(string name)
    {
        return $"Hello, {name}!";
    }
}

In the previous example the Hello method is added to the Program class, but you can add it to any class in your project.

The previous example illustrates the

builder.Services.AddOpenApi(options =>
{
    options.AddOperationTransformer(async (operation, context, cancellationToken) =>
    {
        // Generate schema for error responses
        var errorSchema = await context.GetOrCreateSchemaAsync(typeof(ProblemDetails), null, cancellationToken);
        context.Document?.AddComponent("Error", errorSchema);

        operation.Responses ??= new OpenApiResponses();
        // Add a "4XX" response to the operation with the newly created schema
        operation.Responses["4XX"] = new OpenApiResponse
        {
            Description = "Bad Request",
            Content = new Dictionary
            {
                ["application/problem+json"] = new OpenApiMediaType
                {
                    Schema = new OpenApiSchemaReference("Error", context.Document)
                }
            }
        };
    });
});

builder.Services.AddAuthentication()
    .AddCookie(options =>
    {
        options.Events.OnRedirectToLogin = context =>
        {
            context.Response.Redirect(context.RedirectUri);
            return Task.CompletedTask;
        };

        options.Events.OnRedirectToAccessDenied = context =>
        {
            context.Response.Redirect(context.RedirectUri);
            return Task.CompletedTask;
        };
    });

app.UseExceptionHandler(new ExceptionHandlerOptions
{
    SuppressDiagnosticsCallback = context => false;
});

$ dotnet new web -n MyApp --localhost-tld
The template "ASP.NET Core Empty" was created successfully.

Processing post-creation actions...
Restoring D:\src\MyApp\MyApp.csproj:
Restore succeeded.

$ cd .\MyApp\
$ dotnet run --launch-profile https
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://myapp.dev.localhost:7099
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7099/
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://myapp.dev.localhost:5036
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5036/
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: D:\src\local\10.0.1xx\MyApp

public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
    var span = reader.HasValueSequence ? reader.ValueSequence.ToArray() : reader.ValueSpan;
    // previous code
}

public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
    if (reader.HasValueSequence)
    {
        reader.ValueSequence;
        // ReadOnlySequence optimized path
    }
    else
    {
        reader.ValueSpan;
        // ReadOnlySpan optimized path
    }
}

public class MyBackgroundService : BackgroundService
{
    private readonly MemoryPool _memoryPool;

    public MyBackgroundService(IMemoryPoolFactory factory)
    {
        _memoryPool = factory.Create();
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await Task.Delay(20, stoppingToken);
                // do work that needs memory
                var rented = _memoryPool.Rent(100);
                rented.Dispose();
            }
            catch (OperationCanceledException)
            {
                return;
            }
        }
    }
}

services.AddSingleton,
CustomMemoryPoolFactory>();

public class CustomMemoryPoolFactory : IMemoryPoolFactory
{
    public MemoryPool Create()
    {
        // Return a custom MemoryPool implementation
        // or the default, as is shown here.
        return MemoryPool.Shared;
    }
}

using System.Security.AccessControl;
using System.Security.Principal;
using Microsoft.AspNetCore.Server.HttpSys;

// Create a new security descriptor
var securityDescriptor = new CommonSecurityDescriptor(isContainer: false, isDS: false, sddlForm: string.Empty);

// Create a discretionary access control list (DACL)
var dacl = new DiscretionaryAcl(isContainer: false, isDS: false, capacity: 2);
dacl.AddAccess(
    AccessControlType.Allow,
    new SecurityIdentifier(WellKnownSidType.BuiltinUsersSid, null),
    -1,
    InheritanceFlags.None,
    PropagationFlags.None
);
dacl.AddAccess(
    AccessControlType.Deny,
    new SecurityIdentifier(WellKnownSidType.BuiltinGuestsSid, null),
    -1,
    InheritanceFlags.None,
    PropagationFlags.None
);

// Assign the DACL to the security descriptor
securityDescriptor.DiscretionaryAcl = dacl;

// Configure HTTP.sys options
var builder = WebApplication.CreateBuilder();
builder.WebHost.UseHttpSys(options =>
{
    options.RequestQueueSecurityDescriptor = securityDescriptor;
});

dotnet add package Microsoft.AspNetCore.JsonPatch.SystemTextJson --prerelease

// Original object
var person = new Person {
  FirstName = "John",
  LastName = "Doe",
  Email = "johndoe@gmail.com",
  PhoneNumbers = [new() {Number = "123-456-7890", Type = PhoneNumberType.Mobile}],
  Address = new Address
  {
    Street = "123 Main St",
    City = "Anytown",
    State = "TX"
  }
};

// Raw JSON Patch document
var jsonPatch = """
[
  { "op": "replace", "path": "/FirstName", "value": "Jane" },
  { "op": "remove", "path": "/Email"},
  { "op": "add", "path": "/Address/ZipCode", "value": "90210" },
  {
    "op": "add",
    "path": "/PhoneNumbers/-",
    "value": { "Number": "987-654-3210", "Type": "Work" }
  }
]
""";

// Deserialize the JSON Patch document
var patchDoc = JsonSerializer.Deserialize>(jsonPatch);

// Apply the JSON Patch document
patchDoc!.ApplyTo(person);

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

// Output:
// {
//   "firstName": "Jane",
//   "lastName": "Doe",
//   "address": {
//     "street": "123 Main St",
//     "city": "Anytown",
//     "state": "TX",
//     "zipCode": "90210"
//   },
//   "phoneNumbers": [
//     {
//       "number": "123-456-7890",
//       "type": "Mobile"
//     },
//     {
//       "number": "987-654-3210",
//       "type": "Work"
//     }
//   ]
// }

// Original object
var person = new Person {
  FirstName = "John",
  LastName = "Doe",
  Email = "johndoe@gmail.com"
};

// Raw JSON Patch document
var jsonPatch = """
[
  { "op": "replace", "path": "/Email", "value": "janedoe@gmail.com"},
  { "op": "test", "path": "/FirstName", "value": "Jane" },
  { "op": "replace", "path": "/LastName", "value": "Smith" }
]
""";

// Deserialize the JSON Patch document
var patchDoc = JsonSerializer.Deserialize>(jsonPatch);

// Apply the JSON Patch document, catching any errors
Dictionary? errors = null;
patchDoc!.ApplyTo(person, jsonPatchError =>
    {
        errors ??= new ();
        var key = jsonPatchError.AffectedObject.GetType().Name;
        if (!errors.ContainsKey(key))
        {
            errors.Add(key, new string[] { });
        }
        errors[key] = errors[key].Append(jsonPatchError.ErrorMessage).ToArray();
    });
if (errors != null)
{
    // Print the errors
    foreach (var error in errors)
    {
        Console.WriteLine($"Error in {error.Key}: {string.Join(", ", error.Value)}");
    }
}

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

// Output:
// Error in Person: The current value 'John' at path 'FirstName' is not equal 
// to the test value 'Jane'.
// {
//   "firstName": "John",
//   "lastName": "Smith",              <<< Modified!
//   "email": "janedoe@gmail.com",     <<< Modified!
//   "phoneNumbers": []
// }

public void Validate(JsonPatchDocument patch)
{
    // This is just an example. It's up to the developer to make sure that
    // this case is handled properly, based on the app's requirements.
    if (patch.Operations.Where(op=>op.OperationType == OperationType.Copy).Count()
        > MaxCopyOperationsCount)
    {
        throw new InvalidOperationException();
    }
}

if (RedirectHttpResult.IsLocalUrl(url))
{
    return Results.LocalRedirect(url);
}