How to Convert .NET Framework to .NET Core: Migration Guide

.NET Core gained instant popularity among software developers when Microsoft launched it for the first time on June 27, 2016. Today, 55% of developers prefer it to .NET Framework because it makes it easier to build software that can be deployed across multiple environments.

However, as with any technology change, moving an existing app from .NET Framework to .NET Core can be pretty daunting. And while there are many reasons why this may be beneficial, you should thoroughly understand what’s involved in migration before you take the plunge.

In this post, we’ll discuss how to convert .NET Framework to .NET Core and what you should keep in mind during the process.

Why Is Migration from .NET Framework to .NET Core Relevant?

The .NET Framework has been the default environment for Windows desktop, web, and server applications for over 19 years. It’s a great environment, but not perfect. The biggest problem with .NET Framework-based projects is that they are tied to Windows. That’s fine if you only want to run your application on Windows machines, but it inherently limits the options if you want to run your app on Linux or macOS.

While it cannot be denied that there are advantages in using .NET Framework, there are quite a few limitations. 

For example:

• There is limited support for object-relational (OR) in .NET since it comes with only Entity Framework.

• Microsoft controls the future development of the .NET Framework due to its vendor lock-in.

• Compared to C, C++, .NET Framework has low performance and is not suitable for high-end applications.

• Even though .NET Core is a .NET Framework successor, the transition to .NET Core is complex.

The last point is especially important as .NET Core is considered the future of .NET development. In fact, according to the official announcement from Microsoft, new applications should be built on .NET Core starting from 2019. As of 2023, the newest .NET releases are .NET 7, which shipped on November 2022, and .NET 8 features, which will be officially released in November 2023.

In What Cases .NET Framework to .NET Core Migration Makes Sense

Should you migrate from .NET Framework to .NET Core? When it comes to migrating to .NET Core, it’s not a case of if you should, but when. Of course, there are still many applications that run smoothly on the .NET Framework, and in some cases have been doing so for years. So why would you want to mess with that?

There are quite a few reasons why you would want to migrate your current application infrastructure to .NET Core. The most important reasons, though, are:

When you’re looking for performance improvements

Because of its modular structure, .NET Core makes it easier to access specific features without having to use the entire framework. This allows developers to implement only those features they need, resulting in faster performance. Therefore, if you are trying to improve performance, then migrating your code to .NET Core should be among your strategic steps.

When you want to benefit from cross-platform development

Another great reason to migrate your application to .NET Core is that it will now run on Linux or macOS. This opens up a whole new range of possibilities of where you can run your application. You can run it on Linux servers or even on a Raspberry Pi!

When you want to get an open-source codebase

The best thing about .NET Core being open source is that anyone can contribute to its development, which results in seamless bug fixes and swift, constant deployment of feature upgrades. This means that if you find an issue with any part of the framework, you can easily fix it in-house, or hire a professional to get the job done. 

When you strive for simpler package management 

NuGet has been a great thing for .NET developers, but it can be complicated at times. Packages can have dependencies on other packages, and if those packages have different versions of the same libraries. In other words, they might not work together. Core has a new package manager that makes this easier.

While there is no urgent need to port .NET Framework to .NET Core, it looks as though the latter is the framework of choice for the future. So, if you are thinking of moving, and you don’t have a qualified in-house team, be sure to look for a company that offers desktop migration services, legacy software updates and cloud services. This is the only way to guarantee a seamless transfer.

The comparison table: Difference between .NET Framework and .NET Core

As you can see from the table above, .NET Framework is a mature, stable, and reliable technology that businesses can leverage for a wide variety of applications. There are, however, some cases where using the .NET Framework can be a better option. This is especially true if your application fully relies on libraries and packages that are not supported by .NET Core, your business needs are already met, and your resources are limited.

Check the detailed .NET Framework overview from our team. Assessing .NET Framework: Advantages, Disadvantages, and Support Status

How to Migrate to .NET Core from .NET Framework – 5 Key Steps

