Edit

Share via

Migrate from ASP.NET Core in .NET 9 to ASP.NET Core in .NET 10

This article explains how to update an ASP.NET Core in .NET 9 to ASP.NET Core in .NET 10.

Prerequisites

Update the .NET SDK version in global.json

If you rely on a global.json file to target a specific .NET SDK version, update the version property to the .NET 10 SDK version that's installed. For example:

{
  "sdk": {
-    "version": "9.0.304"
+    "version": "10.0.100"
  }
}

Update the target framework

Update the project file's Target Framework Moniker (TFM) to net10.0:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
-    <TargetFramework>net9.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

</Project>

Update package references

In the project file, update each Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.*, and System.Net.Http.Json package reference's Version attribute to 10.0.0 or later. For example:

<ItemGroup>
-   <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="9.0.0" />
-   <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="9.0.0" />
-   <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="9.0.0" />
-   <PackageReference Include="System.Net.Http.Json" Version="9.0.0" />
+   <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="10.0.0" />
+   <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.0" />
+   <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="10.0.0" />
+   <PackageReference Include="System.Net.Http.Json" Version="10.0.0" />
</ItemGroup>

Blazor

Blazor release notes

For new feature coverage, see What's new in ASP.NET Core in .NET 10.

Set the Blazor WebAssembly environment with the WasmApplicationEnvironmentName MSBuild property

This section only applies to standalone Blazor WebAssembly apps.

The Properties/launchSettings.json file is no longer used to control the environment in standalone Blazor WebAssembly apps.

Set the environment with the <WasmApplicationEnvironmentName> property in the app's project file (.csproj).

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

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

The default environments are:

  • Development for build.
  • Production for publish.

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:

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

In prior Blazor releases, persisting component state during prerendering using the PersistentComponentState service involved a significant amount of code. Starting with .NET 10, you can declaratively specify state to persist from components and services using the [PersistentState] attribute. For more information, see What's new in ASP.NET Core in .NET 10.

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 are no longer available. If the client-side project's project file contains the MSBuild property, remove the property, as it no longer has any effect:

- <BlazorCacheBootResources>...</BlazorCacheBootResources>

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

Adopt passkey user authentication in an existing Blazor Web App

For guidance, see Implement passkeys in ASP.NET Core Blazor Web Apps.

When navigation errors are disabled in a Blazor Web App with Individual Accounts

This section applies to Blazor Web Apps that set the <BlazorDisableThrowNavigationException> MSBuild property to true in order to avoid throwing an navigation exception during static server-side rendering (static SSR).

The IdentityRedirectManager threw an InvalidOperationException in the RedirectTo method to ensure the method wasn't called from an interactive render mode and all the redirection methods were marked with the [DoesNotReturn] attribute. The .NET 10 or later Blazor Web App project template sets the <BlazorDisableThrowNavigationException> MSBuild property to true in the app's project file in order to avoid throwing the exception during static SSR. If an app based on the project template from a prior release of .NET is updated to .NET 10 or later and includes the <BlazorDisableThrowNavigationException> MSBuild property set to true, make the following changes. For more information, see What's new in ASP.NET Core in .NET 10.

In Components/Account/IdentityRedirectManager.cs:

  • Remove the InvalidOperationException from the RedirectTo method:

    - throw new InvalidOperationException(
-     $"{nameof(IdentityRedirectManager)} can only be used during static rendering.");

  • Remove five instances of the [DoesNotReturn] attribute from the file:

    - [DoesNotReturn]

Breaking changes

Use the articles in Breaking changes in .NET to find breaking changes that might apply when upgrading an app to a newer version of .NET.

  • Last updated on