CA1418：驗證平臺相容性

  • 發行項
屬性 值
規則識別碼 CA1418
標題 驗證平台相容性
類別 互通性
修正程式是中斷或非中斷 不中斷
預設在 .NET 8 中啟用 作為警告

原因

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

檔案描述

衍生自 OSPlatformAttribute 的平臺相容性屬性會針對具有選擇性版本部分的作業系統 （OS） 平臺名稱使用字串常值。 字串應該包含已知的平臺名稱，而且沒有任何版本元件或有效的版本部分。

已知的平臺名稱清單會從兩個位置填入：

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

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

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

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

違規

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

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

  • Android是 已知的 平臺，因為 類型中有 OperatingSystem 一個 OperatingSystem.IsAndroid() 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() 個名為 的防護方法。 不過，平臺沒有版本 System.OperatingSystem.IsLinuxVersionAtLeast(int,int)Linux 設定的防護方法，因此 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() { }

隱藏警告的時機

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

另請參閱