Migrating from ASP.NET Web Forms to Blazor: A Practical Roadmap

Migrating from ASP.NET Web Forms to Blazor is rarely a direct conversion between two page models. A Web Forms page owns server controls, raises postback events and often serialises control state into ViewState; a Blazor page is built from Razor components that render the interface and react to callbacks. Treat the work as application modernisation: preserve business rules, improve security and test each user journey before retiring its legacy endpoint.

For Australian organisations, the business case often combines a sizeable Microsoft-oriented mid-market sector with legacy applications that still manage essential workflows. Teams in Sydney, Melbourne and Brisbane may be moving internal processes to SaaS while employees expect dependable access from home and offices. Migration should therefore support hybrid work, Microsoft Teams and browser-based use, not just reproduce desktop-era screens and navigation.

Map the legacy application

Start with an inventory of .aspx pages, code-behind classes, master pages, user controls, validators and third-party components. Also trace Web.config, custom authentication modules, HTTP handlers, background jobs, SOAP endpoints, report generators and direct database access. Hidden dependencies frequently sit in these layers, so an inventory based only on visible pages will miss significant behaviour and operational risk.

Classify each capability as a candidate for direct component replacement, reuse behind an API, redesign or retirement. Give priority to journeys with high traffic, regulatory exposure or costly manual work rather than choosing the easiest page first. This produces a sequence based on business value while allowing the team to avoid rebuilding obsolete functions nobody uses.

Capture a baseline before implementation: response times, database load, error rates, support tickets, accessibility issues and the number of users affected by each feature. Pair those measurements with screen sketches, validation rules and dependency notes. The resulting migration register becomes the definition of done for every replacement and prevents silent functional loss.

Define target architecture and coexistence

Define the target stack on a currently supported long-term-support version of .NET, then decide which parts will be server-rendered, interactive server components or WebAssembly. A shared Razor class library can hold design-system components and domain-specific UI, while dependency injection, strongly typed configuration and structured logging replace service-locator patterns inherited from Web Forms.

Choose the interaction model from workload requirements. Interactive server rendering keeps most code and data access on the server and communicates over a persistent SignalR connection; WebAssembly can reduce server round trips and support offline scenarios but increases download size and client-side security work. A hybrid approach is normal when applications contain both administrative workflows and field users on unreliable connections.

Run the old and new applications side by side during transition. Route selected paths through a reverse proxy or gateway, retain a reversible URL mapping and keep shared identity endpoints consistent. Avoid placing old Web Forms and Blazor behind incompatible session assumptions; verify cookies, headers and timeout behaviour before moving production traffic.

Rebuild workflows as Razor components

Translate screens into components with clear inputs and outputs. Pass values through parameters, expose actions with EventCallback and use render fragments when a parent must supply content. A component should represent one coherent unit of behaviour, not reproduce every panel from the original page, and should avoid reaching directly into HttpContext or static application state.

Model data entry with EditForm, EditContext and a shared validation model instead of server-control validation attributes. Handle asynchronous saves with explicit loading and error states, prevent duplicate submissions and return validation messages close to the relevant field. Preserve keyboard behaviour and focus after rerendering so accessibility improves rather than regresses.

Extract reusable business operations into services that can be called from Blazor, API endpoints and scheduled jobs. Keep data transfer objects separate from database entities, version external contracts and place shared rules behind unit tests. Component tests with bUnit plus browser tests with Playwright can cover rendering, validation and complete navigation paths.

Replace postbacks, ViewState and hidden state

The largest architectural change is the removal of the postback lifecycle. Instead of serialising the page into ViewState and restoring it on the next request, hold transient values in component fields, shared data in appropriately scoped services and durable data in a database or cache. This reduces payload size and makes state ownership visible, although it requires deliberate choices about retention and concurrency.

