Context

When migrating an ASP.NET Web Forms application to Blazor using BlazorWebFormsComponents, these standards define the canonical target architecture, tooling choices, and migration patterns. Established through five WingtipToys migration benchmark runs and codified as a directive by Jeffrey T. Fritz.

Apply these standards to:

• Migration script (bwfc-migrate.ps1) enhancements
• Copilot-assisted Layer 2 work
• Migration documentation and checklists
• Any new migration test runs

Patterns

Target Architecture

Render Mode Placement

@rendermode is a directive attribute, not a standalone directive. It goes on component instances in markup, not in _Imports.razor.

_Imports.razor — add the static using so you can write InteractiveServer instead of RenderMode.InteractiveServer:

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

App.razor — apply render mode to the top-level routable components:

<HeadOutlet @rendermode="InteractiveServer" />
...
<Routes @rendermode="InteractiveServer" />

This gives every page global server interactivity. Do not place @rendermode InteractiveServer as a line in _Imports.razor — it is not a valid Razor directive and will cause build errors (RZ10003, CS0103, RZ10024).

Reference: ASP.NET Core Blazor render modes

Page Base Class

WebFormsPageBase eliminates per-page boilerplate when migrating Web Forms code-behind. Instead of injecting IPageService into every page, a single @inherits directive in _Imports.razor gives all pages access to familiar Web Forms properties.

One-time setup:

1. _Imports.razor — add the base class directive:

@inherits BlazorWebFormsComponents.WebFormsPageBase

2. Layout (MainLayout.razor) — add the Page render component (renders <PageTitle> and <meta> tags):

<BlazorWebFormsComponents.Page />

Properties available on every page:

What is NOT provided (forces proper Blazor migration):

• Page.Request — use IHttpContextAccessor or NavigationManager
• Page.Response — use NavigationManager for redirects
• Page.Session — use scoped DI services

When to still use @inject IPageService: Non-page components (e.g., a shared header or sidebar) that need access to page metadata should inject IPageService directly. WebFormsPageBase only applies to routable pages.

Database Migration

• Always migrate EF6 → EF Core using the latest .NET 10 packages (currently 10.0.3)
• Required packages: Microsoft.EntityFrameworkCore (10.0.3), .SqlServer (or provider matching original app), .Tools, .Design
• ⚠️ CRITICAL: Detect and match the original database provider. Examine the source project's Web.config <connectionStrings> to identify the database provider (System.Data.SqlClient → SqlServer, System.Data.SQLite → Sqlite, Npgsql → PostgreSQL). Install the matching EF Core provider package (Microsoft.EntityFrameworkCore.SqlServer, .Sqlite, Npgsql.EntityFrameworkCore.PostgreSQL, etc.). The L1 script auto-detects this — verify its detection in the [DatabaseProvider] review item. NEVER substitute a different provider than what the original application used.
• Replace DropCreateDatabaseIfModelChanges with EnsureCreated + idempotent seed
• Use IDbContextFactory<T> or scoped DbContext injection
• Models: nullable reference types, file-scoped namespaces, modern init patterns

Identity Migration

• When ASP.NET Identity is present → prefer ASP.NET Core Identity
• OWIN middleware → ASP.NET Core middleware pipeline
• Postback-based auth → HTTP endpoints + cookie auth
• Use dotnet aspnet-codegenerator identity for scaffolding
• SignInManager / UserManager APIs change — full subsystem replacement

Event Handler Strategy

BWFC components already expose EventCallback parameters with matching Web Forms names:

Signature change pattern:

// Web Forms
protected void Button1_Click(object sender, EventArgs e) { ... }

// Blazor (BWFC)
private void Button1_Click(MouseEventArgs e) { ... }
// or
private async Task Button1_Click(MouseEventArgs e) { ... }

The script should preserve the attribute and annotate the signature change needed.

Data Control Strategy — Prefer BWFC Over Raw HTML

