CA1418: Validate platform compatibility

Artikkeli
12/16/2023

Property	Value
Rule ID	CA1418
Title	Validate platform compatibility
Category	Interoperability
Fix is breaking or non-breaking	Non-breaking
Enabled by default in .NET 9	As warning

Cause

The platform compatibility analyzer requires a valid platform name and version. Violations are reported if the platform string provided to the OSPlatformAttribute constructor consists of an unknown platform name or if the optional version part is invalid.

Rule description

The platform compatibility attributes derived from OSPlatformAttribute use string literals for operating system (OS) platform names with an optional version part. The string should consist of a known platform name and either no version part or a valid version part.

The known platform names list is populated from two places:

The PlatformName part of OperatingSystem guard methods named OperatingSystem.Is<PlatformName>[VersionAtLeast](). For example, guard method OperatingSystem.IsWindows() adds Windows to the known platform names list.
The project's MSBuild item group of SupportedPlatform items, including the default MSBuild SupportedPlatforms list. This is the project specific knowledge of known platforms. It allows class library authors to add more platforms into the known platforms list. For example:
```
  <ItemGroup>
    <SupportedPlatform Include="PlatformName" />
  </ItemGroup>
```

If the platform string contains a version part, it should be a valid Version with the following format: major.minor[.build[.revision]].

Violations

Solaris is an unknown platform name because it's not included in the default MSBuild SupportedPlatforms list and there's no guard method named OperatingSystem.IsSolaris() in the OperatingSystem class.
```
[SupportedOSPlatform("Solaris")] // Warns: The platform 'Solaris' is not a known platform name.
public void SolarisApi() { }
```
Android is a known platform because there is a OperatingSystem.IsAndroid() guard method in the OperatingSystem type. However, the version part is not a valid version. It should have at least two integers separated by a dot.
```
[UnsupportedOSPlatform("Android10")] // Warns: Version '10' is not valid for platform 'Android'. Use a version with 2-4 parts for this platform.
public void DoesNotWorkOnAndroid() { }
```
Linux is a known platform because it is included in the default MSBuild SupportedPlatforms list, and there's also a guard method named OperatingSystem.IsLinux(). However, there are no versioned guard methods like System.OperatingSystem.IsLinuxVersionAtLeast(int,int) for the Linux platform, therefore no version part is supported on Linux.
```
[SupportedOSPlatform("Linux4.8")] // Warns: Version '4.8' is not valid for platform 'Linux'. Do not use versions for this platform.
public void LinuxApi() { }
```

How to fix violations

Change the platform to a known platform name.

If the platform name is correct and you want to make it a known platform, then add it to the MSBuild SupportedPlatforms list in your project file:

  <ItemGroup>
    <SupportedPlatform Include="Solaris" />
  </ItemGroup>

[SupportedOSPlatform("Solaris")] // No warning
public void SolarisApi() { }

Fix the invalid version. For example, for Android, 10 is not a valid version, but 10.0 is valid.

// Before
[UnsupportedOSPlatform("Android10")] // Warns: Version '10' is not valid for platform 'Android'. Use a version with 2-4 parts for this platform.
public void DoesNotWorkOnAndroid() { }

// After
[UnsupportedOSPlatform("Android10.0")] // No warning.
public void DoesNotWorkOnAndroid() { }

If the platform doesn't support a version, remove the version part.

// Before
[SupportedOSPlatform("Linux4.8")] // Warns: Version '4.8' is not valid for platform 'Linux'. Do not use versions for this platform.
public void LinuxApi() { }

// After
[SupportedOSPlatform("Linux")] // No warning.
public void LinuxApi() { }

When to suppress warnings

Using an unknown platform name or an invalid version is not recommended, so you shouldn't suppress this rule.

Jaa