# Move one .NET capability at a time, with a route back

Scope an incremental ASP.NET migration around one capability, explicit compatibility checks, and a rollback decision that includes data.

Mottobits · Reviewed 2026-09-30

A modernization plan becomes useful when it names the first capability to move, the dependencies it crosses, and how the team will recover if its assumptions are wrong. Microsoft documents a side-by-side approach in which ASP.NET Core fronts an existing ASP.NET application through YARP. That provides a migration option, not a promise that every view, helper, authentication mechanism, or dependency transfers unchanged.

## Inventory the actual boundary

Start with routes and business behavior, then map the dependencies used by a candidate capability. Include authentication, authorization, session, cookies, antiforgery, file handling, serialization, background work, database writes, and external integrations.

- Record the current build and deployment path, including Windows-only dependencies.
- Choose a supported target based on the application's dependencies and operating environment.
- Pick a bounded capability with a known business owner and observable success criteria.
- Capture baseline behavior and performance using representative test data.

## Prove coexistence before expanding scope

Add the new application beside the old one and make routing ownership explicit. Migrate one capability while the remaining routes continue to the existing application. Authentication needs its own design: Microsoft's documented options include a native rewrite, remote authentication through System.Web adapters, and shared cookies for compatible OWIN scenarios.

- Test login, logout, expiration, role restrictions, and redirects across both applications.
- Check cookie domains and paths, forwarded headers, request limits, and antiforgery behavior.
- Write down which application owns each route and each state-changing operation.
- Avoid shadowing state-changing production requests; duplicated writes can cause real side effects.

## Design rollback around state

Sending traffic back to the old application is useful only if the old application still understands the resulting data. Define database and message compatibility before the first release. Rehearse the rollback with the same kind of schema and state changes the real slice will introduce.

- Prefer compatible schema changes while old and new versions run together.
- Name the signals that stop rollout and the person who can make that decision.
- Verify that retries do not duplicate side effects across the two paths.
- Compare the first slice's operational cost and delivery benefit before committing to the next one.

## Illustrative example — not customer results

Move order-history viewing behind an explicit route while order creation and billing remain in the legacy application.

- The same authorized user sees equivalent order content on the agreed data set.
- Cross-tenant and unauthorized requests remain denied.
- Session expiration and redirects behave according to the documented contract.
- The route can return to the legacy implementation using the rehearsed procedure.
- Latency and error-rate limits are agreed before rollout and measured after it.

## Deliverables

- Dependency and route map
- Architecture decision for the first slice
- Compatibility checks
- Deployment, observation, and rollback notes

## Limits

- Adapters cover specific compatibility scenarios; they do not make ASP.NET Core a drop-in replacement for System.Web.
- For a small application, a controlled full cutover may be simpler than maintaining two applications. Assess the tradeoff before adopting a proxy.

## Sources

- [Microsoft: Get started with incremental ASP.NET migration](https://learn.microsoft.com/en-us/aspnet/core/migration/fx-to-core/start?view=aspnetcore-10.0)
- [Microsoft: Authentication migration](https://learn.microsoft.com/en-us/aspnet/core/migration/fx-to-core/areas/authentication?view=aspnetcore-10.0)
- [Microsoft: System.Web adapters](https://github.com/dotnet/systemweb-adapters)

Co-written by Adnan Rafiq and ChatGPT. ChatGPT assists with research, drafting, and source checks; the engineering direction comes from Adnan. Examples are illustrative unless an article explicitly provides executed results. These are working methods, not customer case studies or guaranteed outcomes.