September 22nd, 2021 | by Paweł Łukasiewicz

Migrate to .NET Core from .NET Framework Painlessly – 4 Key Steps

Table of contents

If you have a .NET Framework application and you’re looking to migrate to .NET Core, then the one thing you should know is that this process is never straightforward. Numerous companies decide to migrate their legacy apps to .NET Core, and most have solid reasons to do so, but many also get lost in this process. The reason? Every migration process is different, and it’s usually complex.

That doesn’t mean you shouldn’t migrate at all. Applications created in older .NET Framework versions may be harder to maintain and generate more costs, so shifting to .NET Core, released only in 2016, may be the right direction to go. We’ve pinpointed four key steps that will help you understand the process and navigate the transition painlessly. In this article, we explain:

  • when migrating to .NET Core makes sense,
  • when it doesn’t make sense,
  • how to migrate your legacy app to .NET Core, and
  • what are the risks CTOs should be aware of before they begin the migration process?

Let’s get started!

When does migrating to .NET Core make sense?

Since the release of .NET Core in 2016, businesses relying on .NET Framework increasingly consider shifting their applications to this new technology because it offers a broad spectrum of benefits.

In contrast to .NET Core, .NET Framework will no longer be updated (although Microsoft does continue to support it), so this alone makes quite a compelling case for migration to .NET Core. The latter receives regular and more frequent updates (which means you will have to update it more often). It does seem like .NET Core is the future: it’s an open-source tool and continuously supports its development. However, if your .NET Framework application remains stable and functional, migrating to .NET Core isn’t a priority.

In what scenarios will moving away from .NET Framework to .NET Core be a step in the right direction?

When you’re looking for performance improvements

Since .NET Core is much younger than .NET Framework, it is safe to say that overall application performance is better in newer frameworks. It was built for performance, and every version is faster than the previous one, and it was built to benefit from asynchronous programming, making this technology faster than .NET Framework. Older technologies are by default slower, and many of them are no longer supported – indeed, Windows isn’t planning on any new releases of the .NET Framework. We can also expect cutting-edge and more effective security mechanisms.

When you want to benefit from cross-platform development

.NET Framework was created exclusively for the development of Windows applications. Although it became one of the most popular development frameworks, a solution that would allow for cross-platform development was needed, which is why Windows created .NET Core. We have already covered cross-platform development in the below posts:

.NET Core vs. .NET Framework – Which is a Better Choice for Your Next App?
When .NET Framework is the Best Choice for Application Development and Why?

When you rely heavily on WebForms

Many sources claim that you shouldn’t migrate when you rely heavily on WebForms. We disagree. Indeed – there is no automated way to migrate WebForms because .NET Core doesn’t support this technology, so it requires considerably more effort, expertise, and understanding of the tool to do it right. Nonetheless, it’s worth the effort, as applications relying on WebForms will sooner or later become outdated and continue to accumulate technical debt in the meantime. Often, the entire migration process is precisely about porting WebForms from .NET Framework to .NET Core.

When you (intend to) rely heavily on Dependency Injection

.NET Core/.NET 5 is equipped with a Dependency Injection framework that is easy to adopt and use – many software developers appreciate the excellent performance of this tool. If you don’t benefit from this functionality yet, moving your app to .NET Core is the perfect opportunity to do so. If you’re already using DI, you will be able to continue to use the same DI framework in most cases.

When you need to speed up development and improve deployment

Coding in .NET Core is much faster than in .NET Framework, so if you’re ambitious and intend to expand your application over a prolonged period, .NET Core is the right choice. It works with NuGet packages (pre-written code components), which saves a lot of development time. .NET Core also supports service-based architecture, enabling self-contained publishing and speeding up the deployment process.

When does migrating to .NET core make sense?


When migration to .NET Core doesn’t make sense?

Just because this technology is around doesn’t mean that you have to migrate your apps to this newer framework. If your application functionalities are stable with the legacy technology, shifting to .NET Core may be unnecessary. Businesses relying on .NET Framework should consider moving their applications to .NET Core primarily when it’s relevant to their business goals and context.

Consider when the process will undoubtedly be counterproductive:

When you’re using technologies that .NET Core doesn’t support

The migration process won’t work if you’re using libraries relying on app domains, remoting, and code access security. It’s impossible to create additional application domains, so you should opt for isolated processes as a replacement. Remoting can be substituted with inter-process communication. If your application works with Windows Management Instrumentation, Windows Registry, or other Windows-specific APIs, it won’t work with .NET Core.

When your application is Windows-specific

If your application requires WMI, Windows Registry, or other Windows-specific APIs, it won’t work with .NET Core. Besides, when you have a fully functional tool intended to run exclusively on Windows, the migration process will be counterproductive.

When migration to .NET core doesn’t make sense?


How to migrate desktop app to .NET Core?

The .NET Standard library (aka shared API), a subset common to both .NET Framework and .NET Core platforms, lays the foundation for the migration process. Smaller projects without dependencies can often be moved automatically simply by shifting from .NET Framework to .NET Standard. In the case of larger projects, however, automation is not an option.

The key to success is dividing the process into steps. We’ve identified four key stages that will help grasp the complexity of the process. As you begin migrating your application to .NET Core, we recommend starting with smaller projects and breaking the cycle down into smaller chunks as much as possible. Remember – every app will be migrated differently.

Four critical stages of the migration process we recommend

The first two stages are about preparation for the migration process. The remaining two are about actually migrating to .NET Core.

1. Make sure your code will run on .NET Core

