UseCompatibleTypes

Nível de gravidade: Aviso

Descrição

Esta regra deteta tipos que não estão disponíveis por defeito nas suas plataformas PowerShell alvo.

Um nome na plataforma PowerShell é identificado no seguinte formato:

<os-name>_<os-arch>_<os-version>_<ps-version>_<ps-arch>_<dotnet-version>_<dotnet-edition>

Em que:

• <os-name>: O nome do sistema operacional em que o PowerShell está sendo executado. No Windows, o número SKU está incluído. No Linux, o valor é o nome da distribuição.
• <os-arch>: A arquitetura da máquina onde o sistema operativo está a correr (normalmente x64).
• <os-version>: A versão auto-reportada do sistema operativo (a versão de distribuição no Linux).
• <ps-version>: A versão do PowerShell (do $PSVersionTable.PSVersion).
• <ps-arch>: A arquitetura de máquina do processo do PowerShell.
• <dotnet-version>: A versão relatada do PowerShell de tempo de execução do .NET está sendo executada em (a partir de System.Environment.Version).
• <dotnet-edition>: O tipo de tempo de execução do .NET PowerShell está sendo executado em (atualmente framework ou core).

Por exemplo:

• win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework é o PowerShell 5.1 em execução no Windows 10 Enterprise (compilação 18312) para x64.
• win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core é o PowerShell 6.1.2 em execução no mesmo sistema operacional.
• ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core é o PowerShell 6.2.0 em execução no Ubuntu 18.04.

O PSScriptAnalyzer inclui alguns perfis de plataforma como ficheiros JSON. Pode direcionar estes perfis incorporados diretamente na sua configuração.

As plataformas agrupadas por padrão são:

Outros perfis podem ser encontrados no repositório GitHub.

Também pode gerar o seu próprio perfil de plataforma com o módulo PSCompatibilityCollector.

As definições de compatibilidade incluem uma lista de plataformas em TargetProfiles. Pode especificar cada plataforma-alvo como:

• Um nome de plataforma (por exemplo, ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). O PSScriptAnalyzer adiciona-o .json e procura-o no diretório de perfil predefinido.
• Um nome de ficheiro (por exemplo, my_custom_platform.json), que o PSScriptAnalyzer procura no diretório de perfil predefinido.
• Um caminho absoluto para um arquivo (como D:\PowerShellProfiles\TargetMachine.json).

O diretório de perfil padrão está sob o módulo PSScriptAnalyzer em $PSScriptRoot/PSCompatibilityCollector/profiles (onde $PSScriptRoot aqui se refere ao diretório que contém PSScriptAnalyzer.psd1).

A análise de compatibilidade compara cada tipo que utiliza tanto com um perfil alvo como com um perfil de união. O perfil union contém todos os tipos disponíveis em qualquer perfil no diretório de perfis.

Se um tipo não estiver no perfil sindical, a regra assume que é local ao teu ambiente e ignora-o. Se um tipo estiver no perfil de união mas ausente de um perfil alvo, a regra assinala-o como incompatível com esse alvo.

Exemplo

Os exemplos seguintes assumem TargetProfiles inclui win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework (Windows 10 Pro, PowerShell 5.1).

Não conforme

System.Management.Automation.SemanticVersion não está disponível por defeito no Windows PowerShell 5.1, por isso a regra assinala este tipo de utilização para esse perfil alvo.

$version = [System.Management.Automation.SemanticVersion]'1.2.3'

Compliant

System.Version está disponível em Windows PowerShell 5.1 e PowerShell 7, por isso passa nas verificações de compatibilidade entre esses alvos.

$version = [System.Version]'1.2.3.0'

Regra de configuração

Um exemplo de configuração pode ser parecido com:

@{
    Rules = @{
        PSUseCompatibleTypes = @{
            Enable = $true
            TargetProfiles = @(
                'ubuntu_x64_18.04_6.1.3_x64_4.0.30319.42000_core'
                'win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework'
                'MyProfile'
                'another_custom_profile_in_the_profiles_directory.json'
                'D:\My Profiles\profile1.json'
            )
            # You can specify types to not check like this, which will also ignore methods and members on it:
            IgnoreTypes = @(
                'System.IO.Compression.ZipFile'
            )
        }
    }
}

Como alternativa, você pode fornecer um objeto de configurações da seguinte maneira:

PS> $settings = @{
      Rules = @{
        PSUseCompatibleTypes = @{
          Enable = $true
          TargetProfiles = @('win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework')
        }
      }
}
PS> Invoke-ScriptAnalyzer -Settings $settings -ScriptDefinition "[System.Management.Automation.SemanticVersion]'1.18.0-rc1'"

RuleName                Severity     ScriptName Line  Message
--------                --------     ---------- ----  -------
PSUseCompatibleTypes    Warning                 1     The type 'System.Management.Automation.SemanticVersion' is
                                                      not available by default in PowerShell version
                                                      '5.1.17763.316' on platform 'Microsoft Windows 10 Pro'

Supressão

Tal como com outras regras, pode suprimir diagnósticos de compatibilidade de tipos adicionando um atributo de supressão ao param bloco de um bloco de scriptblock.

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes', '')]

Também pode suprimir a regra para tipos específicos:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes',
    'System.Management.Automation.Security.SystemPolicy')]

Também pode suprimi-lo para membros específicos do tipo:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes',
    'System.Management.Automation.LanguagePrimitives/ConvertTypeNameToPSTypeName')]

Parameters

Enable

Este parâmetro controla se o ScriptAnalyzer verifica o código com esta regra. Aceita um valor booleano. Para permitir esta regra, defina este parâmetro para $true. O valor predefinido é $false.

Perfis-Alvo

Este parâmetro especifica a lista de perfis de plataforma para verificar a compatibilidade. Ele aceita uma matriz de strings. Cada valor pode ser um nome de plataforma, um nome de ficheiro ou um caminho absoluto para um ficheiro de perfil. O valor predefinido é @().

ProfileDirPath

Este parâmetro controla o diretório que o ScriptAnalyzer procura por perfis por nome e utiliza para gerar o perfil de união. Aceita uma cadeia contendo um caminho absoluto. A localização padrão é o compatibility_profiles diretório no módulo PSScriptAnalyzer.

IgnoreTypes

Este parâmetro especifica os nomes completos dos tipos ou aceleradores de tipos a excluir das verificações de compatibilidade. Aceita um array de cadeias de nomes de tipo. O valor predefinido é @().