Warnung CA1416: Plattformkompatibilität

Die .NET-Codeanalyseregel CA1416 ist ab .NET 5 standardmäßig aktiviert. Sie erzeugt eine Buildwarnung für Aufrufe an plattformspezifische APIs von Aufrufsites, bei denen das Betriebssystem nicht überprüft wird.

Änderungsbeschreibung

Ab .NET 5 umfasst das .NET SDK .NET-Quellcodeanalysen. Einige dieser Regeln, darunter CA1416, sind standardmäßig aktiviert. Wenn Ihr Projekt Code enthält, der gegen diese Regel verstößt und dafür konfiguriert ist, Warnungen als Fehler zu interpretieren, könnte es sich hierbei um einen Breaking Change für Ihr Build handeln. Die Regel CA1416 informiert Sie darüber, wenn Sie plattformspezifische APIs über Orte verwenden, an denen der Plattformkontext nicht überprüft wird.

Regel CA1416, das Analysetool für die Plattformkompatibilität, arbeitet mit einigen anderen Features zusammen, die neu in .NET 5 sind. In NET 5 werden SupportedOSPlatformAttribute und UnsupportedOSPlatformAttribute eingeführt, mit denen Sie die Plattformen angeben können, auf denen eine API unterstützt wird oder nicht. Wenn diese Attribute nicht vorhanden sind, wird davon ausgegangen, dass eine API auf allen Plattformen unterstützt wird. Diese Attribute wurden auf plattformspezifische APIs in den wichtigsten .NET-Bibliotheken angewendet.

In Projekten für Plattformen, für die die verwendeten APIs nicht verfügbar sind, kennzeichnet die Regel CA1416 alle plattformspezifischen API-Aufrufe, bei denen der Plattformkontext nicht überprüft wird. Die meisten APIs, die nun mit den Attributen SupportedOSPlatformAttribute und UnsupportedOSPlatformAttribute versehen sind, lösen PlatformNotSupportedException-Ausnahmen aus, wenn sie unter einem nicht unterstützten Betriebssystem aufgerufen werden. Da diese APIs nun als plattformspezifisch gekennzeichnet sind, hilft Ihnen die Regel CA1416 dabei, PlatformNotSupportedException-Ausnahmen zur Laufzeit zu verhindern, indem Überprüfungen des Betriebssystems zu Ihren Aufrufsites hinzugefügt werden.

Beispiele

  • Die Methode Console.Beep(Int32, Int32) wird nur unter Windows unterstützt, und sie ist mit [SupportedOSPlatform("windows")] versehen. Der folgende Code erzeugt zur Buildzeit eine CA1416-Warnung, wenn das Projekt net5.0als Ziel verwendet (plattformübergreifend). Dieser Code gibt jedoch keine Warnung aus, wenn das Projekt Windows als Ziel verwendet (net5.0-windows) und die GenerateAssemblyInfo für das Projekt aktiviert ist. Mögliche Maßnahmen, um diese Warnung zu vermeiden, finden Sie unter Empfohlene Maßnahme.

    public void PlayCMajor()
    {
        Console.Beep(261, 1000);
    }
    
  • Die Methode Image.FromFile(String) wird im Browser nicht unterstützt, und sie ist mit [UnsupportedOSPlatform("browser")] versehen. Der folgende Code erzeugt eine CA1416-Warnung zur Buildzeit, wenn das Projekt die Browserplattform unterstützt.

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

    Tipp

    • In Blazor WebAssembly-Projekten und Projekten der Razor-Klassenbibliothek ist die Browserunterstützung automatisch enthalten.
    • Wenn Sie den Browser manuell als unterstützte Plattform Ihrem Projekt hinzufügen möchten, fügen Sie den folgenden Eintrag zu Ihrer Projektdatei hinzu:
    <ItemGroup>
      <SupportedPlatform Include="browser" />
    </ItemGroup>
    

Eingeführt in Version

5.0

Stellen Sie sicher, dass plattformspezifische APIs nur aufgerufen werden, wenn der Code auf der entsprechenden Plattform ausgeführt wird. Sie können vor dem Aufrufen einer plattformspezifischen API mithilfe einer der Is<Platform>-Methoden in der Klasse System.OperatingSystem, z. B. OperatingSystem.IsWindows(), das aktuelle Betriebssystem überprüfen.

Sie können eine der Is<Platform>-Methoden in der Bedingung einer if-Anweisung verwenden:

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

Wenn Sie den Aufwand einer zusätzlichen if-Anweisung zur Laufzeit vermeiden möchten, können Sie alternativ Debug.Assert(Boolean) aufrufen:

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

Wenn Sie eine Bibliothek erstellen, können Sie Ihre API als plattformspezifisch markieren. In diesem Fall fällt der Aufwand für die Überprüfung von Anforderungen für Ihre Aufrufer weg. Sie können bestimmte Methoden oder Typen oder eine gesamte Assembly markieren.

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

Wenn Sie nicht alle Ihre Aufrufsites ändern möchten, können Sie die Warnung durch eine der folgenden Vorgehensweisen unterdrücken:

  • Wenn Sie die Regel CA1416 unterdrücken möchten, können Sie hierfür #pragma oder das Compilerflag NoWarn verwenden oder den Schweregrad für die Regel in einer .editorconfig-Datei auf none festlegen.

    public void PlayCMajor()
    {
    #pragma warning disable CA1416
        Console.Beep(261, 1000);
    #pragma warning restore CA1416
    }
    
  • Legen Sie EnableNETAnalyzers in Ihrer Projektdatei auf false fest, um die Codeanalyse vollständig zu deaktivieren. Weitere Informationen finden unter EnableNETAnalyzers.

Betroffene APIs

Für die Windows-Plattform:

Für die Blazor WebAssembly-Plattform:

Weitere Informationen