convert-blazor-server-to-webapp

What this skill does

# Convert Blazor Server App to Blazor Web App

This skill helps an agent convert a pre-.NET 8 Blazor Server app into a .NET 8+ Blazor Web App. The old hosting model uses `AddServerSideBlazor`/`MapBlazorHub` with a `_Host.cshtml` Razor Page as the entry point. The new Blazor Web App model uses `AddRazorComponents`/`MapRazorComponents` with an `App.razor` root component, enabling per-component render modes, enhanced navigation, streaming rendering, and other .NET 8+ features. The converted app uses `InteractiveServer` render mode to preserve existing interactive behavior.

## When to Use

- Migrating a Blazor Server app from .NET 6 or .NET 7 to .NET 8+
- App currently uses `AddServerSideBlazor()` and `MapBlazorHub()` in `Program.cs` (or `Startup.cs`)
- App uses `Pages/_Host.cshtml` (or `_Host.razor`) as the host page with Component Tag Helpers
- Want to adopt new Blazor Web App features while keeping interactive server rendering

## When Not to Use

- **The app already uses `AddRazorComponents` and `MapRazorComponents`.** It is already a Blazor Web App — no conversion is needed. Stop here and tell the user the app is already using the Blazor Web App model.
- Blazor WebAssembly or hosted Blazor WebAssembly app — these have a different migration path
- The app should stay on the legacy Blazor Server hosting model (just update TFM and packages)
- The app targets .NET Framework — it must be migrated to .NET first

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| Blazor Server project | Yes | The `.csproj` and source files of the Blazor Server app |
| Target framework | Yes | .NET 8 or later (e.g., `net8.0`, `net9.0`, `net10.0`) |
| `Program.cs` or `Startup.cs` | Yes | The app's service and middleware configuration |
| `_Host.cshtml` location | Recommended | Usually `Pages/_Host.cshtml`; may be `_Host.razor` in some projects |

## 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>
   ```
2. 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](https://learn.microsoft.com/aspnet/core/migration/70-to-80).

### 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:

```razor
<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`.

2. **Add component injection** — if using environment-conditional error UI, add:
   ```razor
   @inject IHostEnvironment Env
   ```

3. **Fix the base tag** — replace `<base href="~/" />` with `<base href="/" />`.

4. **Replace HeadOutlet Component Tag Helper** — replace:
   ```html
   <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
   ```
   with:
   ```razor
   <HeadOutlet @rendermode="InteractiveServer" />
   ```

5. **Replace App Component Tag Helper with Routes** — replace:
   ```html
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   ```
   with:
   ```razor
   <Routes @rendermode="InteractiveServer" />
   ```

6. **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>
   }
   ```

7. **Update the Blazor script** — replace:
   ```html
   <script src="_framework/blazor.server.js"></script>
   ```
   with:
   ```html
   <script src="_framework/blazor.web.js"></script>
   ```

8. **Add render mode import** — add to `_Imports.razor`:
   ```razor
   @using static Microsoft.AspNetCore.Components.Web.RenderMode
   ```

9. **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);
       });
   ```

2. **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.

3. **Remove the fallback route** — delete:
   ```csharp
   app.MapFallbackToPage("/_Host");
   ```

4. **Remove explicit routing middleware** — delete if present:
   ```csharp
   app.UseRouting();
   ```
   Endpoint routing is the default and explicit `UseRouting()` is no longer needed.

5. **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.