C#idiomatic C#
ca1418fundamentals/code-analysis/quality-rules

Code analysis

CA1418: Validate platform compatibility

Learn about code analysis rule CA1418: Use valid platform string

CA1418 Interoperability enabled by default in .NET 10: As warning
Fix is breaking or non-breaking Non-breakingApplicable languages C# and Visual Basic

Cause

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

Rule description

The platform compatibility attributes derived from System.Runtime.Versioning.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 System.OperatingSystem guard methods named OperatingSystem.Is<PlatformName>[VersionAtLeast](). For example, guard method System.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:

    xml
     <ItemGroup>
   <SupportedPlatform Include="PlatformName" />
 </ItemGroup>

If the platform string contains a version part, it should be a valid System.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 System.OperatingSystem class.

    csharp
    [SupportedOSPlatform("Solaris")] // Warns: The platform 'Solaris' is not a known platform name.
public void SolarisApi() { }

  • Android is a known platform because there is a System.OperatingSystem.IsAndroid guard method in the System.OperatingSystem type. However, the version part is not a valid version. It should have at least two integers separated by a dot.

    csharp
    [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 System.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.

    csharp
    [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:

    xml
      <ItemGroup>
    <SupportedPlatform Include="Solaris" />
  </ItemGroup>
    csharp
    [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.

    csharp
    // 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.

    csharp
    // 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.

See also