SelectMethod PRESERVED: BWFC's DataBoundComponent<ItemType> has a native SelectMethod parameter of type SelectHandler<ItemType> (delegate signature: (int maxRows, int startRowIndex, string sortByExpression, out int totalRowCount) → IQueryable<ItemType>). Convert the Web Forms string method name to a delegate reference: SelectMethod="@productService.GetProducts" (if the service method signature matches) or use explicit lambda wiring: SelectMethod="@((maxRows, startRow, sort, out total) => service.GetProducts(maxRows, startRow, sort, out total))". When SelectMethod is set, DataBoundComponent.OnAfterRenderAsync automatically calls it to populate Items.

⚠️ DO NOT convert SelectMethod to Items= binding. When the original Web Forms markup uses SelectMethod, the migrated Blazor markup MUST preserve SelectMethod as a delegate reference. Converting to Items= loses the native BWFC data-binding pattern and defeats the purpose of drop-in replacement. The ONLY acceptable alternative is when the original Web Forms markup used DataSource (not SelectMethod), in which case Items= is correct.

Session State → Scoped Services

• Replace Session["key"] with a scoped DI service
• Use IHttpContextAccessor for cookie-based persistence when needed
• Register in Program.cs with builder.Services.AddScoped<TService>()
• Example: Session["CartId"] → CartStateService with cookie-based cart ID

Blazor Enhanced Navigation

When linking to minimal API endpoints from Blazor pages, use <form method="post"> or add data-enhance-nav="false" to prevent Blazor's enhanced navigation from intercepting the request. Enhanced navigation handles <a href> clicks as client-side SPA navigation, which breaks links to server endpoints (the request never reaches the server). This applies to all auth endpoints, cart operations, file downloads, and any other minimal API routes.

TextBox Binding Timing for Playwright Tests

BWFC TextBox uses @onchange (fires on blur), not @oninput (fires on keystroke). This affects Playwright test interactions:

• Playwright FillAsync() triggers input events, but the Blazor binding value is NOT committed until the element loses focus
• The change event fires on blur, updating the bound property
• Tests that fill fields and immediately submit may fail if the binding hasn't updated yet

Recommended Playwright pattern for form submissions:

// Fill the last field
await lastField.FillAsync("value");

// Trigger blur to commit the binding
await lastField.BlurAsync();

// Wait for binding propagation
await Task.Delay(200);

// Now click submit — the value is committed
await submitButton.ClickAsync();

Alternative using keyboard navigation:

// Fill fields
await field1.FillAsync("value1");
await field2.FillAsync("value2");

// Press Tab after the last field to trigger blur
await lastField.PressAsync("Tab");

// Small delay for binding update
await Task.Delay(200);

// Submit
await submitButton.ClickAsync();

This is a BWFC-specific behavior that mirrors Web Forms' TextBox TextChanged event semantics — both fire on blur, not on keystroke.

Static Asset Relocation

• All static files → wwwroot/
• CSS bundles (BundleConfig.cs) → explicit <link> tags in App.razor
• JS bundles → explicit <script> tags in App.razor
• Image paths update: ~/Images/ → /Images/
• Font paths: same pattern

Generated Code — Variable Declaration Styles

CRITICAL: All local variable declarations in generated Blazor code MUST use var (implicit typing), not explicit types. This is enforced by .editorconfig as IDE0007 error.

// CORRECT — var for all local declarations
var students = db.Students.ToList();
var product = await productService.GetProductAsync(id);
var count = items.Count();

// WRONG — explicit type declarations cause build failures
List<Student> students = db.Students.ToList();
Product product = await productService.GetProductAsync(id);
int count = items.Count();

This applies to both L1-generated scaffolding and L2 Copilot-generated code. IDE0007 is enabled as a build error in /.editorconfig — explicit types will fail the build immediately.

Page Lifecycle Mapping

Layer 1 (Script) vs Layer 2 (Copilot-Assisted) Boundary

⚠️ CRITICAL: Layer 1 and Layer 2 MUST both run in sequence. Do NOT make any manual code fixes between Layer 1 and Layer 2. Manual fixes between layers corrupt pipeline quality measurement. If Layer 1 output has issues, fix the script — not the output.

Layer 1 — Automated Script (migration-toolkit/scripts/bwfc-migrate.ps1):

Run via:

