Aviso CA1416: compatibilidade da plataforma

  • Artigo

A regra CA1416 do analisador de código do .NET está habilitada por padrão do .NET 5 em diante. Ele produz um aviso de build para chamadas a APIs específicas da plataforma de sites de chamada que não verificam o sistema operacional.

Descrição das alterações

Do .NET 5 em diante, o SDK do .NET inclui Analisadores de código-fonte do .NET. Várias dessas regras são habilitadas, por padrão, inclusive a CA1416. Se o projeto contiver um código que viole essa regra e estiver configurado para tratar avisos como erros, essa alteração poderá interromper o build. A regra CA1416 informa quando você está usando APIs específicas da plataforma em locais onde o contexto da plataforma não é verificado.

A regra CA1416, o analisador de compatibilidade da plataforma, opera lado a lado com alguns outros recursos que são novos no .NET 5. O .NET 5 apresenta SupportedOSPlatformAttribute e UnsupportedOSPlatformAttribute, que permite especificar as plataformas em que uma API tem ou não tem suporte. Na ausência desses atributos, supõe-se que uma API tenha suporte em todas as plataformas. Esses atributos foram aplicados a APIs específicas da plataforma nas bibliotecas principais do .NET.

Em projetos destinados a plataformas para as quais as APIs que eles usam não estão disponíveis, a regra CA1416 sinaliza qualquer chamada à API específica da plataforma em que o contexto da plataforma não é verificado. A maioria das APIs que agora são decoradas com os atributos SupportedOSPlatformAttribute e UnsupportedOSPlatformAttribute geram exceções PlatformNotSupportedException quando são invocadas em um sistema operacional sem suporte. Agora que essas APIs estão marcadas como específicas da plataforma, a regra CA1416 ajuda você a evitar exceções PlatformNotSupportedException no tempo de execução adicionando verificações de SO aos sites de chamadas.

Exemplos

  • O método Console.Beep(Int32, Int32) só tem suporte no Windows e é decorado com [SupportedOSPlatform("windows")]. O código a seguir produzirá um aviso CA1416 no momento da compilação se o projeto for direcionado para net5.0 (multiplataforma). Mas esse código não avisará se o projeto for direcionado ao Windows (net5.0-windows) e GenerateAssemblyInfo estiver habilitado para o projeto. Para ver as ações que podem ser executadas para evitar o aviso, confira Ações recomendadas.

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

  • O método Image.FromFile(String) não tem suporte no navegador e é decorado com [UnsupportedOSPlatform("browser")]. O código a seguir produzirá um aviso CA1416 no momento do build se o projeto der suporte à plataforma do navegador.

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

    Dica

    Projetos do Blazor WebAssembly e da Biblioteca de Classes Razor incluem o suporte ao navegador automaticamente. Para adicionar manualmente o navegador como uma plataforma com suporte em seu projeto, adicione a seguinte entrada ao arquivo de projeto:

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

Versão introduzida

5,0

Verifique se as APIs específicas da plataforma só são chamadas quando o código está em execução em uma plataforma apropriada. Você pode verificar o sistema operacional atual usando um dos métodos Is<Platform> da classe System.OperatingSystem, por exemplo, OperatingSystem.IsWindows(), antes de chamar uma API específica da plataforma.

Você pode usar um dos métodos Is<Platform> na condição de uma instrução if:

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

Ou, se não quiser a sobrecarga de uma instrução if adicional em tempo de execução, chame Debug.Assert(Boolean) em vez disso:

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

Se você estiver criando uma biblioteca, poderá marcar sua API como específica da plataforma. Nesse caso, o ônus de verificar os requisitos recai sobre seus chamadores. Você pode marcar métodos, tipos específicos ou um assembly inteiro.

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

Se você não quiser corrigir todos os seus sites de chamadas, poderá escolher uma das seguintes opções para suprimir o aviso:

  • Para suprimir a regra CA1416, você pode fazer isso usando #pragma ou o sinalizador do compilador NoWarn, ou ainda definir a gravidade da regra como none no arquivo .editorconfig.

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

  • Para desabilitar completamente a análise de código, defina EnableNETAnalyzers como false no arquivo de projeto. Para obter mais informações, confira EnableNETAnalyzers.

APIs afetadas

Para a plataforma Windows:

Para a plataforma Blazor WebAssembly:

Confira também