A major reason for switching from .NET to .NET Core is the ability to run on Linux. But for large enterprise applications, performing a migration in a single step isn’t feasible. For this reason, Microsoft recommends an incremental transition:
- Migrate to ASP.NET Core (while still targeting the .NET Framework)
- Migrate to .NET Core (while staying on Windows)
- Migrate to Linux
- Migrate to [Linux hosted on] Azure
While that sounds good in theory, the lack of mission critical APIs can still prevent projects from making it to step 2. Which is where the Windows Compatibility Pack for .NET Core comes into play. Encompassing 20,000 APIs, this collection of NuGet packages intends to address the outstanding library needs for web app developers.
The newly ported APIs are roughly divided into two categories: Windows-only and cross platform. The Windows-only APIs include:
- Active directory
- Cryptography
- Event logs and performance counters
- File system security
- Named pipes
- Registry Access
- Windows Services
For the most part these are deeply linked to the Windows operating system, with the Linux equivalents are often fundamentally different in design.
The cross-platform libraries include:
- Caching
- ConfigurationManager (i.e. processing legacy app.config/web.config files)
- DatasetExtensions (used for database access without an ORM)
- ODBC database access
- System.Configuration.ConfigurationManager (MEF v1)
- System.Drawing
- System.IO.Packaging (used for interacting with MS Office style Zip files)
- System.ServiceModel (i.e. WCF)
It should be noted that these APIs are being intentionally omitted from the full .NET Core distribution. Immo Landwerth of Microsoft explains,
The reason it’s a separate package is because (1) many of the APIs are provided for compatibility reasons only. New code shouldn’t depend on them (2) many of the APIs are Windows-only. We don’t want to lead you down a path that makes a cross-platform evolution of your app harder.
In order to make it easier to distinguish between Windows-only and cross-platform APIs, an API compatibility analyzer can be used to flag APIs that applications should no longer rely on.
You have the same suppression options as with deprecated APIs but you also have the option to suppress warnings for specific platforms. This is useful if you’re only planning to support your code on a specific subset of platforms (e.g. only Windows and Linux, but not macOS). To do so, you just need to edit your project file and add a property PlatformCompatIgnore that lists all platforms to be ignored.