Converting .NET Framework to .NET Core is an important decision that can positively impact your application’s performance and maintenance in many ways. In this section, you will learn the key steps to making the move.

First, it is important to point out that there are two approaches to migrating your project – automatic and manual.

How to not get lost in the modernization approaches to legacy solutions in 2024 and on? Read our guide Legacy System Modernization Approaches: Practical Advice on Dealing with Outdated Software

Migrating Automatically

Migrate using .NET Upgrade Assistant

To change from .NET Framework to .NET Core automatically, you can use the .NET Upgrade Assistant. This tool analyzes an existing .NET Framework application and provides recommendations for migrating its projects to target .NET Core. 

The Upgrade Assistant also tracks compatibility issues as it transforms the application. The report generated by the Upgrade Assistant can be used as a starting point for migrating an application from .NET Framework to .NET Core.

Migrating Manually

Here is a step-by-step process on how to migrate from .NET Framework to .NET Core manually: 

1. Analyze Project Dependencies

Before you start with the migration process, you need to analyze the system background, your code and dependencies. Microsoft has provided .NET Portability Analyzer, a tool to analyze your application dependencies and project references. This tool also helps you to identify the APIs that are not available in .NET Сore.

The tool is available as a Visual Studio extension and NuGet package. 

In case you discover NuGet dependencies that are not compatible with .NET Core, there are some approaches you can take to proceed with the migration: 

• Contact developers and ask them for support. Remember that .NET Core is open-source and developers are volunteers, which is why you should be mindful of their time and efforts;
• Visit nuget.org and search for a package that fulfills similar functionality as the one you are using now;
• If possible, try to write a code that will accomplish the same tasks as the package itself. 
• New versions and new features keep being released; therefore, you can simply wait until the day of the release and not use some app functionality until then. Contact the .NET team to let them know which library you would like to use.

2. Migrate from ASP.NET MVC

Since this migration is the easiest step, many companies choose to start with it. The good news is that the process is relatively quick and easy thanks to the comprehensive Microsoft guidance.

The steps for this are:

• The first step is to create a new ASP.NET project using the type that suits your project best: ASP.NET Core Web API, ASP.NET Core Web App, or even ASP.NET Core Empty if you are starting from scratch. Make sure that your Target Framework is “.NET 5”.
• Ensure that your Global.asax.cs code is up-to-date. .NET 5 requires migration of any custom logic to the startup class.
• Transfer all existing controllers and classes to the new project structure.
• Update your API controller classes. They should derive from Microsoft.AspNetCore.Mvc.ControllerBase. It may be a good idea to create your own ApiControllerBase class that derives from ControllerBase and is decorated with the [ApiController] attribute. Microsoft.AspNetCore.Mvc.Controller provides support for MVC Views, so such controllers are typically derived from this class.
• Fix all Nuget and reference errors. Namespaces have changed in .NET 5, so you will probably need to adjust your using statements.
• If you use Handlers, convert them to .NET Middleware.
• Move web.config settings to appsettings.json.
• Get rid of old projects and any unnecessary files, such as Global.asax, app.config, and packages.config

3. Migrate from WebForms

One major drawback of .NET Core is that WebForms are not supported. This is why instead of calling it a migration, moving WebForms is called porting from .NET Framework to .NET Core.

How to move your WebForms app to ASP.NET MVC smoothly? Explore our approach. Migrating from ASP.NET Webforms to ASP.NET MVC in 6 Steps

4. Move Your Project File

You can migrate your old project to the Core project using the ‘dotnet migrate; command, which migrates the project.json and any other files that are required by the web application.

The dotnet migrate command will not change your code in any way. It will just update your project file to use the new SDK-style project format (i.e. csproj).

5. Test Run your Application on .NET Core

Once you’ve migrated your application it should run on any supported operating system. The final step in migrating your application should be to test running your current application on .NET Core. Run your application on .NET and if it works, congratulations! You’re ready to go.

How to test a legacy codebase without breaking anything? Learn here. Testing Legacy Codebase: What is, Common Problems and Best Practices

