Partilhar via

UseCompatibleCommands

  • Artigo

Nível de gravidade: Aviso

Descrição

Esta regra identifica comandos que não estão disponíveis em uma plataforma PowerShell de destino.

Uma plataforma PowerShell é identificada por um nome 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, isso inclui o número SKU. No Linux, este é o nome da distribuição.
  • <os-arch>: A arquitetura da máquina em que o sistema operacional está sendo executado (geralmente é x64).
  • <os-version>: A versão auto-relatada do sistema operacional (no Linux, esta é a versão de distribuição).
  • <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.

Algumas plataformas vêm junto com o PSScriptAnalyzer como arquivos JSON, nomeados dessa forma para direcionamento em sua configuração.

As plataformas agrupadas por padrão são:

Versão do PowerShell Sistema Operativo Identificação
3.0 Windows Server 2012 win-8_x64_6.2.9200.0_3.0_x64_4.0.30319.42000_framework
4.0 Windows Server 2012 R2 win-8_x64_6.3.9600.0_4.0_x64_4.0.30319.42000_framework
5.1 Windows Server 2016 win-8_x64_10.0.14393.0_5.1.14393.2791_x64_4.0.30319.42000_framework
5.1 Windows Server 2019 win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
5.1 Windows 10 Pro win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6.2 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
6.2 Janelas 10.0.14393 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2 Janelas 10.0.17763 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Janelas 10.0.18362 win-4_x64_10.0.18362.0_6.2.4_x64_4.0.30319.42000_core
7.0 Ubuntu 18.04 LTS ubuntu_x64_18.04_7.0.0_x64_3.1.2_core
7.0 Janelas 10.0.14393 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0 Janelas 10.0.17763 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0 Janelas 10.0.18362 win-4_x64_10.0.18362.0_7.0.0_x64_3.1.2_core

Outros perfis podem ser encontrados no repositório GitHub.

Você também pode gerar seu próprio perfil de plataforma usando o módulo PSCompatibilityCollector.

As configurações de perfil de compatibilidade levam uma lista de plataformas para segmentar em TargetProfiles. Uma plataforma pode ser especificada como:

  • Um nome de plataforma (como ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), que terá .json adicionado ao final e é pesquisado no diretório de perfil padrão.
  • Um nome de arquivo (como my_custom_platform.json), que será pesquisado para o no diretório de perfil padrão.
  • Um caminho absoluto para um arquivo (como D:\PowerShellProfiles\TargetMachine.json).

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

A análise de compatibilidade compara um comando usado com um perfil de destino e um perfil 'união' (contendo todos os comandos disponíveis em qualquer perfil no perfil dir). Se um comando não estiver presente no perfil da união, presume-se que ele seja criado localmente e ignorado. Caso contrário, se um comando estiver presente no perfil da união, mas não estiver presente em um destino, ele será considerado incompatível com esse destino.

Definições de configuração

Chave de configuração Significado Valores aceites Obrigatório Exemplo
Enable Ativa a regra Bool ($true/$false) Não (padrão: $false) $true
TargetProfiles A lista de perfis do PowerShell a serem direcionados string[]: caminhos absolutos para arquivos de perfil ou nomes de perfis no diretório de perfis Não (padrão: @()) @('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')
ProfileDirPath O local para pesquisar perfis por nome e usar para a geração de perfis de união string: caminho absoluto para novo perfil dir Não (padrão para compatibility_profiles diretório no módulo PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Comandos para ignorar a compatibilidade de scripts in string[]: nomes de comandos a serem ignorados Não (padrão: @()) @('Get-ChildItem','Import-Module')

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

@{
    Rules = @{
        PSUseCompatibleCommands = @{
            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 commands to not check like this, which also will ignore its parameters:
            IgnoreCommands = @(
                'Install-Module'
            )
        }
    }
}

Supressão

O diagnóstico de compatibilidade de comandos pode ser suprimido com um atributo no bloco param de um scriptblock como acontece com outras regras.

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

A regra também pode ser suprimida apenas para comandos específicos:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Start-Service')]

E também suprimido apenas para parâmetros:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Import-Module/FullyQualifiedName')]