Few things about migrating to .NET Core

by Damir Dobric

This article gives you a short overview of usefull tips related to migrating of .NET Framework projects to .NET Core.

Compatibility Mode

.NET Standard 2.0 provides compatibility mode, which allows the referencing of existing .NET Framework binaries.

Keep in mind, referenceing .NET binaries from .NET Standard or .NET Core is not the way to go. It is a temporary solution, which helps with the transition period where many packages aren’t yet available for .NET Standard or .NET Core.

Please also note, that simple referencing of a binary assembly and compiling of the soution does not mean that such solution will run.

For example, if your application is .NET Core and references System.DirectoryServices or System.Configuration it will compile. Unfortinatelly it will fail on runtime, because .NET Core framework does not include that assemblies.

API Port

API Port tool guides you through migration process (see aka.ms/apiport). It scans your existing application binaries, including any third-party references, and produces a report that shows portability of each assembly. Result provides a table of all the APIs that are either unavailable or must be migrated. For more informtion please see also this demo.

Example:

$ apiport analyze -f C:\src\fabrikam\bin\Fabrikam.Shared.dll -t ".NET Standard + Platform Extensions"

Compatibility Pack

The Windows Compatibility Pack is a NuGet package Microsoft.Windows.Compatibility, which contains about 40 Windows-World related components like System.Configuration.ConfigurationManager or System.Drawing.

Using of this package helps in general to understand better, which component of complex application depends on Windows.

Compatibility package is designed as a meta package, which means it doesn’t contain any libraries itself. Meta-packages holds references to other NuGet packages. This allows you to quickly add references to the full list of components without having to explicitelly install all packages.

Once you add a reference to compatibility package it will run as long you run the application on Windows. It is a good practice to check the OS platform inside of application once you started migration process to .NET Core. To do this, use following code:

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
  {
    // Your Windows related code...
  }

But if you start the application on none-Windows OS without this check, you should see following exception:

Unhandled Exception: System.TypeInitializationException: The type initializer for 
'Microsoft.Win32.Registry' threw an exception. ---> System.PlatformNotSupportedException: 
Registry is not supported on this platform.

API Analyser

API Analyzer is a Roslyn based analyzer shipped as NuGet package.

SImply add a refernece to your project and tool will run analyser, which automatically monitors your code for problematic API usage.

It discovers deprected APIs and Cross-Platform issues.

You can watch a nice demo in this 5 min. video.

If you want to know more about migration, please also take a look on this article.