To sum up, it is important to point out here that some apps cannot be migrated through automation tools because they are large and clunky, especially enterprise systems. This is where a legacy software expert like ModLogix comes in.

We can work with you to migrate your application to the latest .NET Core seamlessly and easily so that you too can begin to enjoy the many benefits of the .NET Core framework.

.NET Framework to .NET Core Migration Challenges to Keep in Mind

Although upgrading .NET Framework to .NET Core comes with a ton of business benefits, such as improved performance and deployment flexibility, there are some challenges that you need to keep in mind before and during implementation of the project. For instance, you need to pay attention to: 

API Compatibility

Although prevalently used libraries support both frameworks or provide compatible alternatives, your team might still find it challenging to integrate APIs that are not supported in .NET Core. You can solve this challenge by using Microsoft’s API Portability Analyzer (APA) to identify potential issues during migration and remediate them.

Platform Dependencies

Platform dependency is another big challenge for .NET Famework to .NET Core migration projects. Platform-specific dependencies in applications built by .NET framework may vary, but prevalent ones include third-party components or system-level integration points such as Windows Registry access or COM interop calls.

One way of solving this challenge is by doing away with the dependencies altogether, especially if they are unnecessary for core functionality. However, if you cannot replace or do away with certain dependencies, you might want to explore conditional compilation techniques along with build configurations, specifically customized for each target platform. 

Code Refactoring 

Upgrading to .NET Core from .NET Framework comes with new behavior patterns, causing differences between the APIs of the two frameworks. For example, .NET Core might lack certain classes or methods, prompting you to rewrite the sections of the code that apply to them. In other words, refactoring the existing code is necessary. 

Refactoring challenges can be addressed in several ways, including adoption of modern coding practices like async/await patterns or dependency injection. You can also use .NET Core’s exceptional handling technique to refactor the codebase while preserving key functionalities. 

Testing Strategy 

Testing is one of the most overlooked .NET Framework to .NET Core migration challenges. Usually, a typical migration project requires extensive testing to validate the application’s functionality and stability when deployed across different platforms. In addition to leveraging the existing unit tests, developers might also need to conduct compatibility testing, especially if they are going to identify and remediate platform-specific issues emanating from the migration process. 

You can circumvent this challenge by creating comprehensive test suites for every support runtime environment and operating system. Alternatively, you can leverage specialized testing frameworks that offer extensive cross-platform support, such as NUnit or xUnit.

Technologies That are Not Supported by .NET Core

There are quite a few technologies that are not supported by .NET Core, so you probably will have trouble with them during migration. Pay close attention to the main components and tools: 

• Application Domains

Application domains were used to provide isolation between different applications running in the same process. Since processes provide isolation between different applications in .NET Core; application domains are not supported. The new AssemblyLoadContext class is recommended for dynamically loading assemblies.

• Remoting

.NET Remoting is a .NET technology that enables applications to communicate with each other. It basically allows remote components to communicate across application domains.

Although remoting is a powerful technology and can be leveraged in many use-cases, it’s not available as a part of .NET Core, because as we already know, AppDomains are not a part of the .NET Core. As an alternative to remoting, you can use web services or make use of other inter-process communication technologies such as gRPC instead.

• Code Access Security (CAS)

Code access security (CAS) was a security feature of .NET Framework-based applications. It was based on code groups that had a set of permissions associated with them. In .NET Core, CAS isn’t supported by default. However, you can still specify permissions for assemblies using the following options.

When is it time to migrate a desktop Visual Basic app to the modern .NET technology? 3 Approaches for Safety Migrating a VB.NET App to a Web App

1. Use role-based security to secure your application. 
2. Use resource-based security for finer-grained control over your application. 
3. You can also use an external authorization service that performs centralized authorization for your application. 

• LINQ2SQL

LINQ to SQL is a component of the .NET Framework that provides a run-time infrastructure for managing relational data as objects.

