Convert Blazor Server App to Blazor Web App

Workflow

> Commit strategy: Commit after each logical step so the migration is reviewable and bisectable.

Step 1: Update the project file

Update the .csproj file:

1. Change the Target Framework Moniker (TFM) to the target version:

``xml <TargetFramework>net8.0</TargetFramework> ``

1. Update all Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.*, and System.Net.Http.Json package references to the matching version.

For non-Blazor project file changes (nullable reference types, implicit usings, HTTP/3 support, etc.), see the general ASP.NET Core migration guide.

Step 2: Create Routes.razor from App.razor

The old App.razor contains the <Router> component. This content moves to a new Routes.razor file so that App.razor can become the root HTML document component.

1. Create a new file Routes.razor in the project root.
2. Move the entire content of App.razor into Routes.razor.
3. If the content is wrapped in <CascadingAuthenticationState>, remove that wrapper (it will be replaced by a service in Step 5).
4. Leave App.razor empty for the next step.

The resulting Routes.razor should look similar to:

<Router AppAssembly="@typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
    <NotFound>
        <LayoutView Layout="@typeof(MainLayout)">
            <p>Sorry, there's nothing at this address.</p>
        </LayoutView>
    </NotFound>
</Router>

If the app uses <AuthorizeRouteView> instead of <RouteView>, keep it — it works the same way in Blazor Web Apps.

Step 3: Convert _Host.cshtml to App.razor

Move the HTML shell from Pages/_Host.cshtml into the now-empty App.razor and transform it from a Razor Page into a Razor component:

1. Remove Razor Page directives — delete @page "/", @using Microsoft.AspNetCore.Components.Web, @namespace, and @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers.

1. Add component injection — if using environment-conditional error UI, add:

``razor @inject IHostEnvironment Env ``

1. Fix the base tag — replace <base href="~/" /> with <base href="/" />.

1. Replace HeadOutlet Component Tag Helper — replace:

``html <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" /> ` with: `razor <HeadOutlet @rendermode="InteractiveServer" /> ``

1. Replace App Component Tag Helper with Routes — replace:

``html <component type="typeof(App)" render-mode="ServerPrerendered" /> ` with: `razor <Routes @rendermode="InteractiveServer" /> ``

1. Replace Environment Tag Helpers — replace:

``html <environment include="Staging,Production"> An error has occurred. This application may no longer respond until reloaded. </environment> <environment include="Development"> An unhandled exception has occurred. See browser dev tools for details. </environment> ` with: `razor @if (Env.IsDevelopment()) { <text> An unhandled exception has occurred. See browser dev tools for details. </text> } else { <text> An error has occurred. This app may no longer respond until reloaded. </text> } ``

1. Update the Blazor script — replace:

``html <script src="_framework/blazor.server.js"></script> ` with: `html <script src="_framework/blazor.web.js"></script> ``

1. Add render mode import — add to _Imports.razor:

``razor @using static Microsoft.AspNetCore.Components.Web.RenderMode ``

1. Delete `Pages/_Host.cshtml` (and Pages/_Host.cshtml.cs if it exists).

Prerendering note: If the original app used render-mode="Server" (not "ServerPrerendered"), prerendering was disabled. Preserve this by using new InteractiveServerRenderMode(prerender: false) instead of InteractiveServer for both HeadOutlet and Routes.

Step 4: Update Program.cs

Make the following changes to Program.cs (or Startup.cs if the app uses the older hosting pattern):

1. Replace Blazor Server services — replace:

``csharp builder.Services.AddServerSideBlazor(); ` with: `csharp builder.Services.AddRazorComponents() .AddInteractiveServerComponents(); ``

If AddServerSideBlazor had options configured (e.g., circuit options, hub options, detailed errors), migrate them to AddInteractiveServerComponents: ```csharp // Old: builder.Services.AddServerSideBlazor(options => { options.DetailedErrors = true; options.DisconnectedCircuitRetentionPeriod = TimeSpan.FromMinutes(10); });

// New: builder.Services.AddRazorComponents() .AddInteractiveServerComponents(options => { options.DetailedErrors = true; options.DisconnectedCircuitRetentionPeriod = TimeSpan.FromMinutes(10); }); ```

1. Replace Blazor endpoint mapping — replace:

``csharp app.MapBlazorHub(); ` with: `csharp app.MapRazorComponents<App>() .AddInteractiveServerRenderMode(); ``

Ensure there is a using statement for the project's root namespace so that App resolves to the App.razor component.

1. Remove the fallback route — delete:

``csharp app.MapFallbackToPage("/_Host"); ``

1. Remove explicit routing middleware — delete if present:

``csharp app.UseRouting(); ` Endpoint routing is the default and explicit UseRouting()` is no longer needed.

1. Add antiforgery middleware — add after UseAuthentication/UseAuthorization if present:

``csharp app.UseAntiforgery(); ` AddRazorComponents` registers antiforgery services automatically, but the middleware must be explicitly added to the pipeline. Without it, form POST requests fail with 400 errors.

Step 5: Migrate CascadingAuthenticationState (if present)

If the app used <CascadingAuthenticationState> to wrap the router:

1. Remove the <CascadingAuthenticationState> component wrapper (already done in Step 2 if following this workflow).
2. Add the cascading authentication state service in Program.cs:

``csharp builder.Services.AddCascadingAuthenticationState(); ``

The component wrapper approach does not work across render mode boundaries in Blazor Web Apps. The service-based approach provides Task<AuthenticationState> as a cascading value to all components regardless of render mode.

Step 6: Recommended improvements (optional)

These are optional modernization improvements — not required for the conversion to work. If you suggest any of these, state explicitly that they are optional.

• Replace `UseStaticFiles` with `MapStaticAssets` (.NET 9+): app.MapStaticAssets() provides optimized static file serving with fingerprinting, pre-compression, and content-based ETags. See MapStaticAssets documentation.
• Add `@attribute [StreamRendering]` to pages with async data loading (OnInitializedAsync) for improved perceived performance. The page renders its initial synchronous content immediately and re-renders when async data arrives.
• Update CSS isolation bundle reference if the <link> tag referenced a _Host assembly name; ensure it matches the project's actual assembly name: <link href="{AssemblyName}.styles.css" rel="stylesheet" />.
• For other non-Blazor improvements (minimal hosting, HTTP/3, output caching, etc.), see the general ASP.NET Core migration guide.

Step 7: Verify the migration

1. Build the project targeting the new framework. Confirm no compile errors.
2. Search for remaining references to removed APIs:

- AddServerSideBlazor - MapBlazorHub - MapFallbackToPage - blazor.server.js - _Host.cshtml

1. Run the app and verify:

- Pages load and render correctly - Interactive features work (forms, event handlers, SignalR circuits) - Navigation between pages works - Authentication and authorization flows work if present

1. Run existing tests.

Related skills