CA1418: validar a compatibilidade da plataforma

  • Artigo
Property Valor
ID da regra CA1418
Título validar a compatibilidade da plataforma
Categoria Interoperabilidade
Correção interruptiva ou sem interrupção Sem interrupção
Habilitado por padrão no .NET 8 Como aviso

Causa

O analisador de compatibilidade de plataforma requer um nome e uma versão de plataforma válidos. Violações serão relatadas se a cadeia de caracteres de plataforma fornecida ao constructo OSPlatformAttribute consistir em um nome de plataforma desconhecido ou se a parte de versão opcional for inválida.

Descrição da regra

Os atributos de compatibilidade da plataforma derivados de OSPlatformAttribute usam literais de cadeia de caracteres para nomes de plataforma do sistema operacional (SO) com uma parte de versão opcional. A cadeia de caracteres deve consistir em um nome de plataforma conhecido e nenhuma parte da versão ou em uma parte da versão válida.

A lista de nomes de plataforma conhecidos é populada de dois locais:

  • A parte PlatformName dos métodos de proteção OperatingSystem chamada OperatingSystem.Is<PlatformName>[VersionAtLeast](). Por exemplo, o método de proteção OperatingSystem.IsWindows() adiciona Windows à lista de nomes de plataforma conhecidos.

  • O grupo de itens MSBuild de itens SupportedPlatform, incluindo a lista padrão MSBuild SupportedPlatforms. Esse é o conhecimento específico do projeto sobre plataformas conhecidas. Ele permite que os autores da biblioteca de classes adicionem mais plataformas à lista de plataformas conhecidas. Por exemplo:

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

Se a cadeia de caracteres de plataforma contiver uma parte de versão, ela deverá ser uma Version válida com o seguinte formato: major.minor[.build[.revision]].

Violações

  • Solaris é um nome de plataforma desconhecido, porque não está incluído na lista padrão MSBuild SupportedPlatforms e não há nenhum método de proteção de nome OperatingSystem.IsSolaris() na classe OperatingSystem.

    [SupportedOSPlatform("Solaris")] // Warns: The platform 'Solaris' is not a known platform name.
public void SolarisApi() { }

  • Android é uma plataforma conhecida, porque há um método de proteção OperatingSystem.IsAndroid() no tipo OperatingSystem. No entanto, a parte de versão não é uma versão válida. Ela deveria ter pelo menos dois inteiros separados por um ponto.

    [UnsupportedOSPlatform("Android10")] // Warns: Version '10' is not valid for platform 'Android'. Use a version with 2-4 parts for this platform.
public void DoesNotWorkOnAndroid() { }

  • Linux é uma plataforma conhecida, porque está incluída na lista padrão MSBuild SupportedPlatforms, e também há um método de proteção chamado OperatingSystem.IsLinux(). No entanto, não há métodos de proteção com versão como System.OperatingSystem.IsLinuxVersionAtLeast(int,int) para a plataforma Linux; portanto, não há suporte para nenhuma parte da versão no Linux.

    [SupportedOSPlatform("Linux4.8")] // Warns: Version '4.8' is not valid for platform 'Linux'. Do not use versions for this platform.
public void LinuxApi() { }

Como corrigir violações

  • Altere a plataforma para um nome de plataforma conhecido.

  • Se o nome da plataforma estiver correto e você quiser torná-lo uma plataforma conhecida, adicione-o à lista MSBuild SupportedPlatforms no arquivo de projeto:

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

    [SupportedOSPlatform("Solaris")] // No warning
public void SolarisApi() { }

  • Corrija a versão inválida. Por exemplo, no caso de Android, 10 não é uma versão válida, mas 10.0 é válida.

    // Before
[UnsupportedOSPlatform("Android10")] // Warns: Version '10' is not valid for platform 'Android'. Use a version with 2-4 parts for this platform.
public void DoesNotWorkOnAndroid() { }

// After
[UnsupportedOSPlatform("Android10.0")] // No warning.
public void DoesNotWorkOnAndroid() { }

  • Se a plataforma não der suporte a uma versão, remova a parte de versão.

    // Before
[SupportedOSPlatform("Linux4.8")] // Warns: Version '4.8' is not valid for platform 'Linux'. Do not use versions for this platform.
public void LinuxApi() { }

// After
[SupportedOSPlatform("Linux")] // No warning.
public void LinuxApi() { }

Quando suprimir avisos

Não é recomendável usar um nome de plataforma desconhecido ou uma versão inválida, ou seja, você não deve suprimir essa regra.

Confira também