跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

convert-blazor-server-to-webapp

Guides conversion of a pre-.NET 8 Blazor Server app into a .NET 8+ Blazor Web App. USE FOR: migrating apps that use AddServerSideBlazor and MapBlazorHub to the AddRazorComponents/MapRazorComponents model, converting _Host.cshtml to an App.razor root component, replacing blazor.server.js with blazor.web.js, migrating CascadingAuthenticationState to a service, adopting new Blazor Web App features like enhanced navigation and streaming rendering. DO NOT USE FOR: apps that are already Blazor Web Apps (already use AddRazorComponents and MapRazorComponents), Blazor WebAssembly or hosted Blazor WebAssembly apps (different migration path), apps that should stay on the Blazor Server hosting model without converting, or apps still targeting .NET Framework.

managedcode · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add managedcode/dotnet-skills --skill convert-blazor-server-to-webapp

技能说明


name: convert-blazor-server-to-webapp license: MIT description: > Guides conversion of a pre-.NET 8 Blazor Server app into a .NET 8+ Blazor Web App. USE FOR: migrating apps that use AddServerSideBlazor and MapBlazorHub to the AddRazorComponents/MapRazorComponents model, converting _Host.cshtml to an App.razor root component, replacing blazor.server.js with blazor.web.js, migrating CascadingAuthenticationState to a service, adopting new Blazor Web App features like enhanced navigation and streaming rendering. DO NOT USE FOR: apps that are already Blazor Web Apps (already use AddRazorComponents and MapRazorComponents), Blazor WebAssembly or hosted Blazor WebAssembly apps (different migration path), apps that should stay on the Blazor Server hosting model without converting, or apps still targeting .NET Framework.

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

InputRequiredDescription
Blazor Server projectYesThe .csproj and source files of the Blazor Server app
Target frameworkYes.NET 8 or later (e.g., net8.0, net9.0, net10.0)
Program.cs or Startup.csYesThe app's service and middleware configuration
_Host.cshtml locationRecommendedUsually 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:
    <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.

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.

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

    @inject IHostEnvironment Env
    
  3. Fix the base tag — replace <base href="~/" /> with <base href="/" />.

  4. Replace HeadOutlet Component Tag Helper — replace:

    <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
    

    with:

    <HeadOutlet @rendermode="InteractiveServer" />
    
  5. Replace App Component Tag Helper with Routes — replace:

    <component type="typeof(App)" render-mode="ServerPrerendered" />
    

    with:

    <Routes @rendermode="InteractiveServer" />
    
  6. Replace Environment Tag Helpers — replace:

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

    @if (Env.IsDevelopment())
    {
     
    
阅读完整来源 ↗