CA1418：验证平台兼容性

  • 项目
属性 值
规则 ID CA1418
标题 验证平台兼容性
类别 互操作性
修复是中断修复还是非中断修复 非中断
在 .NET 8 中默认启用 作为警告

原因

平台兼容性分析器需要有效的平台名称和版本。 如果提供给 OSPlatformAttribute 构造函数的平台字符串包含未知平台名称，或者可选版本部分无效，则会报告违规。

规则说明

派生自 OSPlatformAttribute 的平台兼容性属性在操作系统 (OS) 平台名称中使用字符串字面量和可选版本部分。 该字符串应包含已知平台名称，不包含版本部分或包含有效版本部分。

已知平台名称列表由两部分构成：

  • 名为 OperatingSystem.Is<PlatformName>[VersionAtLeast]() 的 OperatingSystem 保护方法的 PlatformName 部分。 例如，保护方法 OperatingSystem.IsWindows() 将 Windows 添加到已知平台名称列表。

  • 由 SupportedPlatform 项构成的项目的 MSBuild 项组，其中包括默认的 MSBuild SupportedPlatforms 列表。 这是已知平台的项目特定信息。 它允许类库作者将更多平台添加到已知平台列表。 例如：

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

如果平台字符串包含版本部分，则它应是具以下格式的有效 Version：major.minor[.build[.revision]]。

冲突

  • Solaris 是未知平台名称，因为它未包含在默认的 MSBuild SupportedPlatforms 列表中，并且 OperatingSystem 类中没有名为 OperatingSystem.IsSolaris() 的保护方法。

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

  • Android 是已知平台，因为 OperatingSystem 类型中有 OperatingSystem.IsAndroid() 保护方法。 但版本部分不是有效版本。 它应至少有两个以点分隔的整数。

    [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 是已知平台，因为它包含在默认的 MSBuild SupportedPlatforms 列表中，并且有名为 OperatingSystem.IsLinux() 的保护方法。 但对于 Linux 平台，没有 System.OperatingSystem.IsLinuxVersionAtLeast(int,int) 等版本化保护方法，因此 Linux 不支持版本部分。

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

如何解决冲突

  • 将平台更改为已知平台名称。

  • 如果平台名称正确，并且你希望使其成为已知平台，请将其添加到项目文件中的 MSBuild SupportedPlatforms 列表：

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

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

  • 修复无效版本。 例如，对于 Android，10 不是有效版本，而 10.0 是有效版本。

    // 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() { }

  • 如果平台不支持某一版本，请删除对应版本部分。

    // 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() { }

何时禁止显示警告

不建议使用未知的平台名称或无效版本，因此不应抑制此规则。

另请参阅