Migrate from .NET Framework to .NET 5

.NET 5 has been available for some time now and .NET 6 will be released in late 2021, but perhaps your team is still using .NET Framework 4.7 or 4.8. You may have preferred to stick with what your team knows, or with the time-tested platform that has been around for decades, but .NET 5 presents a compelling case for those who haven’t made the jump yet. And while it may seem like a small jump in version numbers from 4.x to 5, .NET 5 is a major leap from .NET 4.x and a continuation of the all-new framework that started with .NET Core 1.0 through .NET Core 3.1 and is now the future for all .NET development.
Some of the benefits of migrating to .NET 5:

  • Built for performance, and getting faster with every release
  • It is the current framework that is being actively developed with regular performance, feature, and security updates
  • Using the current framework will mean that future upgrades to .NET 6, 7, and onward will be much easier than the migration from .NET Framework 4.x to .NET 5
  • Build and run cross-platform
  • Optimized project files for faster load and build times
  • Cloud-ready
  • Open source on GitHub
  • Command Line Interface (CLI) for general use and scripting tasks
  • Attract and retain developers who want to work with the latest technologies

Depending on the size of your application, this may be a larger undertaking than any framework upgrade you’ve done in the past, but it also holds greater potential for performance improvements than any prior .NET Framework upgrade. We have helped many clients make this migration, and we have refined the process to make it as painless as possible. Every project has its own constraints and dependencies, so your migration process may be slightly different and require additional steps, but most our .NET 5 migrations follow these steps:

Step 1: .NET Portability Analyzer

The first step in the migration is to analyze your current application to determine the amount of effort to expect when migrating to .NET 5. The .NET Portability Analyzer is a free tool that will analyze your assemblies and provide you with a report of APIs in your current application that are no longer supported. There is typically a path forward for code that uses APIs that are no longer supported, but these changes will require more effort than supported APIs that can easily be shifted to the new version of .NET.

Step 2: Evaluate Project Dependencies

Evaluate dependencies between projects and determine whether to upgrade library classes to .NET Standard or .NET 5. If all projects are being upgraded to .NET 5, then all projects can target .NET 5. In the case where you need to leave a project in .NET Framework and that project needs to reference an upgraded class project, you will need to target .NET Standard 2.0 instead of .NET 5. Refer to the .NET Standard implementation support page to determine what versions of .NET and .NET Standard are compatible with each other.

Step 3: Convert Class Libraries

Class libraries are typically the easiest project types to convert.  If they do not have any compatibility warnings in Step 1, it is very likely that you will be able to simply migrate all of the existing code to the new project structure. Before you start converting projects, ensure that you have the desired version of the .NET SDK installed.
When you are ready to migrate your projects, you can start with the Try Convert tool to see if your entire solution or individual projects can be migrated automatically. If that does not succeed, or if you want to convert them manually to have more control over the process, you can take the following approach:

  1. Create a new Class Library project in either the same folder (with a new project name) a parallel folder (with the same project name) using either Visual Studio (Add > New Project > Class Library), or with the CLI command dotnet new classlib -o <ProjectName>
  2. If using the same project name, replace the old csproj class file with the new csproj file that was just created
  3. Manage Nuget packages for the new project and add any missing packages that your code requires. You can also right-click on the packages.config file in Visual Studio and select “Migrate packages.config to PackageReference.”
  4. Delete files and folders that may no longer be needed such as the Properties folder and the packages.config file (now that your Nuget packages are now managed in the csproj file)
  5. Build the project and resolve any missing references or errors

Step 4: Convert ASP.NET Projects

