CA1418：驗證平臺相容性

屬性 值
規則識別碼 CA1418
職稱 驗證平台相容性
類別 互通性
修正是造成中斷還是不中斷 不中斷
在 .NET 10 中預設啟用 作為警告
適用語言 C# 與 Visual Basic

原因

平臺相容性分析器需要有效的平台名稱和版本。 如果提供給 OSPlatformAttribute 建構函式的平臺字串是由未知的平臺名稱所組成，或選擇性版本元件無效，則會報告違規。

規則描述

衍生自 OSPlatformAttribute 的平臺相容性屬性會針對具有選擇性版本部分的作業系統 （OS） 平台名稱使用字串常值。 字串應包含已知的平台名稱，並且要麼不含版本部分，要麼含有效版本部分。

已知的平台名稱列表會由以下兩個來源填入：

  • 名為 PlatformNameOperatingSystem的 guard 方法部分OperatingSystem.Is<PlatformName>[VersionAtLeast]()。 例如，guard 方法 OperatingSystem.IsWindows() 會將 新增 Windows 至已知的平台名稱清單。

  • 專案的 MSBuild 項目群組SupportedPlatform項目，包括預設的MSBuild 支援平台清單。 這是已知平臺的專案特定知識。 它可讓類別庫作者將更多平臺新增至已知平台清單。 例如：

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

如果平臺字串包含 版本 元件，它應該是具有下列格式的有效 Version 版本： major.minor[.build[.revision]]。

違規

  • Solaris 是未知的平臺名稱，因為它未包含在預設 MSBuild SupportedPlatforms 清單中，而且類別中OperatingSystem.IsSolaris()沒有名為 OperatingSystem 的 guard 方法。

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

  • Android是已知的平台，因為在類型中有一個OperatingSystem.IsAndroid()OperatingSystem guard 方法。 然而，版本部分不是有效的版本。 它至少應該有兩個以點分隔的整數。

    [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) 的版本防護方法，因此不支援任何版本元件。

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

隱藏警告的時機

不建議使用未知的平台名稱或無效的版本，因此您不應該隱藏此規則。

另請參閱

  • Last updated on