
The application was written years ago on .NET Framework, and it works. Orders go through it, the warehouse reads it, the certificates come out of it. The people who wrote it may have left; the people who maintain it are busy keeping it running. Somewhere there is a plan, written by your team or by an outside consultant, that says the application should move to modern .NET, and roughly in which order.
What there is not is someone to carry out that plan without stopping the business. Your team cannot set the day-to-day work aside for months, and the application cannot go dark for a weekend, let alone a month, while it is rebuilt. So the plan stays in a folder, and every year the application drifts a little further from the versions its libraries, its tools and the people who work on it expect.
This piece is about getting from that plan to a migration that runs in stages, each one small enough to test, to switch on and, if needed, to switch back, while the business keeps working. It covers when the move is due, why Microsoft’s own guidance favours an incremental migration for large applications, the groundwork that can be done in the old application before anything moves, how to cut the work into stages and put them in order, how a web application can run old and new side by side, what to do about the data, and how each stage is tested and switched on. The platform facts come from Microsoft’s documentation, which we list at the end.
If there is no plan yet, the first step is a different one: reading the code and writing the roadmap. We come back to that at the end.
Why move an application that still works
A working application is no reason to wait for ever, but it is not an emergency either, and it helps to know which of the two you are facing.
Where .NET Framework stands
According to Microsoft’s lifecycle FAQ for .NET Framework, version 4.5.2 and later are a component of the Windows operating system, and follow the lifecycle policy of the Windows version on which they are installed. The FAQ recommends version 4.8 to customers, and Microsoft’s support policy names 4.8.1 as the latest version, which will continue to be distributed with future releases of Windows. In Microsoft’s lifecycle table, versions 4.7 to 4.8.1 have no end date of their own: Microsoft supports them for as long as the Windows beneath them is supported.
Earlier versions have dates of their own. Microsoft’s support policy for .NET Framework gives 12 January 2027 as the end of support for version 4.6.2, and versions 4.5.2, 4.6 and 4.6.1 retired on 26 April 2022. Version 3.5 Service Pack 1 is, from Windows 10 version 1809 and Windows Server 2019, a standalone product with an end date of its own, in January 2029. What counts is the version installed on each machine that runs the application: 4.6.2 and later are in-place updates on top of the earlier 4.x versions, and Microsoft expects applications built for those to keep running on them without being recompiled. If a machine still has one of the retired versions installed, or a project still needs 3.5, its date belongs in the plan.
Where the pressure comes from
So for an application on version 4.7 or later, the date that matters is that of the Windows beneath it. Microsoft’s overview of upgrading .NET apps names the signals that bring the move forward: .NET or other dependencies reaching end of support, new security vulnerabilities or new compliance requirements, and performance or scalability limits that newer versions address. In an application written a decade ago, we would also look at what surrounds the code: a library that has no release for modern .NET, a component that only installs on an old version of Windows Server, a development tool that new staff have never used. And we would add a human signal. The fewer people know the old code, the more each change to it costs, and the longer each one takes.
Which modern .NET to aim for
Modern .NET has a new major version every year, alternating long-term support (LTS) and standard-term support (STS) releases; according to the same overview, an LTS release is supported for three years. Microsoft’s lifecycle page for .NET gives 10 November 2026 as the end date of both .NET 8 and .NET 9, and 14 November 2028 as that of .NET 10, the current LTS release when this piece was written. At that time, Microsoft’s porting overview still advised considering .NET 8 as the target. With that end date, a migration planned now aims at .NET 10, and plans for the move to the next LTS release when it comes. Once an application is on modern .NET, moving from one release to the next is, in Microsoft’s words, usually smaller in scope: mostly the target framework, the dependencies and the breaking changes between the versions.
One big move, or many small ones
For a web application, Microsoft’s guide to migrating from ASP.NET Framework to ASP.NET Core is plain about the difficulty: the update is non-trivial for the majority of production apps, which often carry many legacy decisions. Its quick decision guide asks three questions. If the application must stay in production during the migration, the answer is an incremental migration; if you can afford a complete rewrite, the guide points to a migration in place. Small and medium applications can be migrated in place; for large production applications, an incremental migration is safer. And unknown or out-of-date dependencies, or heavy use of System.Web, point to an incremental migration too.
The same guide says that an incremental migration is an implementation of the Strangler Fig pattern, and Microsoft’s Azure Architecture Center describes that pattern. A façade, in practice a proxy, sits between the users and the old system, and routes each request either to the old application or to the new one. At first it sends all or most requests to the old application. With each iteration, more functionality is implemented in the new one, and the façade sends it more of the requests. When nothing depends on the old system any more, it is decommissioned; in the end the façade itself can be removed, and the users reach the new system directly. Throughout, they keep the same interface, and need not know that a migration is under way.
The pattern has limits, and the same page lists them. It may not suit a system whose requests cannot be intercepted; a legacy system whose code you cannot reach and that offers no other integration point you can change, such as its database; a small system that is simple to replace whole; or a case where the original has to be decommissioned quickly. Where none of those applies, the incremental route is the one that lets the business keep working while the application changes.
Not every application is a website. Microsoft’s porting overview notes that projects whose app model exists in modern .NET, such as libraries, console apps and desktop apps, usually need little change, while projects that need a new app model, such as moving from ASP.NET to ASP.NET Core, need more work. Windows Forms and WPF are available in modern .NET, although they remain Windows-only. A desktop application usually has no requests a proxy could intercept, so the pattern may not suit it. Its libraries can move one at a time to .NET Standard 2.0 while it still runs on .NET Framework, and moving the executable itself to modern .NET is then a stage of its own, with the previous version kept ready on every workstation. The sections on stages, data and testing apply to it all the same; those on the proxy and the System.Web adapters do not.
What a stage is
A stage is a piece of the migration small enough to be tested, switched on and switched back on its own, that leaves the application working. Before it starts, four things about it are written down.
What moves
Which part of the application moves to modern .NET, named precisely enough that anyone can tell afterwards whether it did: these screens, these web addresses, this library, this batch job.
How it is tested
Which cases are run, by whom and against what result. The cases come from the work of the people who use the application, not only from the developers.
When it is switched on
The agreed moment, chosen when a problem would hurt least, and the person who agrees it.
How it is switched back
The steps that put the previous version back, the data included, and the one person who decides to take them.
A stage that cannot be switched back is not a stage: it is a jump. A stage whose tests nobody from the business runs is a technical exercise. And a stage that does not leave the application working is half of something else. Those four points are what keep a stage from stopping the business. Every stage keeps a way back, even when the data makes it harder; the only step planned with none is the last, retiring the old application and its data, which the section on data comes back to.
The plan you already have probably lists components and an order. Turning it into stages means writing those four points for each item. Some items will split, because they cannot be tested or switched back in one go; a few will merge. Only the first stage needs to be written in full before work begins: each later one is written with what the previous one taught.
Stage zero: the groundwork that moves nothing
Before any part of the application moves, Microsoft’s porting guidance lists changes that are made while the application still builds and runs on .NET Framework. They are meant to change nothing the users see, but retargeting and package updates can change behaviour, so each one is tested and released in the old application on its own.
Retarget to .NET Framework 4.7.2 or later
Microsoft recommends retargeting the projects to version 4.7.2 or higher before porting, so that the latest API alternatives are available where .NET Standard does not support existing APIs.
Move to the new project format
Package references move from the old packages.config file to PackageReference, and the project files to the SDK-style format. Microsoft recommends the new format even for a project that cannot be ported yet, because the format also works with .NET Framework and gives a good basis for porting later. For an ASP.NET web project, NuGet’s documentation notes that Visual Studio’s migration from packages.config is not available, and Microsoft’s incremental guide only asks you to consider the move in the web project.
Update the packages, one at a time
Microsoft’s guide to the incremental migration of ASP.NET asks for packages to be updated one at a time, with a test after each update, and for the breaking changes some updates bring to be dealt with as they come. For an ASP.NET Framework application, it notes that the audit is done with Visual Studio’s NuGet Package Manager, because the dotnet command-line tool does not work for those applications.
Clear the technical debt
The same guide lists the rest of the work worth doing first: compiler warnings, especially those about deprecated APIs; dead code; deprecated APIs that have modern equivalents; unused references; and the build scripts and CI/CD configurations that assume the old project format.
Stage zero is unglamorous, and it is often where the first surprises appear. It is also the stage with the easiest way back, because everything in it still runs on the old framework.
What blocks the move: dependencies and technologies
Two kinds of obstacle decide how hard each later stage will be, and both can be listed before the first of those stages starts.
Libraries you did not write
Microsoft’s porting overview says that dependencies must target .NET, .NET Standard or .NET Core. Its page on analysing dependencies explains how to check a NuGet package: nuget.org shows the target frameworks a package supports in its Dependencies section, although not for every package, and the NuGet Package Explorer shows the folders inside a package, where names such as netstandard2.0 or net8.0 mean a version that works with modern .NET. Often a newer version of the package already does.
A package that only targets .NET Framework may still work. Since .NET Standard 2.0, a compatibility mode lets modern projects reference .NET Framework libraries, and the build warns about it, with warning NU1701, every time. Microsoft is clear that this does not work in every case, for example with a library that uses WPF, and that you should test the project to make sure it also works at run time. A library that is only referenced this way is a risk to write in the plan, not a problem solved.
Technologies that did not make the move
Some technologies of .NET Framework do not exist in modern .NET, and Microsoft lists them. Creating further application domains is not supported, nor is .NET Remoting. Code access security and security transparency are not supported as sandboxes. System.EnterpriseServices, that is COM+, is not supported, nor is Windows Workflow Foundation, for which Microsoft points to CoreWF as an alternative. XSLT script blocks and assemblies made of several modules are not supported either. A WCF server, on the other hand, can run on modern .NET through the CoreWCF packages, and saving assemblies generated with System.Reflection.Emit came back in .NET 9.
Many APIs that depend on Windows were not carried into .NET Standard either, such as the registry and Windows Management Instrumentation. The Windows Compatibility Pack, the Microsoft.Windows.Compatibility package, gives access to them, which Microsoft describes as especially useful when an application moves to modern .NET but stays on Windows, at least as a first step.
Each unsupported technology on that list that your application uses is a stage of its own, or a part of one, because it is not ported: it is replaced. Knowing which ones you have, and where they sit in the code, is what turns a plan into a timetable.
The order of the stages
Microsoft’s guide to the incremental migration gives the technical order, and your business gives the rest. For a web application, the guide puts a new application in front of the old one first, as the next section describes, and clears the technical debt after it. We clear it first, as stage zero, because work done in the old application has the easiest way back. Once the new application is in front, the following come next.
Cross-cutting concerns first
Session state, authentication, logging, caching, error handling, configuration, health monitoring and dependency injection span the whole application, and while old and new run side by side, those your application uses have to work across both. The guide deals with them early, before the supporting libraries are upgraded. Session is its example: a feature with the same name in ASP.NET and ASP.NET Core, but with very different APIs.
Libraries from the leaves up
Supporting libraries are upgraded in what Microsoft calls postorder depth-first order. You start with the libraries that depend on no other library of your solution, upgrade a library only once every library it depends on has been upgraded, and end with the main application. Microsoft recommends .NET Standard 2.0 for these libraries where possible, so that old and new applications can both use them; where that is not possible, a library can target .NET 8 or later alongside its .NET Framework target. And because the migration is incremental, you upgrade only the libraries the part you are migrating needs, not the whole solution at once.
The System.Web adapters
Many libraries of an ASP.NET application pass HttpContext around. Microsoft’s System.Web adapters let such a library be used from both ASP.NET Framework and ASP.NET Core callers, which is exactly the in-between state a staged migration lives in. To use them, a library drops its reference to System.Web, adds the Microsoft.AspNetCore.SystemWebAdapters package, and either gains a .NET 8 or later target alongside its old one or is converted to .NET Standard 2.0; then it is recompiled.
Then the parts the business sees
For the first parts that move, Microsoft’s advice is to begin with simple, stateless endpoints. Your plan adds the business order. Microsoft’s overview of upgrades suggests prioritising by risk and return, and piloting the changes on a low-risk project first. In practice that means a first stage small enough that a failure would not hurt, followed by stages that pay for themselves early: the part that changes most often, or the part whose dependency is closest to its end.
Two applications side by side
For a web application, the staged route has a concrete shape in Microsoft’s documentation. A new ASP.NET Core application is created alongside the existing one, and configured to proxy requests to it with the YARP reverse proxy. A fallback route forwards every request the new application does not handle yet to the old one. In this setup the new application is itself the façade, and removing the façade at the end means removing that fallback route. Each stage moves some of the routes into the new application; everything else keeps going where it always went.
Putting the new application in front of the old one is itself the first switch-over, and it is planned like a stage: tested, switched on at an agreed moment, with a way back to the old address. The documentation adds points that are easy to miss when planning:
- The two applications must use identical virtual directory layouts.
- The old application should run with SSL, and be reachable only through the proxy.
- The two applications share an API key, and the new one knows the old one’s address.
- Session and authentication can be shared, the new application deferring authentication to the old one.
The Strangler Fig page adds considerations of its own. Old and new may use the same services and data stores, and both must be able to reach them at the same time. The façade has to keep up with the migration, and must not become a single point of failure or a performance bottleneck; Microsoft’s incremental guide also asks you to watch for any performance impact of the proxy. And while the two coexist, each may need to call the other: an anti-corruption layer, an adapter that translates between the two, keeps the new system from inheriting the old one’s conventions.
The data: what makes going back hard
Moving code can be undone, because the previous version can be put back. Data is what makes a switch-over hard to undo.
As long as old and new read and write the same database in the same shape, going back from a stage means sending its requests to the old application again. The difficulty starts when a stage changes the data: a new table, a column with a new meaning, a record the old application does not understand. From the moment the new version writes in the new shape, going back requires either that the old application can read what the new one wrote, or that those records are converted back into the old shape.
That is why the way back is written before the stage starts, data included, and why a stage that changes the data is planned on its own, not tucked inside one that moves code. Microsoft’s Strangler Fig page shows the same problem at the scale of a database, one domain at a time. The data of each domain is loaded into a new database and kept in sync with the old one by change data capture. Going back is possible while the old tables and the synchronisation still exist; once they are removed, it means restoring them and replaying the changes, which, in Microsoft’s words, significantly increases effort and risk. The page’s advice is to treat the removal of legacy objects as a deliberate final step, taken only after the new system is validated. The same holds for the old application as a whole: retiring it is the last step, and the only one planned with no way back.
Testing a stage, and switching it on
A stage is tested twice: by the developers, with automated tests, and by the people who use the application, on cases from their own work.
The first kind of test tells you the code behaves as it did. The second tells you the business can work with it. The people who enter orders or issue certificates every day know the cases that matter: the customer with an unusual tax status, the order changed after it had shipped, the certificate for a part made at two plants. A stage is ready when they have run those cases on the new version and found the same result as on the old one. If real records are copied into the test environment to do it, that copy is treated with the same care as the original. Microsoft’s guide makes the technical half of the same point: test thoroughly, so that each migrated component works correctly in both environments.
Switching on is a moment, not a period. It is agreed in advance, at a time when a problem would hurt least: before the shops open, at a change of shift, after the monthly invoicing run. With a proxy in front, switching on is a change of route, and switching back is the same change in reverse, followed by whatever the data part of the way back says. Someone watches the new version through its first hours with the way back at hand, and the person named in advance decides whether to use it.
Tools, and what they do not decide
Microsoft now recommends its GitHub Copilot app modernization agent for upgrades: it analyses the projects, writes an upgrade plan you can adjust, and can carry out many of the steps. The .NET Upgrade Assistant is, in Microsoft’s words, officially deprecated in favour of that agent and no longer actively developed. The platform compatibility analyzer finds calls to APIs that throw a PlatformNotSupportedException at run time.
Tools of this kind can save much of the mechanical work: project files, package references, deprecated calls. They do not decide what a stage is, when it is switched on, how it is switched back or who tests it. Those decisions are the plan, and they stay with the people whose business runs on the application.
An example: certificates first
Here is how it can look, as an example. The company is imaginary, like the examples on our pages.
An automotive parts maker in Italy has a plant in Mexico. Its quality system, a web application, records the checks of both plants and produces the certificates its customers ask for. It is written in an old version of .NET and depends on components that are no longer updated. Between the plant in Italy and the one in Mexico, which works in shifts, the system is in use at all hours. The company already has its roadmap: first the certificates, then the recording of the checks, and the screens last.
Before stage zero, the inventory of dependencies finds one library, the one that lays out the certificates, with no version for modern .NET. It is left as it is for now: replacing it is part of the certificates stage. Stage zero then retargets the projects, converts the libraries to the new format, and the web project where that can be done, and updates the packages one by one, all in the old application, which keeps running throughout. Then the new application goes in front of the old one, forwarding every request to it, and is switched on at a change of shift like any other stage. Next, it is set to defer sign-in to the old application, so that users are recognised by both.
The certificates come first because the company’s roadmap puts them first, and they suit a first stage: they are produced from data the system already holds, so moving them changes no data, and a certificate that comes out wrong is issued again from the old application. The way back is simple: send certificate requests to the old application again. The quality staff of both plants produce certificates for real checks, copied from the system in use, on the new version and on the old, and compare them. The stage is switched on at the agreed change of shift, with someone at each plant looking at the first certificates.
The second stage, the recording of the checks, is the one that writes data. Its plan keeps the records in the shape the old application reads, so that the stage can be switched back, and switching back is one of the cases it is tested with; any change to that shape is a later stage of its own. The screens come last, when nothing behind them is left on the old framework.
Before each stage, plant management knows what it includes, what it costs and on what date it ends. After any of them, the company can stop, with the application working.
Where to start this week
None of this needs an engagement to begin. These steps can be taken with your own team, and all of them are useful whoever carries out the migration:
- Find the plan, and write down who owns it.
- List each project’s .NET Framework version, and the Windows versions it runs on.
- List the packages and libraries, and check which have versions for modern .NET.
- Search the code for the technologies Microsoft lists as unavailable.
- Choose a candidate first stage, and write its four points.
How we do it
This is the work of our staged .NET migration. We start from your plan, or from the one produced by our .NET modernisation roadmap, and before starting we write down the first stage: which part of the application moves to modern .NET, how it is tested, its price and its date. We work on a separate copy, without touching the application the business uses. When the stage is ready, we test it with your team on real cases and switch it on at the agreed moment, with a plan to go back to the previous version, data included, if anything goes wrong. Then, and not before, we write the next stage, with what the previous one has taught us.
You receive the application migrated stage by stage, with the tests of each stage. Each stage is bought separately, at a price written down before it starts, and you can stop after any of them with the application working. The code, the accounts and the documentation are in your name.
If you have the plan and no one to carry it out, start with a free one-hour video call: tell us what the application does, what the plan says and when the application cannot stop, and we will tell you what we would look at for the first stage.
The sources we cite
- Microsoft, Overview of upgrading .NET apps and Overview of porting from .NET Framework to .NET.
- Microsoft, Prerequisites to porting code and Analyze your dependencies to port code from .NET Framework to .NET.
- Microsoft, .NET Framework technologies unavailable on .NET and Use the Windows Compatibility Pack to port code to .NET.
- Microsoft, Migrate from ASP.NET Framework to ASP.NET Core and Get started with incremental ASP.NET to ASP.NET Core migration.
- Microsoft, Remote app setup and System.Web adapters.
- Microsoft, Azure Architecture Center, Strangler Fig pattern.
- Microsoft, Migrate from packages.config to PackageReference.
- Microsoft, .NET Framework support policy.
- Microsoft, lifecycle pages for .NET and .NET Core and .NET Framework, and the .NET Framework lifecycle FAQ.
What we do about it: Staged .NET migration