webforms-migration

Web Forms → Blazor Migration Skill

This skill provides complete transformation rules for migrating ASP.NET Web Forms applications to Blazor Server using the BlazorWebFormsComponents (BWFC) NuGet package. The BWFC library provides Blazor components with identical names, attributes, and HTML output to ASP.NET Web Forms controls — enabling migration with minimal markup changes.

Core Principle

Strip asp: and runat="server", keep everything else, and it just works.

BWFC components match Web Forms control names, property names, and rendered HTML. A well-structured Web Forms page can often be migrated by removing the asp: prefix, removing runat="server", and making a small set of structural adjustments.

Migration Recipe (Step-by-Step)

Step 1: Create Blazor Server Project

dotnet new blazor -n MyBlazorApp --interactivity Server
cd MyBlazorApp
dotnet add package Fritz.BlazorWebFormsComponents

Step 2: Configure _Imports.razor

Add these to the project-level _Imports.razor:

@using BlazorWebFormsComponents
@using BlazorWebFormsComponents.Enums

Step 3: Register BWFC Services

In Program.cs:

builder.Services.AddBlazorWebFormsComponents();

Step 3b: Configure Static Asset Middleware

In Program.cs, use MapStaticAssets() (not UseStaticFiles()) to serve both wwwroot/ content AND _framework/blazor.web.js:

app.MapStaticAssets();   // Required for _framework/blazor.web.js in .NET 9+
app.UseAntiforgery();

⚠️ CRITICAL: Using app.UseStaticFiles() alone will NOT serve _framework/blazor.web.js in .NET 9+, which means the Blazor runtime never loads and NO interactivity works on any page.

Step 3c: Add launchSettings.json

Create Properties/launchSettings.json so dotnet run uses Development mode (required for MapStaticAssets() to resolve framework files during development):

{
  "profiles": {
    "MyBlazorApp": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}