Varning CA1416: Plattformskompatibilitet

Artikel
10/04/2023

.NET-kodanalysregeln CA1416 är aktiverad som standard med början i .NET 5. Den skapar en byggvarning för anrop till plattformsspecifika API:er från anropsplatser som inte verifierar operativsystemet.

Ändra beskrivning

Från och med .NET 5 innehåller .NET SDK .NET-källkodsanalyserare. Flera av dessa regler är aktiverade som standard, inklusive CA1416. Om projektet innehåller kod som bryter mot den här regeln och är konfigurerat för att behandla varningar som fel kan den här ändringen bryta mot bygget. Regel CA1416 informerar dig när du använder plattformsspecifika API:er från platser där plattformskontexten inte verifieras.

Regel CA1416, plattformskompatibilitetsanalyseraren, fungerar hand i hand med några andra funktioner som är nya i .NET 5. .NET 5 introducerar SupportedOSPlatformAttribute och UnsupportedOSPlatformAttribute, som gör att du kan ange de plattformar som ett API är eller inte stöds på. I avsaknad av dessa attribut antas ett API stödjas på alla plattformar. Dessa attribut har tillämpats på plattformsspecifika API:er i kärnbiblioteken för .NET.

I projekt som är målplattformar för vilka API:er som de använder inte är tillgängliga flaggar regel CA1416 alla plattformsspecifika API-anrop där plattformskontexten inte verifieras. De flesta API:er som nu är dekorerade med attributen SupportedOSPlatformAttribute och UnsupportedOSPlatformAttribute genererar PlatformNotSupportedException undantag när de anropas på ett operativsystem som inte stöds. Nu när dessa API:er har markerats som plattformsspecifika hjälper regel CA1416 dig att förhindra körningsfel genom att lägga till OS-kontroller PlatformNotSupportedException på dina anropswebbplatser.

Exempel

Metoden Console.Beep(Int32, Int32) stöds endast i Windows och är dekorerad med [SupportedOSPlatform("windows")]. Följande kod genererar en CA1416-varning vid byggtiden om projektet är mål net5.0 (plattformsoberoende). Men den här koden varnar inte om projektet riktar sig mot Windows (net5.0-windows) och GenerateAssemblyInfo är aktiverat för projektet. Åtgärder som du kan vidta för att undvika varningen finns i Rekommenderad åtgärd.
```
public void PlayCMajor()
{
    Console.Beep(261, 1000);
}
```
Metoden Image.FromFile(String) stöds inte i webbläsaren och är dekorerad med [UnsupportedOSPlatform("browser")]. Följande kod skapar en CA1416-varning vid byggtiden om projektet stöder webbläsarplattformen.
```
public void CreateImage()
{
    Image newImage = Image.FromFile("SampImag.jpg");
}
```
Dricks

Blazor WebAssembly-projekt och Razor-klassbiblioteksprojekt inkluderar webbläsarstöd automatiskt. Om du vill lägga till webbläsaren manuellt som en plattform som stöds för projektet lägger du till följande post i projektfilen:
```
<ItemGroup>
  <SupportedPlatform Include="browser" />
</ItemGroup>
```

Version introducerad

5,0

Rekommenderad åtgärd

Se till att plattformsspecifika API:er endast anropas när koden körs på en lämplig plattform. Du kan kontrollera det aktuella operativsystemet med någon av Is<Platform> metoderna i System.OperatingSystem klassen, OperatingSystem.IsWindows()till exempel , innan du anropar ett plattformsspecifikt API.

Du kan använda någon av Is<Platform> metoderna i villkoret för en if -instruktion:

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

Om du inte vill ha mer information om en extra if instruktion vid körningen anropar Debug.Assert(Boolean) du i stället:

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

Om du redigerar ett bibliotek kan du markera ditt API som plattformsspecifikt. I det här fallet faller ansvaret för att kontrollera kraven på dina uppringare. Du kan markera specifika metoder eller typer eller en hel sammansättning.

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

Om du inte vill åtgärda alla samtalswebbplatser kan du välja något av följande alternativ för att förhindra varningen:

Om du vill utelämna regeln CA1416 kan du göra det med hjälp av #pragma eller nowarn-kompilatorflaggan, eller genom att ange regelns allvarlighetsgrad till none i en .editorconfig-fil.
```
public void PlayCMajor()
{
#pragma warning disable CA1416
    Console.Beep(261, 1000);
#pragma warning restore CA1416
}
```
Om du vill inaktivera kodanalys helt anger du EnableNETAnalyzers till false i projektfilen. Mer information finns i EnableNETAnalyzers.

Berörda API:er

För Windows-plattformen:

För Blazor WebAssembly-plattformen:

Alla API:er som anges på https://github.com/dotnet/runtime/issues/41087.

Dela via