What is .Net 5
.Net 5 is one of the major and latest releases of Microsoft’s .NET family. It comes with many exciting features compared to the previous released .Net core. The primary goal with the release of .Net 5 is to merge all future .Net development onto one unified platform. All of Microsoft’s different development environments, such as WPF, ASP. NET, Xamarin, etc. are all moving to .NET Core, which will now be known as “.NET”.
The latest version of .Net Core was named as .Net 5.0 to prevent confusion with the .Net framework versions already out there. So from now on, they plan to keep the versioning simple 5.0, 6.0, 7.0, and so on.
Why should you migrate from .Net Framework to .Net 5
Before diving into the why, Let’s look at some key features of .Net 5 include:
- Cross-platform implementation.
- Open-source & community-oriented.
- Support with future updates to Visual Studio Code, Visual Studio 2019, Command Line Interface, and Visual Studio for Mac.
- Support for platform-specific features like Windows Forms, & WPF on Windows.
- Small project files.
With the consideration of the above features,
You may use NET Core/5+ for your application:
- If you’re cross-platform needs.
- If you’re targeting microservices.
- If you plan to use Docker containers.
- If you need high-performance and scalable systems.
- If you need side-by-side .NET versions per application.
You better stay with .NET Framework for your application when:
- If your app uses third-party .NET libraries or NuGet packages not available for .NET Core/5+.
- If your app uses .NET Framework technologies that aren’t available for .NET Core/5+.
- If your app uses a platform that doesn’t support .NET Core/5+
Determine the upgrade feasibility
Before you start, it’s better to become familiar with the upgrade feasibility of your project and understand which dependencies support DotNET 5. For this, we can use the .NET Portability Analyzer tool which is available at the Visual Studio Marketplace. This tool will analyze assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms.
Once you have installed the extension from Marketplace you can configure it in Visual Studio via Analyze > Portability Analyzer Settings and selecting your Target Platforms, that you want to evaluate the portability gaps comparing with the platform/version that your current assembly is built with.
To analyze your entire project in Visual Studio, right-click on your project in Solution Explorer and select Analyze Assembly Portability. Or else, go to the Analyze menu and select Analyze Assembly Portability. From there, select your project’s executable or DLL.
Analyze portability
Portability Summary
.NET Upgrade Assistant
Trust me, manually migrating your legacy .net framework project can be really hard. To make things easier, Microsoft previewed a new tool ‘.NET Upgrade Assistant’ in their Ignite event in 2021. The .NET Upgrade Assistant is a powerful global command-line tool that can be run on different kinds of .NET Framework apps. It’s designed to assist with upgrading .NET Framework apps to .NET 5. It will do most of your heavy lifting and allow you to focus on what’s important. The tool includes the installation of analyzers that can assist with completing the migration. The .NET Upgrade Assistant works on the following types of .NET Framework applications:
- Windows Forms
- WPF
- ASP.NET MVC
- Console apps
- Class libraries
Before you start
Before you install the .NET Upgrade Assistant, you must ensure you install the following:
- Visual Studio 2019 16.8 or later (Visual Studio is required because the tool uses MSBuild to work with project files)
- The .NET 5 SDK
The tool also depends on the try-convert tool to convert project files to the SDK style.
- You must have version 0.7.212201 or later to use the Upgrade Assistant.
From a terminal, run the following to install the try-convert. (It’s a global tool, so you can run the command anywhere.)
dotnet tool install -g try-convert
If you have try-convert installed but need to upgrade to a newer version, execute the following:
dotnet tool update -g try-convert
Install the .NET Upgrade Assistant
We’re now ready to install the .NET Upgrade Assistant. To do so, execute the following from a terminal:
dotnet tool install -g upgrade-assistant
After installing the .NET Upgrade Assistant, run it by navigating to the folder where your solution exists and entering the following command.
dotnet tool upgrade -g upgrade-assistant
Use the Upgrade Assistant to Migrate to .NET 5
To get started, Let’s run the following command from the terminal. (The default command should work, but, if needed, you can pass other flags like — verbose.)
upgrade-assistant upgrade
The tool executes and shows you the steps it will perform. For each step in the process, you can apply the next step in the process, skip it, see details or configure logging. Most of the time, you’ll want to select Apply next step. To save some time, you can press Enter to do this.
Back-Up your Project
The first step is to back up the project. The .NET Upgrade Assistant asks if you want to use a custom path for your backup or a default location. Once this completes, we’re ready to convert the project file.
Convert Project files to SDK Style
.NET 5 projects use the SDK-style format. In this step, the Upgrade Assistant converts your project file to this SDK format using the try-convert tool. During this process, we see the tool is warning us that a few imports, like System.Web, might need manual intervention after migration.
Clean up NuGet package references
In this step, the Upgrade Assistant will update package references and remove transitive dependencies.
Update the target framework (Update TFM)
Next, the .NET Upgrade Assistant will update the Target Framework Moniker (TFM) to .NET 5.0. For example, net451 to net5.0.
Update NuGet Packages
Once the Upgrade Assistant updates the TFM, it attempts to update the project’s NuGet packages. The tool uses an analyzer to detect which references to remove and which packages to upgrade with their .NET 5 versions. Then, the tool updates the packages.
Add Template Files
After the tool updates any NuGet packages, it adds any relevant template files. ASP.NET Core uses template files for configuration and startup. These typically include Program.cs, Startup.cs, appsettings.json and appsettings.development.json based on recognised web.config or app.config values.
Migrate Application Configuration Files
- Now the tool is ready to migrate our application configuration files. The tool identifies what settings are supported, then migrates any configurable settings to the appSettings.json file.
- After that is complete, the tool migrates system.web.webPages.razor/pages/namespaces by updating _ViewImports.cshtml with an @addTagHelper reference to Microsoft.AspNetCore.Mvc.TagHelpers.
Update C# Source
Now, the .NET Upgrade Assistant upgrades C# code references to their .NET Core counterparts. You’ll see several steps listed in the terminal — not all apply. In those cases, they’ll be skipped over and flagged as [Complete].
As the first step, it removes any using statements that reference .NET Framework namespaces, like System.Web. Then, it ensures the ActionResult calls come from Microsoft.AspNetCore.Mvc namespace. Finally, the Upgrade Assistant ensures that I don’t use HttpContext.Current, which ASP.NET Core/5 doesn’t support.
The final step is to evaluate the next project. If there are no other projects left, the tool will exit.
Manually Fix Remaining Issues
Now you can open your project in visual studio and check whether your project has ported successfully to .Net 5 by, Right-click -> Properties in your project.
Let’s try to build this code. Look for warnings in the Error List window of Visual Studio to help you identify other parts of your code that might not be supported in .NET 5. A majority of these issues involve how ASP.NET Core handles startup, configuration, and bundling.
- The Global.asax and Global.asax.cs files are no longer needed in ASP.NET Core, as the global application event model is replaced with ASP.NET Core’s dependency injection model, in Startup.cs.
- You won’t need the App_Start folder or any of the files in it (BundleConfig.cs, FilterConfig.cs, and RouteConfig.cs). You can easily delete those files.
- Finally, fix any issues that remain. You should also check any NuGet packages that might have been updated as sometimes there are breaking changes, and you may need to revert to an older version.
Conclusion
In this article, we discussed the difference between the .net framework and .net 5. Then we toured the new .NET Upgrade Assistant and showed how can we easily speed up your migration to .NET 5.
As I mentioned, the .NET Upgrade Assistant is a promising and powerful tool however, it’s in prerelease mode and developing gradually. Make sure to check out the tool’s GitHub repository to get up to speed and report any issues or suggestions.
Happy upgrading to .Net5!!!