LINQ to SQL fully supports transactions, views, and stored procedures. Because LINQ2SQL is a .NET Framework component, .NET Core does not support it at all. You will have to use Entity Framework Core to get similar functionality.

How to Prepare Your System for .NET Framework to .NET Core Migration

As you may already know, .NET Core is a popular open-source, cross-platform, and high-performance framework for developing web applications. However, .NET Framework to .NET Core migration is not as easy as it seems. Still, you can make the move without too much trouble if you follow this 3 step process.

1. Implement the Model Binder

When you migrate a desktop app to .NET Core, the way you handle form data may need to change. The model binder is a powerful component that can automatically map data from HTTP requests to action method parameters.

To simplify the process of .NET to .NET Core migration, use model binding.

2. Leverage on APIs and Client-Side Development

You should use more APIs to build applications and be more client-oriented. Also, if you want to make your apps more accessible, build them on Angular or React — newer frameworks that are less dependent on WebForms and easier to port.

3. Create .NET Standard Libraries

Another crucial process of migrating an existing codebase to .NET Core is by creating .NET standard libraries. This will allow you to know if the same code can be used in both a .NET Framework application and a .NET Core application. It also allows you to start migrating the code without having to redeploy the entire application.

Did you know that IdentityServer is changing its license policy? In 2022, the free trial is over What is Wrong with IdentityServer4 and What Alternatives to Choose?

Why Choose ModLogix for Your .NET Framework to .NET Core Migration?

If you are thinking that the time is right to move from .NET Framework to .NET Core, you are on the right page. ModLogix is a company that specializes in upgrading legacy systems and specifically .NET Core migration services.

Our goal is to help our customers upgrade their existing applications and take advantage of the latest technologies and architectures, while also improving quality and maintenance. 

We help companies take their old and outdated software systems and modernize them. Our approach allows you to increase software performance, maintainability and scalability while reducing development costs.

Case Study

Migration from ASP.NET MVC to .NET Core

AA is a SaaS solution that tracks Medicare, Medicaid, and HMO changes. AA also helps healthcare facilities prevent billing problems and speed up collections.

AA had a shortage of IT personnel to maintain their legacy software interfaces. So they approached us to help them switch from .NET Framework to.NET Core.

Our Solution

• The ModLogix team first conducted an analysis of NuGet packages to identify which ones were supported by .NET Core and which ones were not.

• Since AA’s app navigation relied on the MvcSiteMapProvider plugin, which is not compatible with .NET Core 3.1, our team devised a custom method to address this issue.

• Because we understand the importance of clean code at ModLogix, we eliminated plugins that were either useless or duplicates.

Moving a legacy software to the new platform: rehost, rebuild, or rewrite. Read our tips to make the right choice: Should You Rehost, Rebuild, or Rewrite a Legacy Application With Latest Software?

• Additionally, we changed the storage structure to meet the new .NET standards. 

• We then moved the site’s components to the new platform. Next, we reorganized and separated Bootstrap and Metronic frameworks from bespoke CSS styles, JS scripts, jQuery plugins, and other components.

The Result

The client used the new .NET Core 3.1 framework, which has long-term support and makes it easy to move to a new system in the future. Also, AA was able to cut the cost of each transaction by more than 300 percent and speed things up a lot. 

Read more about this migration by accessing the full case study report here.

As the business world is becoming more and more digitized, companies are constantly seeking solutions to minimize their operational costs.

Our application modernization services at ModLogix are customized to meet your needs and budget. Contact us and tell us about your system and we’ll be glad to provide you with a cloud migration cost estimate for your project. 

Final Thoughts

No matter how you look at it, the future of .NET is the new unifying Microsoft Development Platform, .NET 7, 8 and further. It offers better performance than its predecessors. It’s also a cross-platform framework, making it easier to develop, test, and deploy applications on multiple operating systems.

To upgrade from .NET Framework to .NET Core can be daunting for some developers, which is why you need the help of software modernization experts to point you in the right direction. Get in touch with us at ModLogix and see how we can work with you to create a migration strategy that you will be happy with.