UseCompatibleTypes

Nível de gravidade: Aviso

Estado padrão: Desativado

Descrição

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

Os nomes das plataformas PowerShell usam o 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'

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 é @().

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')]