Replace server-control events with component callbacks and methods that express the user’s intent. Use immutable or copied models before updating collections, and apply optimistic concurrency checks when several people can edit the same record. Persist only filters, drafts and preferences locally when appropriate; clear sensitive or stale values after completion.

Some browser operations still require JavaScript interop, such as printing, file pickers or interacting with a third-party editor. Put that code in a tested interop wrapper, handle disconnected clients and avoid using it as a shortcut around proper Blazor state management. Test WebAssembly and interactive server modes separately because their execution boundaries differ.

Preserve identity, authorisation and compliance

Rebuild authentication as a deliberate identity programme rather than copying custom Web Forms membership code. ASP.NET Core Identity, Microsoft Entra External ID or an enterprise provider can supply credential handling, password resets, account linking and multifactor authentication. Map legacy roles to claims and policy-based authorisation, then test deny paths as thoroughly as successful access.

Australian privacy obligations need to shape data flows, not appear as a final checklist. The Privacy Act 1988 and Australian Privacy Principles may apply to personal information, while some organisations must also consider state or territory legislation and sector rules. Record the purpose and retention of identity data, minimise copied attributes, secure exports and make breach escalation part of operational runbooks.

Interactive rendering can change how request-scoped services and anti-forgery protections behave. Confirm whether authentication runs before the circuit or component render, apply secure cookies consistently and avoid placing authorisation solely in the browser. Test session expiry, reconnect after network loss and unauthorised URL access, because each can bypass assumptions made in the old page lifecycle.

Connect Azure services and delivery pipelines

Move suitable data access behind APIs or application services and adopt current tooling such as Entity Framework Core where it reduces risk. For Australian workloads, evaluate Azure Australia East and Australia Southeast regions, their service availability and the contractual location of dependent data. A region label alone does not guarantee residency, so check each Azure service and logging option against the organisation’s obligations.

Build a CI/CD pipeline that compiles the solution, runs unit and integration tests, produces reproducible artefacts and deploys through infrastructure as code. Azure DevOps or GitHub Actions can coordinate pull-request checks, database migration gates, deployment slots and automated rollback. Keep secrets in a managed vault, and scan dependencies and container images before release.

Observability should begin with the first pilot. Application Insights or OpenTelemetry can connect traces, logs and metrics across the gateway, Blazor circuits, APIs and databases, with alerts tied to user outcomes rather than raw event volume. Release windows also account for teams operating across Australian time zones, including Perth and Adelaide, so overnight validation can reach the next support cohort.

For deeper internal training, programme leads can use session themes and speaker profiles from the C# Corner conference to run focused clinics on architecture, testing and cloud delivery.

Roll out, observe and improve the platform

Pilot the new application with a complete, low-risk user journey rather than a disconnected demo. Keep the legacy route available, compare results against the baseline and use feature flags or audience rules to expand access. When a defect appears, the team should be able to disable the new route and restore the old service without a lengthy deployment.

Provide a short learning path for users and support staff, since familiar Web Forms workflows may look unfamiliar in a reactive Blazor interface. Capture feedback, screen recordings and support contacts by release, then prioritise fixes according to task completion and error rates. The migration is complete only when business owners accept the new behaviour and operational teams can support it without consulting the original developers.

• Migrate one end-to-end journey at a time, including validation, authorisation, error handling, reporting and downstream integrations.
• Separate domain logic from UI code so the same rules can serve Blazor components, APIs and scheduled processes without duplication.
• Replace ViewState with explicit state ownership, scoped services and durable storage, then verify concurrency and data-retention requirements.
• Make privacy, security, accessibility and performance acceptance criteria part of the definition of done from the first pilot.
• Release behind reversible routing, monitor real user journeys and keep tested rollback procedures until the legacy path is retired.

Success should be visible in the measures captured at the start: faster completion of critical tasks, fewer support escalations, lower application overhead and consistent access for hybrid teams. A staged Blazor migration that preserves those gains is a controlled evolution of the business, not a ceremonial rewrite of its interface.