. NET core compatibility Windows & Windows compatible Linux

What is the?

This are meant for developers, need to port existing. NET Framework code to. NET Core. But before your start porting, you should understand, and what's want to accomplish with the migration. Just porting to. NET Core because it's a new. NET implementation isn ' t a good enough reason (unless you ' re a True Fan).

. NET Core is optimized-building highly scalable Web applications, running on Windows, MacOS or Linux. If you ' re building Windows desktop applications, then the. NET Framework is the best choice for you. Take a look at our documentation for more details on how to choose between. NET Core and. NET Framework.

Demo

For a demo, take a look at the This video:

Using the Windows compatibility Pack

We highly recommend that's plan your migrations as a series of steps instead of assuming you can port the existing code Base all at once. If you ' re planning to migrate an ASP application running on a local Windows server to an ASP. NET Core Application Running on Linux in Azure, we ' d recommend perform these steps:

1. Migrate to ASP (while still targeting the. NET Framework)
2. Migrate to. NET Core (when staying on Windows)
3. Migrate to Linux
4. Migrate to Azure

The order of steps might vary, depending on your business goals and what value are need to accomplish first. For example, you might need-to-deploy to Azure before you perform the other migration steps. The primary point is so you perform one step at a time to ensure your application stays operational along the the. This reduces the complexity and churn you has to reason about at once. It also allows learn more about your code base and adjust your plans as you discover issues.

The Porting to. NET Core from. NET Framework documentation provides more details on the recommended process and which tool s can use.

Before bringing existing. NET Framework code to a. NET Core project, we recommend you first add the Windows compatibility Pack by installing the NuGet package Microsoft.Windows.Compatibility. This maximizes the number of APIs for you has at your disposal.

The Windows compatibility Pack is currently in preview because it's still a work in progress. The following table describes the APIs that is already part of the Windows compatibility Pack or is coming in a subseque NT Updat

Component	Status	windows-only	Component	Status	windows-only
Microsoft.Win32.Registry	Available	Yes	System.Management	Coming	Yes
Microsoft.Win32.Registry.AccessControl	Available	Yes	System.Runtime.Caching	Coming
System.CodeDom	Available		System.Security.AccessControl	Available	Yes
System.ComponentModel.Composition	Coming		System.Security.Cryptography.Cng	Available	Yes
System.Configuration.ConfigurationManager	Available		System.Security.Cryptography.Pkcs	Available	Yes
System.Data.DatasetExtensions	Coming		System.Security.Cryptography.ProtectedData	Available	Yes
System.Data.Odbc	Coming		System.Security.Cryptography.Xml	Available	Yes
System.Data.SqlClient	Available		System.Security.Permissions	Available
System.Diagnostics.EventLog	Coming	Yes	System.Security.Principal.Windows	Available	Yes
System.Diagnostics.PerformanceCounter	Coming	Yes	System.ServiceModel.Duplex	Available
System.DirectoryServices	Coming	Yes	System.ServiceModel.Http	Available
System.DirectoryServices.AccountManagement	Coming	Yes	System.ServiceModel.NetTcp	Available
System.DirectoryServices.Protocols	Coming		System.ServiceModel.Primitives	Available
System.Drawing	Coming		System.ServiceModel.Security	Available
System.Drawing.Common	Available		System.ServiceModel.Syndication	Coming
System.IO.FileSystem.AccessControl	Available	Yes	System.ServiceProcess.ServiceBase	Coming	Yes
System.IO.Packaging	Available		System.ServiceProcess.ServiceController	Available	Yes
System.IO.Pipes.AccessControl	Available	Yes	System.Text.Encoding.CodePages	Available	Yes
System.IO.Ports	Available	Yes	System.Threading.AccessControl	Available	Yes

Handling Windows-only APIs

If you plan to run your. NET Core application on Windows only and then you don't have to worry about whether a API is cross- Platform or not. However, if you plan to migrate your application to Linux or MacOS, you need to take the platform-in account.

As you can see in the previous table, about half of the components in the Windows compatibility Pack is Windows-only, the Other half works on any platform. Your code can always assume this all the APIs exist across all platforms, but if they is windows-only they t Hrow PlatformNotSupportedException . This allows-write code that calls Windows-only APIs after doing a platform check at runtime, rather than have to Use conditional compilation using #if . We recommend Runtimeinformation.isosplatform () for platform checks:

PrivateStaticString Getloggingpath () {Verify the code is running on Windows.if (Runtimeinformation.isosplatform (osplatform.windows)) {using (VarKey = Registry.CurrentUser.OpenSubKey (@ "Software\fabrikam\assetmanagement")) {if (key?. GetValue ( "Loggingdirectorypath") is string configuredpath) return ConfiguredPath;}} //this is either does running on Windows or no logging path was configured, //so Ju St use of the path for non-roaming user-specific data files. var appdatapath = Environment.getfolderpath ( Environment.SpecialFolder.LocalApplicationData); return path.combine (Appdatapath,  "Fabrikam" Assetmanagement "< Span class= "Pl-pds" > "Logging");          

You might wonder how do you ' re supposed to know which APIs is windows-only. The obvious answer would is documentation, but that's not very convenient. This is one of the reasons why we introduced the API Analyzer tool, both weeks ago. It's a roslyn-based analyzer that would flag usages of windows-only APIs when you're targeting. NET Core and. NET Standard. For the previous sample, this looks as follows:

You have the three options to deal with Windows-only API usages:

• Remove. Sometimes might get away with simply deleting the code as you don ' t plan to migrate certain features to the. NET core- Based version of your application.
• Replace. Usually, you'll want to preserve the general feature so you might has to replace the technology with one it is CROSS-PL Atform. For example, instead of saving configuration state in the registry, you ' d use text-based configuration files can read from all platforms.
• Guard. In some cases, if you are want to the call of the Windows-only API when you ' re running on Windows and simply does nothing (or call a L Inux-specific API) When your ' re running on Linux.

In the previous example, the code was already written in such a-on-the-it provides a default configuration when the Setti ng isn ' t found in the registry. So the easiest solution are to guard the call to registry APIs behind a platform check.

The Windows compatibility Pack is designed as a metapackage, meaning it doesn ' t directly contain any libraries but referen CES other packages. This allows-quickly bring in all the technologies without have to hunt down various packages. But as your port progresses, your may find it useful to reference individual packages instead. This allows your to remove dependencies and ensure newly written code in so project doesn ' t take a dependency on it again .

Summary

When your port existing code from the. NET Framework to. NET Core, install the new Windows compatibility Pack. It provides access to a additional 20,000 APIs, compared to what's available in. NET Core. This includes drawing, EventLog, WMI, Performance Counters, and Windows Services.

If you plan to make your code cross-platform with the new API Analyzer to ensure you don ' t accidentally depend on windows- Only APIs.

But remember, the. NET Framework is still, the best choice for building desktop applications as well as Web form-based Web applications. If you're happy on the. NET Framework, there are also no reason to port to. NET Core.

Let us know what do you think!

. NET core compatibility Windows & Windows compatible Linux