Compartir a través de

Advertencia CA1416: Compatibilidad de plataformas

  • Artículo

La regla CA1416 del analizador de código de .NET está habilitada de forma predeterminada a partir de .NET 5. Genera una advertencia de compilación para las llamadas a API específicas de la plataforma desde sitios de llamada que no comprueban el sistema operativo.

Descripción del cambio

A partir de .NET 5, el SDK de .NET incluye analizadores de código fuente de .NET. Varias de estas reglas están habilitadas de forma predeterminada, incluida la regla CA1416. Si el proyecto contiene código que infringe esta regla y está configurado para tratar las advertencias como errores, este cambio podría interrumpir la compilación. La regla CA1416 le notifica cuando está usando API específicas de la plataforma desde lugares donde no se comprueba el contexto de la plataforma.

La regla CA1416, del analizador de compatibilidad de la plataforma, funciona conjuntamente con otras características que son nuevas en .NET 5. .NET 5 presenta SupportedOSPlatformAttribute y UnsupportedOSPlatformAttribute, que permiten especificar las plataformas en las que una API se admite o no se admite. En ausencia de estos atributos, se supone que se admite una API en todas las plataformas. Estos atributos se han aplicado a muchas API específicas de la plataforma en las bibliotecas principales de .NET.

En los proyectos que tienen como destino las plataformas para las que no están disponibles las API que usan, la regla CA1416 marca cualquier llamada API específica de la plataforma en la que no se comprueba el contexto de la plataforma. La mayoría de las API que ahora están representadas con los atributos SupportedOSPlatformAttribute y UnsupportedOSPlatformAttribute producen excepciones PlatformNotSupportedException cuando se invocan en un sistema operativo no compatible. Ahora que estas API están marcadas como específicas de la plataforma, la regla CA1416 ayuda a evitar excepciones PlatformNotSupportedException en tiempo de ejecución mediante la adición de comprobaciones del sistema operativo a los sitios de llamada.

Ejemplos

  • El método Console.Beep(Int32, Int32) solo se admite en Windows y está decorado con el atributo [SupportedOSPlatform("windows")]. El código siguiente generará una advertencia CA1416 en tiempo de compilación si el proyecto tiene como destino net5.0 (multiplataforma). Pero este código no generará la advertencia si el proyecto tiene como destino Windows (net5.0-windows) y GenerateAssemblyInfo está habilitado para el proyecto. Para ver las acciones que puede realizar para evitar la advertencia, consulte la sección Acción recomendada.

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

  • El método Image.FromFile(String) no se admite en el explorador y está decorado con el atributo [UnsupportedOSPlatform("browser")]. El código siguiente generará una advertencia CA1416 en tiempo de compilación si el proyecto admite la plataforma del explorador.

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

    Sugerencia

    Los proyectos de Blazor WebAssembly y los de la biblioteca de clases de Razor incluyen compatibilidad con los exploradores automáticamente. Para agregar de forma manual el explorador como una plataforma compatible para el proyecto, agregue la entrada siguiente al archivo de proyecto:

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

Versión introducida

5.0

Asegúrese de que solo se llama a las API específicas de la plataforma cuando el código se ejecuta en la plataforma adecuada. Puede comprobar el sistema operativo actual mediante uno de los métodos Is<Platform> de la clase System.OperatingSystem (por ejemplo, OperatingSystem.IsWindows()) antes de llamar a una API específica de la plataforma.

Puede usar uno de los métodos Is<Platform> en la condición de una instrucción if:

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

O bien, si no quiere sobrecargar una instrucción if adicional en tiempo de ejecución, llame a Debug.Assert(Boolean) en su lugar:

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

Si va a crear una biblioteca, puede marcar la API como específica de la plataforma. En este caso, la carga de los requisitos de comprobación recae en los autores de las llamadas. Puede marcar métodos o tipos específicos, o un ensamblado completo.

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

Si no quiere corregir todos los sitios de llamada, puede elegir una de las siguientes opciones para suprimir la advertencia:

  • Para suprimir la regla CA1416, puede usar #pragma o la marca del compilador NoWarn, o bien puede establecer la gravedad de la regla en none en un archivo .editorconfig.

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

  • Para deshabilitar completamente el análisis de código, establezca EnableNETAnalyzers en false en el archivo del proyecto. Para obtener más información, vea EnableNETAnalyzers.

API afectadas

Para la plataforma Windows:

Para la plataforma de WebAssembly de Blazor:

Consulte también