Delen via

Waarschuwing CA1416: Platformcompatibiliteit

.NET Code Analyzer-regel CA1416 is standaard ingeschakeld vanaf .NET 5. Er wordt een buildwaarschuwing gegenereerd voor aanroepen naar platformspecifieke API's van oproepsites die het besturingssysteem niet verifiëren.

Wijzigingsbeschrijving

Vanaf .NET 5 bevat de .NET SDK .NET-broncodeanalyses. Verschillende van deze regels zijn standaard ingeschakeld, waaronder CA1416. Als uw project code bevat die deze regel schendt en is geconfigureerd om waarschuwingen als fouten te behandelen, kan deze wijziging de build verbreken. Regel CA1416 informeert u wanneer u platformspecifieke API's gebruikt vanaf locaties waar de platformcontext niet wordt geverifieerd.

Regel CA1416, de platformcompatibiliteitsanalyse, werkt hand in hand met enkele andere functies die nieuw zijn in .NET 5. .NET 5 introduceert de SupportedOSPlatformAttribute en UnsupportedOSPlatformAttribute, waarmee u de platforms kunt opgeven waarop een API wel of niet wordt ondersteund. Bij afwezigheid van deze kenmerken wordt ervan uitgegaan dat een API wordt ondersteund op alle platforms. Deze kenmerken zijn toegepast op platformspecifieke API's in de kernbibliotheken van .NET.

In projecten die zijn gericht op platformen waarvoor API's die ze gebruiken niet beschikbaar zijn, markeert regel CA1416 een platformspecifieke API-aanroep waarbij de platformcontext niet wordt geverifieerd. De meeste API's die nu zijn ingericht met de SupportedOSPlatformAttribute en UnsupportedOSPlatformAttribute kenmerken genereren PlatformNotSupportedException uitzonderingen wanneer ze worden aangeroepen op een niet-ondersteund besturingssysteem. Nu deze API's zijn gemarkeerd als platformspecifiek, helpt regel CA1416 u runtime-uitzonderingen PlatformNotSupportedException te voorkomen door besturingssysteemcontroles toe te voegen aan uw oproepsites.

Voorbeelden

  • De Console.Beep(Int32, Int32) methode wordt alleen ondersteund in Windows en is ingericht met [SupportedOSPlatform("windows")]. Met de volgende code wordt tijdens het bouwen een CA1416-waarschuwing gegenereerd als de projectdoelen (platformoverschrijdend) worden bereiktnet5.0 . Deze code waarschuwt echter niet als het project is gericht op Windows (net5.0-windows) en het GenerateAssemblyInfo is ingeschakeld voor het project. Zie Aanbevolen actie voor acties die u kunt ondernemen om de waarschuwing te voorkomen.

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

  • De Image.FromFile(String) methode wordt niet ondersteund in de browser en is ingericht met [UnsupportedOSPlatform("browser")]. Met de volgende code wordt tijdens het bouwen een CA1416-waarschuwing gegenereerd als het project het browserplatform ondersteunt.

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

    Aanbeveling

    Blazor WebAssembly-projecten en Razor-klassebibliotheekprojecten bevatten automatisch browserondersteuning. Als u de browser handmatig wilt toevoegen als een ondersteund platform voor uw project, voegt u de volgende vermelding toe aan uw projectbestand:

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

Versie geïntroduceerd

5,0

Zorg ervoor dat platformspecifieke API's alleen worden aangeroepen wanneer de code wordt uitgevoerd op een geschikt platform. U kunt het huidige besturingssysteem controleren met behulp van een van de Is<Platform> methoden in de System.OperatingSystem klasse, OperatingSystem.IsWindows()bijvoorbeeld voordat u een platformspecifieke API aanroept.

U kunt een van de Is<Platform> methoden in de voorwaarde van een if instructie gebruiken:

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

Als u de overhead van een extra if instructie tijdens runtime niet wilt, roep dan in plaats daarvan Debug.Assert(Boolean) aan.

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

Als u een bibliotheek ontwerpt, kunt u uw API markeren als platformspecifiek. In dit geval valt de last van het controleren van de vereisten op uw bellers. U kunt specifieke methoden of typen of een hele assembly markeren.

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

Als u niet al uw oproepsites wilt herstellen, kunt u een van de volgende opties kiezen om de waarschuwing te onderdrukken:

  • Als u regel CA1416 wilt onderdrukken, kunt u dit doen met de #pragma vlag van de NoWarn-compiler of door de ernstnone van de regel in te stellen op een .editorconfig-bestand.

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

  • Als u codeanalyse volledig wilt uitschakelen, stelt u deze in EnableNETAnalyzersfalse uw projectbestand in. Zie EnableNETAnalyzers voor meer informatie.

Betrokken API's

Voor Windows-platform:

Voor blazor WebAssembly-platform:

Zie ook

  • Last updated on