UseCompatibleCommands

Nível de gravidade: Aviso

Descrição

Esta regra deteta comandos que não estão disponíveis na tua plataforma 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/compatibility_profiles (onde $PSScriptRoot aqui se refere ao diretório que contém PSScriptAnalyzer.psd1).

A análise de compatibilidade compara cada comando que usa tanto com um perfil alvo como com um perfil de união. O perfil de união contém todos os comandos disponíveis em qualquer perfil do diretório do perfil.

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

Exemplo

Os exemplos seguintes assumem TargetProfiles que inclui ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core (Ubuntu 18.04, PowerShell 6.2).

Não conforme

function Get-OsInfo {
    $os = Get-WmiObject -Class Win32_OperatingSystem
    return $os.Caption
}

Compliant

function Get-OsInfo {
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
    return $os.Caption
}

Regra de configuração

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

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

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

Também podes suprimir a regra para comandos específicos:

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

Também pode suprimi-la para parâmetros específicos:

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

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.

IgnoreCommands

Este parâmetro especifica comandos a excluir das verificações de compatibilidade. Aceita um array de cadeias de nomes de comandos. O valor predefinido é @().