Partilhar via

UseCompatibleCommands

  • Artigo

Nível de Gravidade: Aviso

Description

Esta regra identifica comandos que não estão disponíveis numa plataforma do PowerShell direcionada.

Uma plataforma do 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 operativo no qual o PowerShell está em execução. No Windows, isto inclui o número de SKU. No Linux, este é o nome da distribuição.
  • <os-arch>: a arquitetura da máquina em que o sistema operativo está a ser executado (normalmente x64, é ).
  • <os-version>: a versão auto-comunicada do sistema operativo (no Linux, esta é a versão de distribuição).
  • <ps-version>: a versão do PowerShell (de $PSVersionTable.PSVersion).
  • <ps-arch>: a arquitetura do computador do processo do PowerShell.
  • <dotnet-version>: A versão comunicada do PowerShell de runtime do .NET está em execução (a partir de System.Environment.Version).
  • <dotnet-edition>: O sabor de runtime .NET do PowerShell está em execução no (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 operativo.
  • 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 são agrupadas com o PSScriptAnalyzer como ficheiros JSON, nomeados desta forma para segmentação na sua configuração.

As plataformas agrupadas por predefinição são:

Versão do PowerShell Sistema Operativo ID
3.0 Windows Server 2012 win-8_x64_6.2.9200.0_3.0_x64_4.0.30319.42000_framework
4.0 Windows Server 2012R2 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 1809 (RS5) win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6.2 Windows Server 2016 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows Server 2019 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
7.0 Windows Server 2016 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0 Windows Server 2019 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_3.1.2_core
7.0 Ubuntu 18.04 LTS ubuntu_x64_18.04_7.0.0_x64_3.1.2_core

Podem ser encontrados outros perfis no repositório do GitHub.

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

As definições do perfil de compatibilidade levam uma lista de plataformas a visar 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 é procurado no diretório de perfil predefinido.
  • Um nome de ficheiro (como my_custom_platform.json), que será procurado no diretório de perfil predefinido.
  • Um caminho absoluto para um ficheiro (como D:\PowerShellProfiles\TargetMachine.json).

O diretório de perfil predefinido está no módulo PSScriptAnalzyer em $PSScriptRoot/compatibility_profiles (onde $PSScriptRoot aqui se refere ao diretório que PSScriptAnalyzer.psd1contém ).

A análise de compatibilidade compara um comando utilizado tanto com um perfil de destino como com um perfil "união" (que contém todos os comandos disponíveis em qualquer perfil no dir do perfil). Se um comando não estiver presente no perfil do sindicato, assume-se que foi criado localmente e ignorado. Caso contrário, se um comando estiver presente no perfil do sindicato, mas não estiver presente num destino, 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 (predefinição: $false) $true
TargetProfiles A lista de perfis do PowerShell para destino string[]: caminhos absolutos para ficheiros de perfil ou nomes de perfis no diretório de perfil Não (predefiniçã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 A localização para procurar perfis por nome e utilização para a geração de perfis sindicais cadeia: caminho absoluto para o novo dir de perfil Não (predefinições para o compatibility_profiles diretório no módulo PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Comandos para ignorar a compatibilidade de em scripts string[]: nomes de comandos a ignorar Não (predefinição: @()) @('Get-ChildItem','Import-Module')

Uma configuração de exemplo pode ter o seguinte aspeto:

@{
    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

Os diagnósticos de compatibilidade de comandos podem ser suprimidos com um atributo no param bloco de um scriptblock como 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')]