Partilhar via

Aviso CA1416: Compatibilidade da plataforma

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

Alterar a descrição

A partir do .NET 5, o SDK do .NET inclui analisadores de código-fonte do .NET. Várias dessas regras estão habilitadas, por padrão, incluindo CA1416. Se o seu projeto contém código que viola essa regra e está configurado para tratar avisos como erros, essa alteração pode quebrar sua compilação. A regra CA1416 informa quando você está usando APIs específicas da plataforma de locais onde o contexto da plataforma não é verificado.

A regra CA1416, o analisador de compatibilidade de plataforma, trabalha lado a lado com alguns outros recursos que são novos no .NET 5. O .NET 5 apresenta o SupportedOSPlatformAttribute e UnsupportedOSPlatformAttribute, que permite especificar as plataformas nas quais uma API é ou não suportada. Na ausência desses atributos, presume-se que uma API seja suportada em todas as plataformas. Esses atributos foram aplicados a APIs específicas da plataforma nas principais bibliotecas .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 de 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 SupportedOSPlatformAttribute atributos e UnsupportedOSPlatformAttribute lançam PlatformNotSupportedException exceções quando são invocadas em um sistema operacional sem suporte. Agora que estas APIs estão marcadas como específicas da plataforma, a regra CA1416 ajuda-o a evitar exceções em tempo PlatformNotSupportedException de execução ao adicionar verificações do sistema operativo aos seus sites de chamadas.

Exemplos

  • O Console.Beep(Int32, Int32) método só é suportado no Windows e é decorado com [SupportedOSPlatform("windows")]. O código a seguir produzirá um aviso CA1416 no momento da compilação se os alvos(plataforma cruzada). Mas esse código não avisa se o projeto tem como alvo o Windows (net5.0-windows) e o GenerateAssemblyInfo está habilitado para o projeto. Para ações que você pode tomar para evitar o aviso, consulte Ação recomendada.

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

  • O Image.FromFile(String) método não é suportado no navegador e é decorado com [UnsupportedOSPlatform("browser")]. O código a seguir produzirá um aviso CA1416 no momento da compilação se o projeto suportar a plataforma do navegador.

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

    Gorjeta

    Os projetos Blazor WebAssembly e os projetos de biblioteca de classes Razor incluem suporte automático ao navegador. Para adicionar manualmente o navegador como uma plataforma suportada para o seu projeto, adicione a seguinte entrada ao seu arquivo de projeto:

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

Versão introduzida

5.0

Certifique-se de que as APIs específicas da plataforma só sejam chamadas quando o código estiver sendo executado em uma plataforma apropriada. Você pode verificar o sistema operacional atual usando um dos métodos na Is<Platform> classe, por exemplo, System.OperatingSystemantes de chamar uma API específica da OperatingSystem.IsWindows() plataforma.

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

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

Ou, se não quiser o sobrecusto de uma instrução adicional if 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. Neste caso, o ónus da verificação dos requisitos recai sobre os seus chamadores. Você pode marcar métodos ou tipos específicos ou um assembly inteiro.

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

Se não quiser corrigir todos os seus sites de chamadas, você pode 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 definindo a severidade da regra como none em um arquivo .editorconfig.

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

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

APIs afetadas

Para a plataforma Windows:

Para a plataforma Blazor WebAssembly:

Consulte também

  • Last updated on