Ready to migrate to .NET 10? Check SSW's .NET 10 Migration consulting page.
Migrating from .NET Framework (4.x) to the latest version of .NET brings huge advantages to your app's performance, hosting fees, and maintainability. But it's important that you understand what the road to migrating to the latest .NET will look like for your app before you start breaking things! So how do you ensure your migration is being done the right way?
With outdated NuGet packages, C# styling and architectures, keeping our .NET Framework applications up to date can be a pain. Especially when we want to make the leap from .NET Framework to .NET for that juicy performance and compatibility bump.
Luckily Microsoft provides excellent tooling for supporting your great leap into the latest version of .NET.
The differences between a web app built with ASP.NET Framework and one built with ASP.NET Core are immense. The entire request pipeline underwent significant changes, and can often be impossible to migrate in-place. So how can you tackle these challenges the right way?
When upgrading a web application from .NET Framework to .NET Standard or .NET, you will likely have to address System.Web. On upgrade, the reference to System.Web is either removed or will cause compile-time errors.
When it’s removed, the most common compile time error will be HttpContext.Current.
There are several options available depending on the scenario and stage of migration.
Some older projects .NET Framework project will have EDMX instead of modern DbContext first introduced in Entity Framework 4.1, which first introduced DbContext and Code-First approach back in 2012, replacing the ObjectContext that EDMX used for Database-First approach.
In this rule, we’ll use ObjectContext and Entities interchangeably. ObjectContext is the base class that is used by the generated class, which will generally end with Entities (e.g. DataEntities).
The rule is focusing on .NET 8+ as the support for .NET Framework projects and Nuget was added back, which makes a staged migration a lot more feasible. Most, if not all, are still applicable for .NET 7 as well.
The Global.asax is an optional file that dictates how an ASP.NET application handles application, session and request events. The code for handling those events is written in Global.asax.cs, and when migrating to ASP.NET Core this code will need to be restructured.
OWIN is the Open Web Interface for .NET, which was intended to provide a standard interface between .NET web servers and web applications for ASP.NET. It provided the ability to chain middleware together to form pipelines and to register modules.
The Katana libraries provided a flexible set of popular components for OWIN-based web applications. These components were supplied through packages prefixed with Microsoft.Owin.
Middleware and module registering functionality are now core features of ASP.NET Core. Microsoft provides adapters to and from the OWIN interface for ASP.NET that can be used to gradually migrate custom OWIN components. By contrast, ASP.NET Core has native ports for Katana components.
The Web.Config file was used in ASP.NET to control the behaviour of individual ASP.NET applications and configure IIS. By default, modern ASP.NET Core applications use the Kestrel web server which is configured in code. Unless you are deploying your application using IIS, you will need to migrate your Web.Config file.
The Web.Config file contains data about the package inclusions, module inclusions and configuration values.
Migrating your project to a new Target Framework Moniker (TFM) can be a complex task, especially when you're dealing with compatibility issues between different Target Framework Monikers (TFMs). It is suggested to handle your migration PBIs (Product Backlog Items) collectively and transition your main branch to the new TFM. Making this judgment call requires careful consideration of factors like the number of PBIs and their estimated completion time.
Here are some essential tips for managing changes that are not compatible with both the old and new TFMs:
Most REST APIs serialise/deserialise to and from JSON format. To perform this serialisation, a .NET web application typically relies on either Newtonsoft.Json or System.Text.Json.
Modern .NET applications prefer System.Text.Json over Newtonsoft.Json - which is commonly found in earlier versions of .NET and .NET Framework projects.
This, however, may break in certain usages.
This issue needs to be addressed when migrating projects from .NET Framework to modern .NET.
In the case where the legacy .NET Framework application is hosting the frontend, it is recommended to also think about the hosting method of the frontend in .NET 10.
This issue is best considered before or during the migration so the team will not spend time implementing something that will be removed shortly in the future.
You finally dumped BinaryFormatter, replaced WebClient with HttpClient, and standardised on System.Text.Json!
But in a big codebase (or with a rotating team) someone can unknowingly add the old API back in a new feature branch, undoing days of migration work. The same risk appears with library preferences: you want everybody using FluentValidation, yet the next pull request pulls in DataAnnotations again.