PoužítCompatibleCommands

  • Článek

Úroveň závažnosti: Upozornění

Popis

Toto pravidlo identifikuje příkazy, které nejsou k dispozici na cílové platformě PowerShellu.

Platforma PowerShellu je označená názvem v následujícím formátu:

<os-name>_<os-arch>_<os-version>_<ps-version>_<ps-arch>_<dotnet-version>_<dotnet-edition>

Kde:

  • <os-name>: Název operačního systému, na kterém běží PowerShell. Ve Windows to zahrnuje číslo skladové položky. V Linuxu se jedná o název distribuce.
  • <os-arch>: Architektura počítače, na které běží operační systém (obvykle x64).
  • <os-version>: Verze operačního systému nahlášená vlastním držitelem (v Linuxu je to distribuční verze).
  • <ps-version>: Verze PowerShellu (z $PSVersionTable.PSVersion).
  • <ps-arch>: Architektura počítače procesu PowerShellu.
  • <dotnet-version>: Hlášená verze modulu runtime .NET PowerShellu běží na (z System.Environment.Version).
  • <dotnet-edition>: Prostředí PowerShell s modulem runtime .NET je spuštěné (aktuálně framework nebo core).

Příklad:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_frameworkje PowerShell 5.1 spuštěný v Windows 10 Enterprise (build 18312) pro x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core je PowerShell 6.1.2 spuštěný ve stejném operačním systému.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core je PowerShell 6.2.0 běžící na Ubuntu 18.04.

Některé platformy jsou součástí PSScriptAnalyzer jako soubory JSON, které jsou tímto způsobem pojmenovány pro cílení ve vaší konfiguraci.

Ve výchozím nastavení jsou balíčky platforem:

Verze PowerShellu Operační systém 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_6.2.4_x64_3.1.2_core

Další profily najdete v úložišti GitHub.

Můžete také vygenerovat vlastní profil platformy pomocí modulu PSCompatibilityCollector.

Nastavení profilu kompatibility obsahuje seznam platforem, na které se mají cílit v části TargetProfiles. Platformu je možné zadat takto:

  • Název platformy (například ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), který se .json přidá na konec a vyhledá se ve výchozím adresáři profilu.
  • Název souboru (například my_custom_platform.json), který se vyhledá ve výchozím adresáři profilu.
  • Absolutní cesta k souboru (například D:\PowerShellProfiles\TargetMachine.json).

Výchozí adresář profilu je v modulu PSScriptAnalzyer na adrese $PSScriptRoot/compatibility_profiles (kde $PSScriptRoot zde odkazuje na adresář obsahující PSScriptAnalyzer.psd1).

Analýza kompatibility porovnává použitý příkaz s cílovým profilem i s profilem union (obsahující všechny příkazy dostupné v libovolném profilu v adresáři profilu). Pokud se příkaz ve sjednocovacím profilu nenachází, předpokládá se jeho místní vytvoření a ignorování. Jinak platí, že pokud je příkaz přítomen ve sjednocovacím profilu, ale není k dispozici v cíli, považuje se za nekompatibilní s tímto cílem.

Nastavení konfigurace

Konfigurační klíč Význam Přípustné hodnoty Povinné Příklad
Enable Aktivuje pravidlo. bool ($true/$false) Ne (výchozí: $false) $true
TargetProfiles Seznam profilů PowerShellu, na které chcete cílit string[]: absolutní cesty k souborům profilů nebo názvům profilů v adresáři profilů Ne (výchozí: @()) @('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 Umístění pro vyhledání profilů podle názvu a použití pro generování sjednocovacího profilu string: absolutní cesta k adresáři nového profilu Ne (výchozí hodnota je compatibility_profiles adresář v modulu PSScriptAnalyzer. C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Příkazy, které mají ignorovat kompatibilitu ve skriptech string[]: názvy příkazů, které se mají ignorovat Ne (výchozí: @()) @('Get-ChildItem','Import-Module')

Příklad konfigurace může vypadat takto:

@{
    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'
            )
        }
    }
}

Potlačení

Diagnostiku kompatibility příkazů je možné potlačit atributem bloku param scriptblock stejně jako u jiných pravidel.

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

Pravidlo lze také potlačit pouze pro konkrétní příkazy:

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

A také potlačeno pouze pro parametry:

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