The first stage is about verifying the code compatibility of the legacy app against the .NET Core (or .NET 5) specifications. Likely, some of the application libraries will work on .NET Core (especially if you work with Framework 4.7.2 or any earlier .NET Framework version), but some won’t. For instance, .NET Framework components generating .pdf files are often incompatible with .NET Core.

You can use the .NET Portability Analyzer to check which specific libraries won’t work. This free tool will yield a report of your Framework APIs that indicates the ones that are no longer supported in the latest versions of .NET. Software developers will have to change these specific APIs before migration. Remember to treat the report as initial guidance rather than a precise specification of the compatibility with .NET Core. Use .NET Portability Analyzer (you’ll find it in Visual Studio) to estimate the amount of effort required for this step and don’t rely on it exclusively. Follow up with thorough verification.

2. Decide on the architecture of the new application

At this stage of .NET Core migration, you need to decide on the form of the new application. Consider separating the backend and the frontend. Can development teams work independently on these as they migrate? Separation is possible when we work with Model View Controller (MVC) or with microservices. Additionally, should you support the legacy app? If so, it may have to be supported separately, depending on the nature of the project. Choose the migration type based on the architecture of your app and how it is developed and released.

.NET Core is an excellent option for creating Web API service for the backend and client-side libraries for the frontend in various technologies, such as Angular/React. It’s the best solution when scalability is our target and one of the top choices for web development among .NET software developers. It offers the ability to shift from traditional monolith apps to microservice-based architecture. This is currently one of the most popular technologies, as it is easier to manage and offers better performance.

Once you’ve decided on the application form, you can delve into migrating your WebForms, ASP.NET MVC, or Web API to .NET Core.

3. Move the models without dependencies

Once you’ve determined the type of .NET Core app you are about to create during migration, check project dependencies. You can use the .NET Upgrade Assistant for the process (also available in Visual Studio). It will display the dependencies and recommend the order of projects to migrate, which can be helpful when you need to tackle them in large numbers. Then, look at the components without dependencies – you should move these components first, one by one, starting with the elements in the lowest application architecture. The idea is to start with the more manageable tasks before moving on to what’s more complex.

4. Move the dependencies

Now, in the final step of this process, you need to move the projects with dependencies. If your application uses NuGet packages, update them to the latest versions. You can use the .NET Upgrade Assistant to automate the updates. Then, check if each NuGet package is compatible with the target framework. If you find that many of them use specific APIs supported only by .NET Framework, you may have to replace each NuGet package to enable framework migration.

How to migrate desktop app to .NET Core in 4 steps


Migration risks

The nasty truth is that migrating to .NET Core from .NET Framework is marred with numerous challenges and risks. Since there is no space to tackle them all in this article, we’d like to point out what, from our perspective, will be particularly pressing for most business cases.

Targeting wrong .NET platform

If migration to .NET Core wasn’t complicated enough, another thing that requires consideration is the target .NET platform. To make the right decision, you need to understand your business goals.

Consider the below recommendations from Microsoft:

  • If your goal is to move your app to .NET Core and support multiple platforms, your best choice is to target .NET Core.
  • If your goal is to make your library run on all .NET supported platforms, the recommended target is .NET Standard.
  • If your goal is to port your web app to .NET Core to support multiple platforms, the recommended target is ASP.NET Core.
  • If your goal is porting your app from .NET Framework to .NET Core on Windows, use .NET Core + Platform Extensions.
  • If your goal is porting your library from .NET Framework to .NET Core on Windows, use .NET Standard + Platform Extensions.

Prolonged conversion process

We’ve previously mentioned WebForms. It’s the trickiest aspect of migrating from .NET Framework to .NET Core, but one that will make the most sense from the business perspective. .NET Core does not support WebForms, and since .NET Framework will not receive any further updates, this technology will slowly but steadily become outdated.

The process of moving WebForms to .NET Core is referred to as porting rather than migration because it requires a total re-implementation of functionalities of these pages. Unfortunately, this process is genuinely complex and lengthy, but it allows you to redesign every page. This means you can create an entirely new and responsive design and offer a much better experience if your current technology is outdated.

There are two main approaches to migrating WebForms:

  • you can either rewrite the whole system, which is bound to slow down the development process significantly, or
  • migrate gradually by rebuilding the entire core library and then migrating every page one by one (this will require running two core libraries simultaneously).

Functionalities may have to be written upon request.

Since some libraries aren’t supported in .NET Core, migration may require coding certain functionalities from scratch. This will require software developers to understand how the app functions and what the API has to yield so that the programmers working on the interface know how to link those elements with the newly migrated projects. Of course, this process will involve extensive communication between the client and the software developers, and it may become a big project in itself.

.NET Core migration

We would be keen to give you a uniform scenario for migrating your project from .NET Framework to .NET Core, but we can’t do that. This process is far from quick and straightforward, even though both frameworks share common components from the .NET Standard library. Every migration process we navigated differed from another.

Navigating the migration requires technical expertise and a thorough understanding of the app functionalities and business goals. It must begin with a thorough examination of the code and individual projects and how they are interconnected. Preparation of files and libraries is an integral part of the migration process – one which may reveal that a specific component cannot be moved at all.

We hope that this text sheds some light on the intricacies of the process and helps you visualize what is involved. If you decide to migrate your application from .NET Framework to .NET Core with an external software development partner, check their experience within this domain and be prepared for surprises as the migration process unfolds.

Paweł Łukasiewicz

Senior .NET Developer / Blogger. On a daily basis, focused on cloud development. In my spare time, I am writing articles on various technology topics touching full-stack development lifecycle.