Move appropriate parts of Microsoft.DotNet.PlatformAbstractions.RuntimeEnvironment into the shared framework

[tannergooding]

Rationale

It is often the case, when working with .NET Core that you want to do something based on the current platform/architecture. In many cases, this can include needing to interop with tools published using a particular "runtime identifier".

Today, the RuntimeIdentifier is only exposed through the Microsoft.DotNet.PlatformAbstractions.RuntimeEnvironment.GetRuntimeIdentifier() API and is not exposed as part of CoreFX. This requires referencing an additional package, and prevents it from being used in certain scenarios (such as evaluation time in MSBuild).

As such, I propose that we expose a mechanism to get the RID for the current execution environment at runtime.

Proposed API

#nullable enabled
namespace System.Runtime.InteropServices
{
    public static class RuntimeInformation
    {
        // The current OS RID, e.g.: win7-x64, osx.10.11-x64, ubuntu.18.04-arm64, rhel.7-x64
        public static string RuntimeIdentifier { get; }
    }
}

The above API will return the value of a new AppContext variable RUNTIME_IDENTIFIER. This variable will be passed by the dotnet.exe host, and can be passed by any other native host when the runtime is loaded.

DISCUSSION: Should we still maintain a managed fallback code path for when this AppContext variable isn't present? For example if the app was loaded from a different native host that didn't set this variable.

Additional Notes

This would allow switching on the active RID from an MSBuild project/props/targets file, which would allow greater versatility in consuming native tools from a package during build time (or from a user program at runtime).

It may be worth reviewing the other APIs exposed via Microsoft.DotNet.PlatformAbstractions.RuntimeEnvironment and determining which others, if any, should also be exposed: https://github.com/dotnet/core-setup/blob/master/src/managed/Microsoft.DotNet.PlatformAbstractions/RuntimeEnvironment.cs

Updates

• eerhardt: Add proposal for OperatingSystem and OperatingSystemVersion so Microsoft.DotNet.PlatformAbstractions.RuntimeEnvironment can be completely removed/deprecated/etc.

• vihofer: Choosing OS over OperatingSystem as we already use OS in IsOSPlatform. OperatingSystemPlatform is already accessible through IsOSPlatform(Platform). RuntimeArchitecture is already exposed as ProcessArchitecture. The RuntimeVersions proposal is already covered by dotnet/coreclr#22664 and doesn't require an api review.

• eerhardt: Remove proposal for OSName and OSVersion, we will drop support for these APIs. Callers can instead call Ntdll.RtlGetVersionEx on Windows, or read /etc/os-release on Unix.
  Change RuntimeIdentifier from a property to a method call, since the proposed behavior will invoke a method: AppContext.GetData(), which isn't appropriate for a property.

[tannergooding]

FYI. @eerhardt

[tannergooding]

@nguerrera, @KathleenDollard, @livarcocc, @dsplaisted. I know there has been a similar request on the SDK/CLI team before

[weshaggard]

We already have other related issues like https://github.com/dotnet/corefx/issues/28620.

[dsplaisted]

Is just getting the current RID helpful? Or do you usually also need to find a best match from a list of RIDs you have resources available for, using the RID graph?

[tannergooding]

Is just getting the current RID helpful? Or do you usually also need to find a best match from a list of RIDs you have resources available for, using the RID graph?

Yes, getting the best match from a list of RIDs is even better. Not sure how closely tied that is to NuGet, however.

[tannergooding]

We already have other related issues like #25681.

@weshaggard, right. But I didn't see anything that looked like the "recommended" API proposal layout and that covered the RuntimeIdentifier.

[eerhardt]

It may be worth reviewing the other APIs exposed via Microsoft.DotNet.PlatformAbstractions.RuntimeEnvironment and determining which others, if any, should also be exposed: https://github.com/dotnet/core-setup/blob/master/src/managed/Microsoft.DotNet.PlatformAbstractions/RuntimeEnvironment.cs

