1. Introduction

.NET 10 is a Long-Term Support (LTS) release designed for stability, performance, and long-term maintenance. Migrating from .NET 9 to .NET 10 is generally straightforward, but Blazor Server, ASP.NET Core hosting, and authentication flows require special attention due to breaking behavioral changes.

This guide consolidates Microsoft documentation, Uno Platform guidance, and community learnings into a single, end-to-end migration playbook.

2. Prerequisites & Environment Setup

Install .NET 10 SDK

Ensure the .NET 10 SDK is installed and update global.json if present:

{ "sdk": { "version": "10.0.100" } }

Visual Studio

Use a Visual Studio version that supports .NET 10 (VS 2026+). Older versions will fail to load or debug projects correctly.

3. Update Project Target Frameworks

In every .csproj:

<PropertyGroup> <TargetFramework>net10.0</TargetFramework> </PropertyGroup>

For multi-targeting:

<TargetFrameworks>net10.0;netstandard2.0</TargetFrameworks>

Clean build artifacts:

dotnet clean rm -rf bin obj

4. Update NuGet Packages

List outdated dependencies:

dotnet list package --outdated

Upgrade to .NET 10–compatible versions, paying attention to:

• ASP.NET Core packages

• EF Core 10.x

• Authentication providers

• UI component libraries (MudBlazor, Telerik, Syncfusion, etc.)

⚠️ Some ecosystem libraries may lag behind .NET 10—verify compatibility before upgrading production apps.

5. Breaking Changes Overview (.NET 10)

Key platform-wide changes:

• Obsolete hosting APIs (WebHostBuilder, IWebHost)

• Authentication behavior changes (401/403 instead of redirects)

• Razor runtime compilation deprecated

• OpenAPI changes (WithOpenApi)

• EF Core query & JSON mapping behavior updates

• .NET CLI defaults changed (.slnx, auditing)

6. Blazor Server App Migration (DETAILED)

Blazor Server apps are ASP.NET Core apps with persistent SignalR connections, so authentication, hosting, and middleware changes in .NET 10 matter more here than in minimal APIs.

6.1 Update the Project File (Blazor Server)

Typical Blazor Server .csproj before:

<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>net9.0</TargetFramework> <Nullable>enable</Nullable> <ImplicitUsings>enable</ImplicitUsings> </PropertyGroup> </Project>

After migration:

<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>net10.0</TargetFramework> <Nullable>enable</Nullable> <ImplicitUsings>enable</ImplicitUsings> </PropertyGroup> </Project>

6.2 Hosting Model Changes (Critical)

❌ Old pattern (obsolete in .NET 10)

public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup<Startup>(); });

✅ Recommended .NET 10 pattern

var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorComponents() .AddInteractiveServerComponents(); var app = builder.Build(); app.MapRazorComponents<App>() .AddInteractiveServerRenderMode(); app.Run();

📌 Why this matters
Blazor Server depends on the modern minimal hosting model. The old Startup.cs approach is no longer recommended and may break future updates.

6.3 Authentication & Authorization Changes (Very Important)

Behavior Change in .NET 10

Impact on Blazor Server

• <AuthorizeRouteView> may stop navigating properly

• Login flows can break

• Users may see blank pages or circuit disconnects

Fix: Explicit Authentication Handling

Ensure you configure authentication correctly:

builder.Services.AddAuthentication(options => { options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme; }) .AddCookie(options => { options.LoginPath = "/Account/Login"; options.AccessDeniedPath = "/Account/AccessDenied"; });

And in App.razor:

<CascadingAuthenticationState> <Router AppAssembly="@typeof(App).Assembly"> <Found Context="routeData"> <AuthorizeRouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)"> <NotAuthorized> <RedirectToLogin /> </NotAuthorized> </AuthorizeRouteView> </Found> </Router> </CascadingAuthenticationState>

📌 Recommendation
Explicitly handle login redirects inside Blazor components rather than relying on middleware redirects.

6.4 Razor & Runtime Compilation

Change in .NET 10

• Runtime Razor compilation is obsolete

• Precompiled Razor is now the default

❌ Remove:

builder.Services.AddRazorPages().AddRazorRuntimeCompilation();

✅ Keep:

builder.Services.AddRazorPages();

This improves startup performance and avoids runtime failures.

6.5 SignalR & Circuit Stability

Blazor Server relies on SignalR:

• .NET 10 introduces internal performance improvements

• Circuit reconnection behavior is stricter

Best practices:

builder.Services.AddServerSideBlazor(options => { options.DisconnectedCircuitRetentionPeriod = TimeSpan.FromMinutes(3); options.JSInteropDefaultCallTimeout = TimeSpan.FromSeconds(60); });

6.6 JavaScript Interop Changes

While no major breaking API changes exist, timing and lifecycle ordering may differ.

✔ Ensure JS calls happen after render:

@inject IJSRuntime JS protected override async Task OnAfterRenderAsync(bool firstRender) { if (firstRender) { await JS.InvokeVoidAsync("init"); } }

6.7 Blazor Server + EF Core 10

Common issues:

• JSON column mapping behavior changed

• ExecuteUpdateAsync signature changes

• Date/Time handling differs for SQLite

✔ Always retest:

• Data grids

• Background jobs

• Scoped DbContext lifetimes

7. MAUI & Uno Notes (Summary)

• Update tooling & templates

• MAUI workloads must match .NET 10 SDK

• Uno Platform recommends .slnx and updated VS extensions

• Avoid mixing older MSBuild tasks

8. Testing Strategy (Mandatory)

Automated

Manual (Blazor-specific)

• Login/logout flows

• Page refresh during active circuits

• Authorization-protected routes

• Browser reconnect behavior

9. Migration Checklist (Blazor Included)

10. Final Thoughts

Migrating from .NET 9 to .NET 10 is low-risk for most projects, but Blazor Server apps require careful attention to:

• Authentication behavior

• Hosting model modernization

• Circuit lifecycle management

Once migrated, you gain:

• LTS stability

• Improved performance

• Cleaner hosting architecture

• Better long-term support guarantees