Udostępnij za pośrednictwem

Ostrzeżenie CA1416: Zgodność platformy

  • Artykuł

Reguła analizatora kodu platformy .NET CA1416 jest domyślnie włączona, począwszy od platformy .NET 5. Tworzy ostrzeżenie kompilacji dla wywołań interfejsów API specyficznych dla platformy z lokacji wywołań, które nie weryfikują systemu operacyjnego.

Opis zmiany

Począwszy od platformy .NET 5, zestaw .NET SDK zawiera analizatory kodu źródłowego platformy .NET. Kilka z tych reguł jest domyślnie włączonych, w tym CA1416. Jeśli projekt zawiera kod, który narusza tę regułę i jest skonfigurowany do traktowania ostrzeżeń jako błędów, ta zmiana może spowodować przerwanie kompilacji. Reguła CA1416 informuje o używaniu interfejsów API specyficznych dla platformy z miejsc, w których kontekst platformy nie jest weryfikowany.

Reguła CA1416, analizator zgodności platformy, działa ręcznie z innymi funkcjami, które są nowe na platformie .NET 5. W programie SupportedOSPlatformAttribute .NET 5 wprowadzono elementy i UnsupportedOSPlatformAttribute, które pozwalają określić platformy, na których działa interfejs API lub nie jest obsługiwany. W przypadku braku tych atrybutów zakłada się, że interfejs API jest obsługiwany na wszystkich platformach. Te atrybuty zostały zastosowane do interfejsów API specyficznych dla platformy w podstawowych bibliotekach platformy .NET.

W projektach przeznaczonych dla platform docelowych, dla których interfejsy API, których używają, nie są dostępne, reguła CA1416 flaguje dowolne wywołanie interfejsu API specyficzne dla platformy, w którym kontekst platformy nie jest weryfikowany. Większość interfejsów API, które są teraz ozdobione atrybutami SupportedOSPlatformAttribute i UnsupportedOSPlatformAttribute zgłasza PlatformNotSupportedException wyjątki, gdy są wywoływane w nieobsługiwanym systemie operacyjnym. Teraz, gdy te interfejsy API są oznaczone jako specyficzne dla platformy, reguła CA1416 pomaga zapobiec wyjątkom czasu PlatformNotSupportedException wykonywania przez dodanie kontroli systemu operacyjnego do witryn połączeń.

Przykłady

  • Metoda jest obsługiwana Console.Beep(Int32, Int32) tylko w systemie Windows i jest ozdobiona elementem [SupportedOSPlatform("windows")]. Poniższy kod spowoduje wygenerowanie ostrzeżenia CA1416 w czasie kompilacji, jeśli projekt jest przeznaczonynet5.0 dla celów (międzyplatformowych). Jednak ten kod nie będzie ostrzegać, jeśli projekt jest przeznaczony dla systemu Windows (net5.0-windows) i GenerateAssemblyInfo jest włączony dla projektu. Aby uzyskać informacje o akcjach, które można wykonać, aby uniknąć ostrzeżenia, zobacz Zalecane działanie.

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

  • Metoda nie jest obsługiwana Image.FromFile(String) w przeglądarce i jest ozdobiona elementem [UnsupportedOSPlatform("browser")]. Poniższy kod spowoduje wygenerowanie ostrzeżenia CA1416 w czasie kompilacji, jeśli projekt obsługuje platformę przeglądarki.

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

    Napiwek

    Projekty zestawu WebAssembly platformy Blazor i projekty bibliotek klas Razor obejmują automatyczne obsługę przeglądarki. Aby ręcznie dodać przeglądarkę jako obsługiwaną platformę dla projektu, dodaj następujący wpis do pliku projektu:

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

Wprowadzona wersja

5,0

Upewnij się, że interfejsy API specyficzne dla platformy są wywoływane tylko wtedy, gdy kod działa na odpowiedniej platformie. Bieżący system operacyjny można sprawdzić przy użyciu jednej z Is<Platform> metod w System.OperatingSystem klasie, na przykład OperatingSystem.IsWindows(), przed wywołaniem interfejsu API specyficznego dla platformy.

Można użyć jednej z Is<Platform> metod w warunku instrukcji if :

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

Lub, jeśli nie chcesz narzut dodatkowej if instrukcji w czasie wykonywania, wywołaj Debug.Assert(Boolean) zamiast tego:

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

Jeśli tworzysz bibliotekę, możesz oznaczyć interfejs API jako specyficzny dla platformy. W takim przypadku ciężar sprawdzania wymagań spada na rozmówców. Można oznaczyć określone metody lub typy lub cały zestaw.

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

Jeśli nie chcesz naprawiać wszystkich witryn połączeń, możesz wybrać jedną z następujących opcji, aby pominąć ostrzeżenie:

  • Aby pominąć regułę CA1416, można to zrobić za pomocą #pragmaflagi kompilatora NoWarn lub ustawiając ważność reguły na none w pliku editorconfig.

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

  • Aby całkowicie wyłączyć analizę kodu, ustaw wartość EnableNETAnalyzers na false w pliku projektu. Aby uzyskać więcej informacji, zobacz EnableNETAnalyzers.

Dotyczy interfejsów API

Dla platformy Windows:

Dla platformy WebAssembly platformy Blazor:

Zobacz też