There have been a lot of changes to how .NET Core and .NET 5 initialize and run ASP.NET projects, so this step tends to be more involved than migrating class libraries.
Similar to Step 3, you may be able to automatically convert your entire solution or the ASP.NET projects with the Try Convert tool. But if it does not succeed, or if you want to perform the conversion manually, you can follow these steps:

  1. Similar to Step 3, create a new ASP.NET project and use the type that fits your project: ASP.NET Core Web API, ASP.NET Core Web App, or even ASP.NET Core Empty if you want to start from scratch. Select “.NET 5” for your Target Framework.
  2. Review your startup code in Global.asax.cs. Any custom logic will need to be migrated to the new Startup class in .NET 5.
  3. Copy or move all of your existing controllers and classes into the new project structure
  4. Update existing API controller classes to derive from Microsoft.AspNetCore.Mvc.ControllerBase. You may want to create your own ApiControllerBase class that derives from ControllerBase and is decorated with the [ApiController] attribute. Controllers that need to provide MVC View support can derive from Microsoft.AspNetCore.Mvc.Controller.
  5. Resolve any Nuget or reference errors. You will likely need to adjust your using statements to account for changed namespaces in .NET 5.
  6. Migrate any Handlers to use .NET Middleware instead
  7. Migrate web.config settings to appsettings.json
  8. Clean up the old project and any unnecessary files, such as Global.asax, app.config, packages.config

Step 5: Porting Entity Framework 6 to Entity Framework Core 5

If you are using an older version of Entity Framework, this is a good time to at least consider whether you want to migrate to Entity Framework Core 5. Because there are significant changes between EF 6 and EF Core 5, Microsoft refers to this as a “port” rather than a “migration” and it is worth reviewing all of their considerations on the Porting from EF6 to EF Core page. If you do port to EF Core 5, you should plan to test your application to ensure it works and performs as expected. Some queries may need to be adjusted to align with how EF Core handles joins and split queries, and some aspects have changed that will need to be restructured, such as complex Group By queries.
Moving to EF Core 5 does have its advantages, and similar to the rest of the .NET 5 platform, every release adds new capabilities and performance improvements.
If you decide to move to EF Core 5, the typical migration steps are:

  1. If scaffolding or reverse-engineering your DbContext from a database using the EF Scaffold tool or EF Core Power Tools, set the DbContext target to EF Core 5 and regenerate your models and DbContext files. If you were using an EDMX file, you will need to generate a new DbContext and Models using a scaffolding tool. If you are using Migrations, there is no easy way to port the existing migrations. Instead, you will want to migrate your model to EF Core and then use Add-Migration to create a new starting point for future updates and migrations.
  2. If you are not using Dependency Injection, configure your Context by overriding the OnConfiguring() method
  3. If you are using Dependency Injection, call the IServiceCollection.AddDbContext() extension method in your Startup ConfigureServices method. You can set the connection string and other configuration options within AddDbContext.

Step 6: Review Dependency Injection

If you are already using Dependency Injection, you can likely continue to use the same DI framework. If you are not using DI at all, the migration to .NET 5 provides the perfect opportunity to start using the built-in Dependency Injection framework. Even if you are using a different DI framework, it may be worth considering making the switch to .NET Dependency Injection because of its excellent performance, and since it is a first-class citizen in .NET, it is very easy to adopt and use.

Step 7: Migrate to System.Text.Json

Similar to EF Core and DI, the migration to System.Text.Json for serialization and deserialization is an optional migration. If you are using Newtonsoft.Json currently, there won’t be complete feature parity in System.Text.Json, so it is worth reviewing the differences outlined here. But if System.Text.Json does provide all of the features you need, it is likely that you will see performance improvements by making the switch.
Here are our typical steps for migrating to System.Text.Json:

  1. Remove Nuget references to Newtonsoft.Json in your project(s)
  2. Build your solution and you should get build errors for everything that was using Newtonsoft
  3. Update using statements, typically removing Newtonsoft.Json and replacing with System.Text.Json
  4. Update serialization/deserialization syntax: SerializeObject() becomes JsonSerializer.Serialize() and DeserializeObject() becomes JsonSerializer.Deserialize()


Making the move from .NET Framework to the latest .NET platform can be a large effort, but it certainly has its benefits. Along with the immediate performance gains, you will once again be on the current .NET platform that will continue to improve over time.
We have helped many clients make this migration, so let us know if we can help!

