Avertissement CA1416 : compatibilité de plateforme

  • Article

La règle d’analyseur de code .NET CA1416 est activée par défaut à partir de .NET 5. Cela génère un avertissement de build pour les appels à des API spécifiques à la plateforme à partir de sites d’appel qui ne vérifient pas le système d’exploitation.

Description de la modification

À compter de .NET 5, le SDK .NET inclut des analyseurs de code source .NET. Plusieurs de ces règles sont activées par défaut, y compris CA1416. Si votre projet contient du code qui enfreint cette règle et est configuré pour traiter les avertissements comme des erreurs, cette modification peut interrompre votre build. La règle CA1416 vous informe lorsque vous utilisez des API spécifiques à la plateforme à partir d’endroits où le contexte de la plateforme n’est pas vérifié.

La règle CA1416 (analyseur de compatibilité de plateforme) fonctionne main dans la main avec d’autres fonctionnalités qui sont nouvelles dans .NET 5. .NET 5 introduit SupportedOSPlatformAttribute et UnsupportedOSPlatformAttribute, qui vous permettent de spécifier les plateformes sur lesquelles une API est ou n’est pas prise en charge. En l’absence de ces attributs, une API est supposée être prise en charge sur toutes les plateformes. Ces attributs ont été appliqués aux API spécifiques à la plateforme dans les bibliothèques .NET principales.

Dans les projets qui ciblent des plateformes pour lesquelles les API qu’elles utilisent ne sont pas disponibles, la règle CA1416 signale tout appel d’API spécifique à la plateforme pour lequel le contexte de la plateforme n’est pas vérifié. La plupart des API qui sont désormais décorées avec les attributs SupportedOSPlatformAttribute et UnsupportedOSPlatformAttribute lèvent des exceptions PlatformNotSupportedException lorsqu’elles sont appelées sur un système d’exploitation non pris en charge. Maintenant que ces API sont marquées comme propres à la plateforme, la règle CA1416 vous aide à empêcher les exceptions PlatformNotSupportedException à l’exécution en ajoutant des vérifications du système d’exploitation à vos sites d’appel.

Exemples

  • La méthode Console.Beep(Int32, Int32) est uniquement prise en charge sur Windows et est décorée avec [SupportedOSPlatform("windows")]. Le code suivant génère un avertissement CA1416 au moment de la génération si le projet ciblenet5.0 (multiplateforme). Toutefois, ce code n’avertit pas si le projet cible Windows (net5.0-windows) et si GenerateAssemblyInfo est activé pour le projet. Pour connaître les actions que vous pouvez effectuer pour éviter l’avertissement, consultez Action recommandée.

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

  • La méthode Image.FromFile(String) n’est pas prise en charge dans le navigateur et est décorée avec [UnsupportedOSPlatform("browser")]. Le code suivant génère un avertissement CA1416 au moment de la génération si le projet prend en charge la plateforme du navigateur.

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

    Conseil

    Les projets Blazor WebAssembly et les projets de bibliothèque de classes Razor incluent automatiquement la prise en charge du navigateur. Pour ajouter manuellement le navigateur en tant que plateforme prise en charge pour votre projet, ajoutez l’entrée suivante à votre fichier projet :

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

Version introduite

5,0

Assurez-vous que les API spécifiques à la plateforme ne sont appelées que lorsque le code s’exécute sur une plateforme appropriée. Vous pouvez vérifier le système d’exploitation actuel à l’aide de l’une des méthodes Is<Platform> de la classe System.OperatingSystem, par exemple, OperatingSystem.IsWindows(), avant d’appeler une API spécifique à la plateforme.

Vous pouvez utiliser l’une des méthodes Is<Platform> dans la condition d’une instruction if :

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

Ou, si vous ne souhaitez pas la surcharge d’une instruction if supplémentaire au moment de l’exécution, appelez Debug.Assert(Boolean) à la place :

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

Si vous créez une bibliothèque, vous pouvez marquer votre API comme spécifique à la plateforme. Dans ce cas, le fardeau de la vérification des exigences incombe à vos appelants. Vous pouvez marquer des méthodes ou des types spécifiques ou un assembly entier.

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

Si vous ne souhaitez pas corriger tous vos sites d’appel, vous pouvez choisir l’une des options suivantes pour supprimer l’avertissement :

  • Pour supprimer la règle CA1416, vous pouvez le faire à l’aide de #pragma ou de l’indicateur de compilateur NoWarn, ou en définissant la gravité de la règle sur none dans un fichier .editorconfig.

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

  • Pour désactiver complètement l’analyse du code, définissez EnableNETAnalyzers sur false dans votre fichier projet. Pour plus d’informations, consultez EnableNETAnalyzers.

API affectées

Pour la plateforme Windows :

Pour la plateforme Blazor WebAssembly :

Voir aussi