Strangler Fig Pattern for Legacy Migration
On this page
Why big-bang rewrites fail
A team decides to rewrite a 12-year-old ASP.NET Web Forms retail system from scratch. Two years in, the new system still doesn't do everything the old one does, because the old one kept changing and nobody had written down half of its rules. Meanwhile the business got no new features. Many rewrites end this way: cancelled or shipped late with missing behavior.
The strangler fig pattern, named by Martin Fowler after a vine that grows around a tree until it replaces it, avoids the big bang. You put a routing layer in front of the old system and move one capability at a time to new code. The old system shrinks until it can be switched off. At every step, the system works and delivers.
Strangler fig pattern: the steps
- Put a facade in front. A reverse proxy or API gateway (YARP, NGINX, a cloud load balancer) receives all traffic. At first it forwards everything to the legacy app. Users notice nothing.
- Pick one capability and build it as a new service.
- Route that capability's traffic to the new service, path by path:
/catalog/*goes new, everything else still goes old. Start with a small percentage of users if you can. - Watch and compare. Errors, latency, business numbers. Keep the old path ready to route back to. For logic that must match exactly, such as pricing or tax, run a parallel run first: send each request to both systems, return the legacy answer to the user, and log every case where the new one differs. GitHub's Scientist library, with a .NET port, is built for this. Switch over when the differences are zero or explained.
- Remove the legacy code for that capability once the new one is proven.
- Repeat until nothing is left.
Choosing what to extract first
Good first candidates:
- Change often, so the new code pays back quickly.
- Have a clear boundary, a bounded context (Day 52) with few dependencies.
- Are lower risk than the core money path, so the team learns the process safely.
- Are mostly reads, which are easier to move than complex writes.
For the Web Forms retailer, the catalog fits: the merchandising team changes it weekly, it's read-heavy, and an error there doesn't charge anyone's card. Checkout and payments come later, once the team has done it a few times.
The hard part: migrating data
Code moves more easily than data. During the transition the new service often needs data that the legacy database still owns. Options, roughly in order of independence:
| Approach | How | Trade-off |
|---|---|---|
| Read the legacy database | New service reads old tables directly | Quick start; still coupled to the old schema |
| Sync data | Change data capture copies legacy changes into the new store | Independence for reads; one-way and eventually consistent |
| New service owns it | Writes move to the new service; legacy reads through an API or a synced copy | Real independence; needs careful cutover |
Avoid two systems both writing the same data with nobody clearly in charge. Pick an owner for each piece of data at each stage, and use an anti-corruption layer (Day 52) so the legacy data model doesn't shape the new code.
Sharing login between the old and new apps
Users don't care which app serves a page, so login and session must work across both. A user who signs in on a Web Forms page and is then routed to the new ASP.NET Core catalog shouldn't be asked to log in again. Microsoft's incremental migration approach is exactly this pattern: YARP as the facade in front of the old app, plus System.Web adapters that let the new app share authentication and session with the old one during the transition (Microsoft docs). Solve this before moving the first page, or the migration stalls on login.
Knowing when you're done
Track the share of traffic and features still served by the legacy system. The last few percent are often odd, rarely used features: decide deliberately whether to migrate, replace or retire each one, or the old system lives forever for one report.
Check yourself
Nothing is delivered until the end, the old system keeps changing, and undocumented behavior gets missed. Strangling delivers value and verifies each piece incrementally, with a way back.
A parallel run: send real requests to both, serve the legacy result, and log every difference. Switch only when differences are zero or understood.
Read the legacy tables temporarily, sync changes with change data capture into the new store, or move ownership of the data to the new service with legacy reading through it.
A routing layer in front of the legacy system, such as a proxy or gateway, that can send specific routes to new services while everything else still reaches the old app. Each extraction then becomes a routing change that's easy to roll back.
When no traffic reaches the legacy system and no data lives only there. Track requests and data reads per legacy route, retire them as they reach zero, and decommission the old system once it's fully unused.