See my comments here: https://github.com/dotnet/corefx/issues/28620#issuecomment-377421773, copied below for ease in reading:

@eerhardt what is your thoughts on bring Microsoft.DotNet.PlatformAbstractions into corefx?

I would absolutely LOVE for this to happen.

However, I don't think it should go wholesale into corefx. I think pieces of it should be removed altogether (I'm looking at you HashCodeCombiner and Platform).

And some things should be folded into System.Runtime.InteropServices.RuntimeInformation, like RuntimeEnvironment.

ApplicationEnvironment can probably be deleted as well now that we have netstandard2.0. I'm not exactly sure what it's main purpose was - mostly for net45 and netstandard1.3 code to be able to call 1 method to get the BaseDirectory without having to #if themselves. With netstandard2.0, users can now call AppContext.BaseDirectory, or AppDomain.CurrentDomain.BaseDirectory for this.

So thinking about it more - probably move RuntimeEnvironment into RuntimeInformation, and delete the rest. Obviously the library will still live in servicing branches, if we ever need to service the already released versions of it. And users can continue to use the already released versions all they want.

---

The other public members of RuntimeEnvironment:

        public static Platform OperatingSystemPlatform { get; } = PlatformApis.GetOSPlatform();

        public static string OperatingSystemVersion { get; } = PlatformApis.GetOSVersion();

        public static string OperatingSystem { get; } = PlatformApis.GetOSName();

        public static string RuntimeArchitecture { get; } = GetArch();

The following properties aren't already exposed in corefx:

• OperatingSystem should be moved to RuntimeInformation.
• OperatingSystemVersion should be moved to RuntimeInformation.

The following properties are dupes of corefx APIs:

• OperatingSystemPlatform can be removed since we already have OSPlatform.
• RuntimeArchitecture can be removed since we already have RuntimeInformation.ProcessArchitecture.

[eerhardt]

One question I have about the RID API:

Today, we have an environment variable that allows someone to set the RID:

private static readonly string OverrideEnvironmentVariableName = "DOTNET_RUNTIME_ID";

Do we plan on preserving this behavior with the proposed API? And if we do, would it make more sense for the API to be a method instead of a property? Since it would always need to check the env var.

[tannergooding]

Do we plan on preserving this behavior with the proposed API? And if we do, would it make more sense for the API to be a method instead of a property? Since it would always need to check the env var.

I think a method makes sense, if the behavior is preserved. Otherwise, a property seems the better choice.

[pjanotti]

In general I don't like the idea of applications taking functionality dependency based on reported OS version at runtime: there is a history of broken features because the OS can fake its answers, or later starts to support some feature and the app then requires recompilation. If possible testing/trying the feature itself is the preferred way. That said decisions based on broad categories (e.g.: Windows vs Unix) or more fine grained for tests, not production, are reasonable. Of course using RID info is totally fine in the context of building/packaging/etc.

Do we really need this as a public API? Can we instead bring it down to some place that provides the gains for building/packaging without exposing a public API?

[eerhardt]

I don't think it is a great idea for code to take functionality dependency based on reported OS version at runtime either. But the fact of the matter is, it happens. The RID has the OS version inside of it. So anything you do with the RID will now mean you are dependent on the reported OS version.

We've been down the "do we need the OS Version public API?" path before, and it wasn't added as a "corefx" API previously. And that decision is what led to the creation of the PlatformAbstractions library in the first place. So whether we like it or not, we already have this public API. The issue is the API lives outside of corefx, and outside the "typical" place where people look for this type of information - the RuntimeInformation class. If all the existing callers of RuntimeEnvironment.OperatingSystemVersion can be convinced that they actually don't need to call it, then I think it can be removed.

Here are other places where people are asking for OS version:

