Description
Removal of Microsoft.DotNet.PlatformAbstractions Package
We will stop building new versions of Microsoft.DotNet.PlatformAbstractions in .NET 5
Version introduced
.NET 5.0 Preview 6
Old behavior
New versions of the Microsoft.DotNet.PlatformAbstractions library were produced alongside new versions of .NET Core.
New behavior
New functionality and major versions of this library will no longer be produced.
Reason for change
As part of the ongoing repository consolidation effort in .NET 5, we have been examining the libraries that were previously in dotnet/core-setup and deciding on their long-term strategy/goals.
The Microsoft.DotNet.PlatformAbstractions library has considerable overlap with APIs that are already established in the System.* namespaces. Also, some PlatformAbstractions APIs were not designed with the same level of scrutiny and long-term supportability that the rest of the System.* APIs are designed. For example, PlatformAbstractions uses an enum named Platform to describe the current Operating System Platform. This design was explicitly rejected when designing RuntimeInformation.IsOSPlatform(OSPlatform) to allow for new platforms and to allow the most flexibility in the future.
To resolve this situation, we have ensured that the scenarios enabled by Microsoft.DotNet.PlatformAbstractions are now possible without it and plan to stop building new versions of Microsoft.DotNet.PlatformAbstractions in .NET 5. The existing versions will continue to work, even in .NET 5, and be serviced along with previous versions of .NET Core. But new functionality won't be added to the library. New functionality will be added through other libraries and APIs.
Recommended action
You can continue to use older versions of the library if they meet your requirements.
When the older version no longer meets your requirements, you can replace usages of the PlatformAbstractions APIs with the recommended API in the following table.
| PlatformAbstractions API | Recommended Replacement |
|---|---|
| ApplicationEnvironment.ApplicationBasePath | AppContext.BaseDirectory |
| HashCodeCombiner | System.HashCode |
| RuntimeEnvironment.GetRuntimeIdentifier() | RuntimeInformation.RuntimeIdentifier |
| RuntimeEnvironment.OperatingSystemPlatform | RuntimeInformation.IsOSPlatform(OSPlatform) |
| RuntimeEnvironment.RuntimeArchitecture | RuntimeInformation.ProcessArchitecture |
| RuntimeEnvironment.OperatingSystem | RuntimeInformation.OSDescription ** See Note |
| RuntimeEnvironment.OperatingSystemVersion | RuntimeInformation.OSDescription and Environment.OSVersion.Version ** See Note |
Note on OperatingSystem and OperatingSystemVersion
The majority of use cases for these APIs are for display purposes: displaying to a user, logging, telemetry, etc. Making runtime decisions on an operating system version (especially one that is of type string) is not a recommended practice. We have made enhancements to Environment.OSVersion.Version to return the correct version for Windows and macOS Operating Systems. However, for most Unix distributions, what is considered to be the "OS Version" is not as straight-forward. Do you want the Linux kernel version? The distro version? etc. For most Unix platforms, Environment.OSVersion.Version and RuntimeInformation.OSDescription continue to return the version returned by uname. For getting Linux distro name and version information, the recommended approach is to read the /etc/os-release file.
Category
- Core .NET libraries
Affected APIs
All under the Microsoft.DotNet.PlatformAbstractions namespace.
- ApplicationEnvironment.ApplicationBasePath
- HashCodeCombiner
- RuntimeEnvironment.GetRuntimeIdentifier()
- RuntimeEnvironment.OperatingSystemPlatform
- RuntimeEnvironment.RuntimeArchitecture
- RuntimeEnvironment.OperatingSystem
- RuntimeEnvironment.OperatingSystemVersion
Issue metadata
- Issue type: breaking-change