Related Blog Posts

We hope you’ve found this to be helpful and are walking away with some new, useful insights. If you want to learn more, here are a couple of related articles that others also usually find to be interesting:

Manage Your Windows Applications With Winget

Winget, Microsoft’s native package manager for Windows 10 (version 1709 and later) and Windows 11, offers a streamlined CLI for efficient application management. This blog post introduces Winget’s installation and basic commands for installing, updating, and removing software. It highlights the tool’s ability to manage non-Winget-installed apps and explores curated package lists for batch installations. The post also recommends top Winget packages, noting some may require a paid subscription.

Read More

Our Gear Is Packed and We're Excited to Explore With You

Ready to come with us? 

Together, we can map your company’s software journey and start down the right trails. If you’re set to take the first step, simply fill out our contact form. We’ll be in touch quickly – and you’ll have a partner who is ready to help your company take the next step on its software journey. 

We can’t wait to hear from you! 

Main Contact

This field is for validation purposes and should be left unchanged.

Together, we can map your company’s tech journey and start down the trails. If you’re set to take the first step, simply fill out the form below. We’ll be in touch – and you’ll have a partner who cares about you and your company. 

We can’t wait to hear from you! 

Montage Portal

Montage Furniture Services provides furniture protection plans and claims processing services to a wide selection of furniture retailers and consumers.

Project Background

Montage was looking to build a new web portal for both Retailers and Consumers, which would integrate with Dynamics CRM and other legacy systems. The portal needed to be multi tenant and support branding and configuration for different Retailers. Trailhead architected the new Montage Platform, including the Portal and all of it’s back end integrations, did the UI/UX and then delivered the new system, along with enhancements to DevOps and processes.


We’ve logged countless miles exploring the tech world. In doing so, we gained the experience that enables us to deliver your unique software and systems architecture needs. Our team of seasoned tech vets can provide you with:

Custom App and Software Development

We collaborate with you throughout the entire process because your customized tech should fit your needs, not just those of other clients.

Cloud and Mobile Applications

The modern world demands versatile technology, and this is exactly what your mobile and cloud-based apps will give you.

User Experience and Interface (UX/UI) Design

We want your end users to have optimal experiences with tech that is highly intuitive and responsive.


This combination of Agile software development and IT operations provides you with high-quality software at reduced cost, time, and risk.

Trailhead stepped into a challenging project – building our new web architecture and redeveloping our portals at the same time the business was migrating from a legacy system to our new CRM solution. They were able to not only significantly improve our web development architecture but our development and deployment processes as well as the functionality and performance of our portals. The feedback from customers has been overwhelmingly positive. Trailhead has proven themselves to be a valuable partner.

– BOB DOERKSEN, Vice President of Technology Services
at Montage Furniture Services

Technologies Used

When you hit the trails, it is essential to bring appropriate gear. The same holds true for your digital technology needs. That’s why Trailhead builds custom solutions on trusted platforms like .NET, Angular, React, and Xamarin.


We partner with businesses who need intuitive custom software, responsive mobile applications, and advanced cloud technologies. And our extensive experience in the tech field allows us to help you map out the right path for all your digital technology needs.

  • Project Management
  • Architecture
  • Web App Development
  • Cloud Development
  • DevOps
  • Process Improvements
  • Legacy System Integration
  • UI Design
  • Manual QA
  • Back end/API/Database development

We partner with businesses who need intuitive custom software, responsive mobile applications, and advanced cloud technologies. And our extensive experience in the tech field allows us to help you map out the right path for all your digital technology needs.

Our Gear Is Packed and We're Excited to Explore with You

Ready to come with us? 

Together, we can map your company’s tech journey and start down the trails. If you’re set to take the first step, simply fill out the contact form. We’ll be in touch – and you’ll have a partner who cares about you and your company. 

We can’t wait to hear from you! 

Thank you for reaching out.

You’ll be getting an email from our team shortly. If you need immediate assistance, please call (616) 371-1037.