警告 CA1416：平台相容性

  • 發行項

從 .NET 5 開始，依預設會啟用 .NET 程式碼分析器規則 CA1416。 其會從未驗證作業系統的呼叫站台產生平台特定 API 呼叫的建置警告。

變更描述

從 .NET 5 開始，.NET SDK 包含 .NET 原始程式碼分析器。 這些規則中有些會預設啟用，包括 CA1416。 如果您的專案包含違反此規則的程式碼，且設定為將警告視為錯誤，則此項變更會中斷您的組建。 規則 CA1416 會在您從平台內容未驗證的位置使用平台特定 API 時通知您。

規則 CA1416 是平台相容性分析器，可與 .NET 5 中的一些其他新功能搭配運作。 .NET 5 導入了 SupportedOSPlatformAttribute 和 UnsupportedOSPlatformAttribute，可讓您指定「支援」或「不支援」API 的平台。 如果沒有這些屬性，則會假設所有平台上都支援 API。 這些屬性已套用至核心 .NET 程式庫中的平台特定 API。

當專案以使用的 API 不可用的平台為目標時，規則 CA1416 會將平台內容未經過驗證的所有平台特定 API 呼叫加上旗標。 現在，裝飾有 SupportedOSPlatformAttribute 和 UnsupportedOSPlatformAttribute 屬性的大多數 API，都會在受到不支援作業系統叫用時擲回 PlatformNotSupportedException。 現在，這些 API 已標記為平台特定，規則 CA1416 會協助您藉由新增 OS 檢查到呼叫站台來防止執行階段 PlatformNotSupportedException 例外狀況。

範例

  • Console.Beep(Int32, Int32) 方法只受 Windows 支援，且裝飾有 [SupportedOSPlatform("windows")]。 如果專案以 net5.0 (cross platform) 為目標，則以下程式碼會在建置階段產生 CA1416 警告。 但是，如果專案以 Windows (net5.0-windows) 為目標，且專案的 GenerateAssemblyInfo 已啟用，那麼此程式碼則不會警告。 如需您可以採取的動作以避免警告，請參閱建議的動作。

    public void PlayCMajor()
{
    Console.Beep(261, 1000);
}

  • 瀏覽器不支援 Image.FromFile(String) 方法，且其裝飾有 [UnsupportedOSPlatform("browser")]。 如果專案支援瀏覽器平台，則已下程式碼會在建置階段產生 CA1416 警告。

    public void CreateImage()
{
    Image newImage = Image.FromFile("SampImag.jpg");
}

    提示

    Blazor WebAssembly 專案和 Razor 類別程式庫專案會自動包含瀏覽器支援。 如要手動為您的專案新增瀏覽器作為支援的平台，請新增以下項目到您的專案檔：

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

導入的版本

5.0

請確保只有當程式碼在適當的平台上執行時，才會呼叫平台特定 API。 您可使用 System.OperatingSystem 類別中的其中一個 Is<Platform> 方法 (例如 OperatingSystem.IsWindows()) 來檢查目前的作業系統，再呼叫平台特定 API。

您可以在 if 陳述式的條件中使用其中一個 Is<Platform> 方法：

public void PlayCMajor()
{
    if (OperatingSystem.IsWindows())
    {
        Console.Beep(261, 1000);
    }
}

或者，如果您不想在執行階段有額外 if 陳述式的負荷，請改為呼叫 Debug.Assert(Boolean)：

public void PlayCMajor()
{
    Debug.Assert(OperatingSystem.IsWindows());
    Console.Beep(261, 1000);
}

如果您在撰寫程式庫，可以將 API 標記為平台特定。 在此情況下，將由您的呼叫者決定檢查需求的負擔。 您可以標記特定方法或類型，或是整個組件。

[SupportedOSPlatform("windows")]
public void PlayCMajor()
{
    Console.Beep(261, 1000);
}

如果您不想修正所有呼叫站台，可以選擇以下選項中的其中一個來隱藏警告：

  • 如要隱藏規則 CA1416，您可以使用 #pragma 或 NowWarn 編譯器旗標，或是在 .editorconfig 檔案中設定規則的嚴重性為 none。

    public void PlayCMajor()
{
#pragma warning disable CA1416
    Console.Beep(261, 1000);
#pragma warning restore CA1416
}

  • 若要完全停用程式碼分析，請在專案檔中將 EnableNETAnalyzers 設定為 false。 如需詳細資訊，請參閱 EnableNETAnalyzers。

受影響的 API

如為 Windows 平台：

如為 Blazor WebAssembly 平台：

另請參閱