UseCompatibleCommands
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 (normalmentex64
, é ). -
<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 deSystem.Environment.Version
). -
<dotnet-edition>
: O sabor de runtime .NET do PowerShell está em execução no (atualmenteframework
oucore
).
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.psd1
conté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')]