Avviso CA1416: Compatibilità della piattaforma

  • Articolo

La regola dell'analizzatore del codice .NET CA1416 è abilitata, per impostazione predefinita, a partire da .NET 5. Genera un avviso di compilazione per le chiamate alle API specifiche della piattaforma dai siti di chiamata che non verificano il sistema operativo.

Descrizione delle modifiche

A partire da .NET 5, .NET SDK include analizzatori del codice sorgente .NET. Diverse di queste regole sono abilitate, per impostazione predefinita, tra cui CA1416. Se il progetto contiene codice che viola questa regola ed è configurato per considerare gli avvisi come errori, questa modifica potrebbe interrompere la compilazione. La regola CA1416 indica quando si usano API specifiche della piattaforma da posizioni in cui il contesto della piattaforma non viene verificato.

La regola CA1416, l'analizzatore di compatibilità della piattaforma, funziona in parallelo con alcune altre funzionalità nuove di .NET 5. .NET 5 introduce SupportedOSPlatformAttribute e UnsupportedOSPlatformAttribute, che consentono di specificare le piattaforme in cui un'API è o non è supportata. In assenza di questi attributi, si presuppone che un'API sia supportata in tutte le piattaforme. Tali attributi sono stati applicati alle API specifiche della piattaforma nelle librerie .NET di base.

Nei progetti destinati alle piattaforme per le quali le API usate non sono disponibili, la regola CA1416 contrassegna qualsiasi chiamata API specifica della piattaforma in cui il contesto della piattaforma non viene verificato. La maggior parte delle API ora decorate con gli attributi SupportedOSPlatformAttribute e UnsupportedOSPlatformAttribute generano eccezioni PlatformNotSupportedException quando vengono richiamate in un sistema operativo non supportato. Ora che queste API sono contrassegnate come specifiche della piattaforma, la regola CA1416 consente di evitare eccezioni PlatformNotSupportedException in fase di esecuzione aggiungendo controlli del sistema operativo per i siti di chiamata.

Esempi

  • Il metodo Console.Beep(Int32, Int32) è supportato solo in Windows ed è integrato con [SupportedOSPlatform("windows")]. Il codice seguente genererà un avviso CA1416 in fase di compilazione se il progetto ha come destinazione net5.0 (multipiattaforma). Questo codice non verrà tuttavia segnalato come avviso se il progetto è destinato a Windows (net5.0-windows) e l'oggetto GenerateAssemblyInfo viene abilitato per il progetto. Per le azioni che è possibile eseguire per evitare l'avviso, vedere Azione consigliata.

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

  • Il metodo Image.FromFile(String) non è supportato nel browser ed è integrato con [UnsupportedOSPlatform("browser")]. Il codice seguente genererà un avviso CA1416 in fase di compilazione se il progetto supporta la piattaforma del browser.

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

    Suggerimento

    I progetti Blazor WebAssembly e i progetti di libreria di classi Razor includono automaticamente il supporto del browser. Per aggiungere manualmente il browser come piattaforma supportata per il progetto, aggiungere la voce seguente al file di progetto:

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

Versione introdotta

5.0

Assicurarsi che le API specifiche della piattaforma vengano chiamate solo quando il codice è in esecuzione su una piattaforma appropriata. È possibile controllare il sistema operativo corrente usando uno dei metodi Is<Platform> nella classe System.OperatingSystem, ad esempio OperatingSystem.IsWindows(), prima di chiamare un'API specifica della piattaforma.

È possibile usare uno dei metodi Is<Platform> nella condizione di un'istruzione if:

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

Oppure, se non si vuole che l'overhead di un'istruzione aggiuntiva if in fase di esecuzione, chiamare Debug.Assert(Boolean) in alternativa:

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

Se si crea una libreria, è possibile contrassegnare l'API come specifica della piattaforma. In questo caso, l'onere di verificare i requisiti ricade sui chiamanti. È possibile contrassegnare metodi o tipi specifici o un intero assembly.

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

Se non si desidera correggere tutti i siti di chiamata, è possibile scegliere una delle opzioni seguenti per eliminare l'avviso:

  • L’eliminazione della regola CA1416 è possibile attraverso l’utilizzo di #pragma o del flag del compilatore NoWarn oppure impostando la gravità della regola su none in un file con estensione editorconfig.

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

  • Per disabilitare completamente l'analisi del codice, impostare EnableNETAnalyzers su false nel file di progetto. Per altre informazioni, vedere EnableNETAnalyzers.

API interessate

Per la piattaforma Windows:

Per la piattaforma Blazor WebAssembly:

Vedi anche