.\migration-toolkit\scripts\bwfc-migrate.ps1 -Path "<source-webforms-project>" -Output "<blazor-output-dir>"

Script handles:

• asp: prefix stripping (preserves BWFC tags)
• Data-binding expression conversion (5 variants)
• LoginView → preserve as BWFC LoginView — do NOT rewrite as AuthorizeView. The BWFC LoginView injects AuthenticationStateProvider natively and uses the same template names (AnonymousTemplate, LoggedInTemplate). The migration script handles this automatically.
• Master page → MainLayout.razor
• Scaffold generation (csproj, Program.cs, etc.)
• SelectMethod/GetRouteUrl flagging
• Register directive cleanup

Layer 2 — Copilot-Assisted (NOT manual — guided by the bwfc-migration skill):

• EF6 → EF Core (models, DbContext, seed)
• Identity/Auth subsystem
• Session → scoped services
• Business logic (checkout, payment, admin CRUD)
• Complex data-binding with arithmetic/method chains
• Data loading patterns (SelectMethod string → SelectHandler delegate, or Items via OnInitializedAsync)
• Template context wiring (Context="Item")
• Navigation conversions (Response.Redirect → NavigationManager.NavigateTo)

Examples

Preserving a ListView (CORRECT)

@* Web Forms *@
<asp:ListView ID="productList" runat="server"
    DataKeyNames="ProductID" GroupItemCount="4"
    ItemType="WingtipToys.Models.Product"
    SelectMethod="GetProducts">
    <ItemTemplate>
        <td><%#: Item.ProductName %></td>
    </ItemTemplate>
</asp:ListView>

@* After migration — Option A: SelectMethod preserved as delegate (BWFC native) *@
<ListView SelectMethod="@productService.GetProducts" GroupItemCount="4">
    <ItemTemplate>
        <td>@context.ProductName</td>
    </ItemTemplate>
</ListView>

@code {
    [Inject] private ProductService productService { get; set; }
}

@* After migration — Option B: Items loaded in OnInitializedAsync *@
<ListView Items="@_products" GroupItemCount="4">
    <ItemTemplate>
        <td>@context.ProductName</td>
    </ItemTemplate>
</ListView>

@code {
    [Inject] private ProductContext Db { get; set; }
    private List<Product> _products;

    protected override async Task OnInitializedAsync()
    {
        _products = await Db.Products.ToListAsync();
    }
}

Preserving Event Handlers (CORRECT)

@* Web Forms *@
<asp:Button ID="btnRemove" runat="server" Text="Remove"
    OnClick="RemoveItem_Click" CommandArgument='<%# Item.ItemId %>' />

@* After migration (BWFC preserved) *@
<Button Text="Remove"
    OnClick="RemoveItem_Click" CommandArgument="@context.ItemId" />

@code {
    // Only signature changes — method name stays the same
    private async Task RemoveItem_Click(MouseEventArgs e) { ... }
}

Anti-Patterns

❌ Replacing BWFC Data Controls with Raw HTML

@* WRONG — loses all BWFC functionality *@
@foreach (var product in _products)
{
    <tr>
        <td>@product.ProductName</td>
    </tr>
}

@* RIGHT — use BWFC ListView *@
<ListView Items="@_products">
    <ItemTemplate>
        <tr><td>@context.ProductName</td></tr>
    </ItemTemplate>
</ListView>

❌ Stripping Event Handler Attributes

@* WRONG — strips the handler, requires manual re-wiring *@
<Button Text="Submit" />
@* TODO: re-add click handler *@

@* RIGHT — preserve the attribute, only annotate signature change *@
<Button Text="Submit" OnClick="Submit_Click" />
@* TODO: Update Submit_Click signature: (object, EventArgs) → (MouseEventArgs) *@

❌ Using System.Web.UI.Page as Base Class

// WRONG — Web Forms base class
public partial class ProductList : Page { }

// RIGHT — BWFC page base class (provides Page.Title, IsPostBack, etc.)
// Set via @inherits WebFormsPageBase in _Imports.razor
public partial class ProductList : WebFormsPageBase { }

// ALSO RIGHT — for non-page components
public partial class MyComponent : ComponentBase { }