https://github.com/dotnet/corefx/issues/16629
https://github.com/dotnet/corefx/issues/29395
https://github.com/dotnet/corefx/issues/8099
https://github.com/dotnet/corefx/issues/4741
https://github.com/dotnet/corefx/issues/12737
https://github.com/dotnet/corefx/issues/9011
https://github.com/dotnet/corefx/issues/1017
https://github.com/dotnet/cli/issues/2754

(note this isn't an exhaustive list, I stopped looking as I think the point is made)

The main usage of OperatingSystemVersion is logging/reporting types of scenarios. Here are the 2 places in the dotnet/cli that call RuntimeEnvironment.OperatingSystemVersion:

• When handling dotnet --info
• To send to telemetry information

I know that we already have Environment.OSVersion. However, Environment.OSVersion is not implemented the same way as RuntimeEnvironment.OperatingSystemVersion. RuntimeEnvironment.OperatingSystemVersion will give you the version part of the RID, which comes from /etc/os-release and then also has some special logic to "normalize" the version on alpine and RHEL. Whereas Environment.OSVersion gets the version from calling uname and returning the .release portion directly.

Lastly, I think these methods/properties (GetRuntimeIdentifier(), OperatingSystem, OperatingSystemVersion) need to live together since they need to be consistent. If the RID says it is rhel.7-x64, then the OperatingSystemVersion needs to return 7. And getting the RID from corefx's RuntimeInformation, but needing to go to PlatformAbstraction's RuntimeEnvironment to get the OperatingSystemVersion doesn't make any sense. If we are going to move the API to get the current machine's RID into RuntimeInformation, then PlatformAbstraction's RuntimeEnvironment should be removed.

p.s.
On the topic of using reported versions in code, I think this comment from @terrajobst is relevant

Working around implementation level issues. Sometimes you need to work around specific behavior that is displayed by specific platform versions.

Version APIs are problematic. Believe me, we know very well how version checks are fragile. We've tried several times to remove version checks from our API surface. Be it in .NET Core or in Windows. But the reality is that some problems are just too hard to do reliably -- regardless of the approach. Giving developers the ability to perform version checks as the ultimate escape hatch is a sensible compromise. There is a reason why we don't want to make this API super discoverable and also turn the logic inside out, i.e. let the developer pass in the value they care about so we can do the version checking for them.

[pjanotti]

Thanks for digging the history and showing that this was considered many times before 😄 you convinced me.

[eerhardt]

I've added to the proposal to include OperatingSystem, and OperatingSystemVersion strings. However, thinking more about this, would it make sense to create a new type that encapsulated the RID APIs? ex.

public struct RuntimeIdentifier
{
    public string Id { get; }
    public string OperatingSystem { get; }
    public string OperatingSystemVersion  { get; }
}

or potentially just a completely new static class that contained RID specific information:

public static class RuntimeIdentifier
{
    public static string GetCurrent();
    public static string OperatingSystem { get; }
    public static string OperatingSystemVersion { get; }
}

This would convey that the OperatingSystem and OperatingSystemVersion strings are directly tied to the RID's concept of what OperatingSystem and OperatingSystemVersion are. And it would be understandable why they are different than say Environment.OSVersion, or RuntimeInformation.IsOSPlatform (ex. RuntimeInformation.IsOSPlatform(OSPlatform.Create("ubuntu")) returns false even when running on ubuntu.)

[weshaggard]

I think it might make some since to have a type for RuntimeIdentifier if we plan to support other scenarios like checking compatibility with other RIDs, if we only care about getting the current RID then I'd stick with a static class.

I do think we need to be a little careful about making assumptions about the structure of a RID. While it is true it generally contains an OS and version it isn't always the case as a RID is just an string. It also commonly contains the architecture so if you are breaking it apart you may want to add that value as well.

ex. RuntimeInformation.IsOSPlatform(OSPlatform.Create("ubuntu")) returns false even when running on ubuntu

We should consider actually fixing that if we can someone embed the RID graph we could use that information to check these different hierarchies.

[simplexidev]

This is something that would be useful, especially when writing bindings for other native libraries. Has there been any update on this?