· iWork Technologies Team · Product Modernization
Refactoring ASP.NET Web Forms to Blazor Without a Big-Bang Rewrite
A practical guide to moving a legacy ASP.NET Web Forms application to Blazor one page at a time, with parity tests first, old and new running side by side, and a cutover based on evidence.

ASP.NET Web Forms runs only on .NET Framework. It will keep running for years, but it will not move to modern .NET, and every year it gets harder to hire for, secure and extend. Blazor is the natural destination for most Web Forms teams: it is component-based, written in C# and Razor, and its event model feels familiar to people who grew up on server controls.
The mistake is treating the move as a rewrite. Freezing a working product for a year while a second team rebuilds it from scratch is how migrations fail. This guide covers the approach we use instead: strangler-fig migration, where the new Blazor application takes over the old one page by page while both keep running.
Step 1: Inventory what you actually have
You cannot plan a migration around a system you have not mapped. Before any code moves, build an inventory:
- Pages and user controls. Every
.aspx,.ascxand master page, with its route and how often it is used. - Server controls in use.
GridView,UpdatePanel,Repeater, validators, third-party control suites. Third-party suites are often the hardest part to replace. - State. Where the app relies on ViewState, Session, Application state or cookies, and what lives in each.
- Authentication. Forms authentication, Windows authentication or something custom, and where authorization checks happen.
- Data access.
SqlDataSourcecontrols in markup, ADO.NET in code-behind, typed DataSets, Entity Framework 6, stored procedures. - Integrations. Web services, file drops, scheduled jobs and anything else that calls into the app or is called by it.
AI coding agents are useful here. Under a senior engineer’s direction, an agent can walk the codebase and produce a first-pass inventory of pages, controls, session keys and data calls far faster than a person reading files. A person then checks it, because the inventory drives every later decision.
Use the inventory to pick an order. Good first candidates are pages that are used often, change often and depend on little shared state.
Step 2: Write parity tests before anything moves
Parity tests pin down what the system does today, so you can prove the new version does the same. They are the safety net for the whole migration.
For a Web Forms app, parity tests are usually end-to-end:
- Browser tests that log in, fill forms, click buttons and assert on what the page shows.
- Tests that check the data written to the database after a workflow completes.
- Tests for the edge cases people forget: validation messages, empty states, permission errors.
Write them against the legacy app first and make them pass. Then point the same tests at the Blazor version of each page. If they pass there too, the page is ready to take traffic.
This is another place where agents carry the volume. Generating parity tests for hundreds of screens is repetitive work. Agents draft them; senior engineers review that each test checks real behavior rather than just that the page loads.
Step 3: Run old and new side by side
The strangler-fig pattern needs one front door. Users hit a single URL, and a routing layer decides whether each request goes to the legacy Web Forms app or the new Blazor app.
Two common options:
- YARP (Yet Another Reverse Proxy) in an ASP.NET Core app that sits in front of both. Migrated routes go to Blazor; everything else falls through to Web Forms.
- Microsoft’s System.Web adapters, which build on YARP and add support for sharing session and authentication between the two apps during an incremental migration.
Here is an illustrative YARP configuration, not a client’s setup. Migrated routes go to the new app, Blazor’s framework files go with them, and the catch-all sends the rest to the legacy app.
{
"ReverseProxy": {
"Routes": {
"customers": {
"ClusterId": "blazor",
"Match": { "Path": "/customers/{**catch-all}" }
},
"blazor-framework": {
"ClusterId": "blazor",
"Match": { "Path": "/_framework/{**catch-all}" }
},
"blazor-hub": {
"ClusterId": "blazor",
"Match": { "Path": "/_blazor/{**catch-all}" }
},
"legacy": {
"ClusterId": "webforms",
"Order": 1000,
"Match": { "Path": "{**catch-all}" }
}
},
"Clusters": {
"blazor": {
"Destinations": { "primary": { "Address": "https://new-app.internal/" } }
},
"webforms": {
"Destinations": { "primary": { "Address": "https://legacy-app.internal/" } }
}
}
}
}
Each migrated page is a routing change. If something goes wrong, you move the route back. That reversibility is what makes the approach safe.
Step 4: Map Web Forms concepts to Blazor components
Most Web Forms concepts have a direct Blazor equivalent. The mapping we work from:
| Web Forms | Blazor |
|---|---|
.aspx page |
Routable component with @page |
User control (.ascx) |
Component with [Parameter] properties |
| Master page | Layout component |
| ViewState | Component fields and properties |
| Postback and server events | @onclick, @onchange and other event handlers |
Page_Load with !IsPostBack |
OnInitializedAsync |
UpdatePanel |
Not needed: interactive components re-render only what changed |
| Validators | EditForm with DataAnnotationsValidator |
GridView |
A Razor table, QuickGrid, or a component library grid |
Below is an illustrative before and after, not client code: a simple customer search page.
Before: Web Forms markup and code-behind
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Customers.aspx.cs" Inherits="Legacy.Customers" %>
<form id="form1" runat="server">
<asp:TextBox ID="SearchBox" runat="server" />
<asp:Button ID="SearchButton" runat="server" Text="Search" OnClick="SearchButton_Click" />
<asp:GridView ID="CustomerGrid" runat="server" AutoGenerateColumns="false">
<Columns>
<asp:BoundField DataField="Name" HeaderText="Name" />
<asp:BoundField DataField="Email" HeaderText="Email" />
</Columns>
</asp:GridView>
</form>
using System;
namespace Legacy
{
public partial class Customers : System.Web.UI.Page
{
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack)
{
BindGrid(string.Empty);
}
}
protected void SearchButton_Click(object sender, EventArgs e)
{
BindGrid(SearchBox.Text);
}
private void BindGrid(string term)
{
var repository = new CustomerRepository();
CustomerGrid.DataSource = repository.Search(term);
CustomerGrid.DataBind();
}
}
}
After: a Blazor component
@page "/customers"
@rendermode InteractiveServer
@inject ICustomerService CustomerService
<input @bind="searchTerm" placeholder="Search customers" />
<button @onclick="SearchAsync">Search</button>
@if (results is null)
{
<p>Loading...</p>
}
else
{
<table>
<thead>
<tr><th>Name</th><th>Email</th></tr>
</thead>
<tbody>
@foreach (var customer in results)
{
<tr>
<td>@customer.Name</td>
<td>@customer.Email</td>
</tr>
}
</tbody>
</table>
}
@code {
private string searchTerm = string.Empty;
private IReadOnlyList<CustomerDto>? results;
protected override async Task OnInitializedAsync()
{
results = await CustomerService.SearchAsync(string.Empty);
}
private async Task SearchAsync()
{
results = await CustomerService.SearchAsync(searchTerm);
}
}
The changes worth noticing: the repository is injected through an interface instead of created inline, the data call is async, and there is no ViewState. The search term is a field on the component, and the table re-renders when results changes. The @rendermode directive applies to Blazor Web Apps on .NET 8 and later; if your app sets interactivity globally, you can leave it out.
Translating pages like this is high-volume, pattern-based work, which suits AI coding agents. They do the first translation; a senior engineer reviews each change, and the parity tests decide whether it is right.
Step 5: Solve session and authentication early
Session and authentication are where side-by-side migrations most often break. A user who logs in on a Web Forms page must stay logged in on a Blazor page, and data they put in session must still be there.
Options, roughly in order of preference:
- Move to a shared identity provider using OpenID Connect, so both apps trust the same tokens. This is usually the cleanest end state.
- Use the System.Web adapters’ remote authentication, where the new app asks the legacy app who the user is during the transition.
- Reduce session use before migrating a page. Values that only lived in session because of ViewState-era habits can often move to the URL, the database or component state.
- Use the adapters’ remote session for values you cannot remove yet, and plan to retire it.
Decide this before migrating the first authenticated page. Retrofitting it later is expensive.
Step 6: Separate data access from the pages
Web Forms apps often mix data access into markup and code-behind. Pull it out before or during the move:
- Replace
SqlDataSourcecontrols and inline ADO.NET with services behind interfaces. - Keep the existing database. Changing the schema and the UI at the same time doubles the risk.
- Entity Framework 6 runs on modern .NET, so existing EF6 code can often move as-is and be upgraded to EF Core later, in its own phase.
- Keep stored procedures if the business logic lives there. Move that logic out deliberately, not as a side effect.
The interfaces you create here are what make the Blazor components testable, and they let both apps share the same data layer during the transition.
Step 7: Cut over on evidence
A page is ready to take traffic when its parity tests pass against the Blazor version and it has run in parallel without differences. Then:
- Route a small share of users, or internal users first, to the new page.
- Watch errors, performance and support tickets.
- Move the remaining traffic, keeping the old route available as a rollback.
- Remove the legacy page once the new one has been stable for an agreed period.
Repeat until the catch-all route has nothing left to serve. Then the Web Forms app can be retired.
What this looks like at scale
We took a phased approach, with parallel development and no downtime for the business, on a legacy enterprise SaaS platform with 300+ complex screens. It moved from .NET Web Forms to Blazor, and from Xamarin to .NET MAUI. The result was 40% lower costs and 2x faster feature launches. The details are in the SaaS platform modernization case study.
Most modernizations like this run in multiple phases over 9 to 18 months. Each phase ends with a working cutover, so value arrives long before the last page moves.
Where to start
Start with the inventory and a handful of parity tests on your busiest page. That alone will tell you how hard the migration is and where the risk sits.
If you want help with that first step, book a Free AI Readiness Audit. We will look at your Web Forms estate and recommend where a first phase should start. To see how we run these engagements, read about AI Modernization.



