Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.
In order to migrate your application from .NET Framework to .NET Core, one part of the migration is making sure your existing code that targets the .NET Framework BCL (Base Class Library) also works with the .NET Core BCL. This is where the .NET Portability Analyzer comes in.
Migrating from .NET Framework to .NET Core
This post is in a blog series for migrating from .NET Framework to .NET Core. Here’ are some earlier post if you need to catch up:
- Migrating from .NET Framework to .NET Core Overview
- Migrating to ASP.NET Core
- Multi-Targeted NuGet Package Gotchas!
- NuGet Package Alternatives when Migrating to .NET Core
- Mission Complete
I’ve recorded a short video that also describes how to use the portability analyzer.
.NET Framework and .NET Core are two entirely different things. Yes, they share the name “.NET”, but they are comprised of different Runtimes and Base Class Libraries. The Base Class Library (BCL) is the foundation of the framework for .NET types such as Object, String, Boolean, Array, List, DateTime, and other primitive types and data structures.
In order to share code/libraries between .NET Framework applications and .NET Core applications is where .NET Standard comes in. I’ve found the simplest way to explain this is to think of .NET Standard as an interface (or a contract).
Both .NET Framework and .NET Core implement that interface.
Because of this, if you write an application that is .NET Standard 2.0 compliant, you can then run your application on both .NET Framework or .NET Core.
- .NET Framework 4.8 supports .NET Standard 2.0
- .NET Core 2.1 supports .NET Standard 2.0
- .NET Core 3.1 supports .NET Standard 2.1
Again, because both .NET Framework 4.8 and .NET Core 2.1 support .NET Standard 2.0, you could run your application on either.
Note that .NET Core 3.1 supports .NET Standard 2.1. And it has been noted that .NET Framework will never support .NET Standard 2.1.
.NET Portability Analyzer
The .NET Portability Analyzer is a tool that analyzes your codebase and provides a report about what types you’re using from the BCL that are supported in .NET Standard or .NET Core.
This allows you to determine how close or far you are away from being able to migrate to .NET Core. A lot of the Types and APIs that exist in .NET Framework also now exist in .NET Core. There are however some gaps that will never be officially implemented in .NET Core. Most notably this will be any type that lives in the System.Web namespace.
There are two ways to run the .NET Portability Analyzer. The simplest is to use the Visual Studio Extension.
Once installed, you can access the settings from the solution context menu:
The Portability Analyzer settings allow you to configure which target platforms to review against. You can specify .NET Core specific or .NET Standard.
After configuring you can then run the “Analyzer Assembly Portability” from the solution context menu. This will generate an Excel file (.xlsx) that will contain all the types that exist in your code that are not supported against the target platforms you specified.
The Portability Summary section gives overall % of each assembly/project in your solution and how it’s supported on the target platform.
The details section lists all the APIs that are missing from a target platform.
The missing assemblies section of the report likely will include a list of dependencies that you are likely using via NuGet. I’ll cover how to handle 3rd party dependencies in another post.
This report will be invaluable for tracking down APIs that you’re using that are not supported in .NET Core.
Once you have these missing APIs in hand that are not supported in .NET Core, it really is up to you to determine how you want to handle or rewrite that code.
If you’re not using Visual Studio, you can simply build the .NET Portability Analyzer and run it against your assembly. You can find the source and instructions on the projects GitHub repo.
If you’ve used the portability analyzer and have and or comments that may help others, let me know in the comments or on Twitter.