migration-standards

⛔ MANDATORY RULES — Read Before Any Migration Work

Data control migration is non-negotiable

• NEVER replace <asp:ListView>, <asp:FormView>, <asp:GridView>, <asp:DataList>, or <asp:Repeater> with manual HTML, <table> markup, or @foreach loops.
• ALWAYS migrate them to the BWFC component of the same name: <ListView>, <FormView>, <GridView>, <DataList>, and <Repeater>.
• These components already exist in the BlazorWebFormsComponents library and are the correct migration target.
• If generated BWFC markup does not compile, fix the markup so the BWFC component works — do not replace the component with hand-written HTML.

1. ALL migrated pages inherit WebFormsPageBase via @inherits BlazorWebFormsComponents.WebFormsPageBase in _Imports.razor. This gives every page: Session, Response, Request, Server, Cache, ClientScript, ViewState, IsPostBack.

2. PRESERVE the original Web Forms API calls. If the Web Forms code says Session["CartId"], the Blazor code says Session["CartId"]. If it says Response.Redirect("ShoppingCart.aspx"), the Blazor code says Response.Redirect("ShoppingCart"). The shims handle the translation.

3. NEVER inject raw ASP.NET Core services when a shim exists:

   • ❌ [Inject] IHttpContextAccessor → ✅ Use Request, Response, Session properties
   • ❌ [Inject] NavigationManager (for redirects) → ✅ Use Response.Redirect()
   • ❌ [Inject] IMemoryCache → ✅ Use Cache property
   • ❌ HttpContext.Session["key"] → ✅ Use Session["key"]

4. NEVER create Minimal API endpoints to replace Web Forms page actions. If it was a page in Web Forms, it's a page in Blazor.

5. NEVER use cookies to replace Session. If the original code used Session, use SessionShim.

6. AddBlazorWebFormsComponents() in Program.cs registers ALL shims automatically.

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.