dotnet / dotnet/runtime

Constants for OS platform values

Open
#125,181 9 comments 0 reactions 0 assignees View on GitHub
api-suggestion area-System.Runtime
Dominant language
C#
Stars
18.3k
Forks
5.6k
PR merge metrics
PR metrics pending

Description

## Proposal

Provide named constants for OS platforms so that developers can avoid the risk of typos.

```
public class OSPlatformNames
{
public const string Windows = "Windows";
public const string Linux = "Linux";
}
```

These baseline strings are used with attributes like `SupportedOSPlatform`. The attributes also support extended syntax that includes version numbers embedded in the string. Therefore, to avoid needing syntax like:

```
[SupportedOSPlatform($"{OSPlatformNames.Windows}10.0.19045")]
```

...it is also proposed to add overloads to the related attribute classes that accept the platform name and the version as separate parameters:

```
[SupportedOSPlatform(OSPlatformNames.Windows, "10.0.19045")]
```

## Background

There are a handful of attributes that are used to describe supported/unsupported OS platforms:

* [`TargetPlatformAttribute`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.versioning.targetplatformattribute?view=net-9.0)
* [`SupportedOSPlatformAttribute`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.versioning.supportedosplatformattribute?view=net-9.0)
* [`UnsupportedOSPlatformAttribute`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.versioning.unsupportedosplatformattribute?view=net-9.0)
* [`ObsoletedOSPlatformAttribute`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.versioning.obsoletedosplatformattribute?view=net-9.0)
* [`SupportedOSPlatformGuardAttribute`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.versioning.supportedosplatformguardattribute?view=net-9.0)
* [`UnsupportedOSPlatformGuardAttribute`](https://learn.microsoft.com/en-us/dotnet/api/system.runtime.versioning.unsupportedosplatformguardattribute?view=net-9.0)

These are all defined in [`PlatformAttributes.cs`](https://github.com/dotnet/dotnet/blob/main/src/runtime/src/libraries/System.Private.CoreLib/src/System/Runtime/Versioning/PlatformAttributes.cs). They all take a `string` to describe the target OS platform. The exact nature of this string doesn't seem to be clearly documented anywhere, just that it is a "name and optional version of the platform".

Being a plain `string` means that the specification doesn't need any adjustment to support new platforms if/when support is added, but it also means that it is trivially easy to get the string wrong and potentially only learn about it at runtime. For instance, if the user simply mistypes the platform name, the code will compile just the same.

```
[UnsupportedOSPlatform("Linxu")]
public void GetNTFSFileIndex(string path)
{
}
```

Recently, I was looking up how to use these attributes and Google Search's AI assistant confidently told me in three different searches that I could use each of the strings "OSX", "MacOSX" or "macOS" to refer to that platform. I'm not 100% certain but I'm pretty sure only one of those will actually work as expected.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.