Sdílet prostřednictvím

UseCompatibleTypes

  • Článek

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

Popis

Toto pravidlo identifikuje typy, které nejsou dostupné (ve výchozím nastavení načtené) v cílových platformách PowerShellu.

Platforma PowerShellu je identifikována 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 prostředí PowerShell operačního systému je spuštěný. Ve Windows to zahrnuje číslo skladové položky. V Linuxu se jedná o název distribuce.
  • <os-arch>: Architektura počítače, na které operační systém běží (obvykle x64).
  • <os-version>: Verze operačního systému hlášená vlastním hlášením (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 PowerShellu modulu runtime .NET je spuštěná (z System.Environment.Version).
  • <dotnet-edition>: Modul runtime .NET je spuštěný v PowerShellu (aktuálně framework nebo core).

Například:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework je PowerShell 5.1 spuštěný ve Windows 10 Enterprise (build 18312) pro platformu 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 pojmenované tímto způsobem pro cílení na vaši konfiguraci.

Platformy, které jsou ve výchozím nastavení součástí, jsou:

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 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 Windows 10.0.14393 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10.0.17763 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 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 Windows 10.0.14393 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0 Windows 10.0.17763 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0 Windows 10.0.18362 win-4_x64_10.0.18362.0_7.0.0_x64_3.1.2_core

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

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

Nastavení profilu kompatibility přebírá seznam platforem, které se mají cílit v rámci 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ý bude mít .json přidán na konec a vyhledá se ve výchozím adresáři profilu.
  • Název souboru (například my_custom_platform.json), který bude prohledán 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 v $PSScriptRoot/PSCompatibilityCollector/profiles (kde $PSScriptRoot zde odkazuje na adresář obsahující PSScriptAnalyzer.psd1).

Analýza kompatibility porovnává typ použitý jak s cílovým profilem, tak sjednocovacího profilu (obsahující všechny typy dostupné v libovolném profilu v dir profilu). Pokud typ není v sjednocovacího profilu, předpokládá se, že se místně vytvoří a ignoruje. Jinak platí, že pokud je typ v sjednocovacího profilu, ale není v cíli, považuje se za nekompatibilní s tímto cílem.

Nastavení konfigurace

Konfigurační klíč Význam Přijaté hodnoty Povinný Příklad
Enable Aktivuje pravidlo. bool ($true/$false) Ne (výchozí hodnota: $false) $true
TargetProfiles Seznam profilů PowerShellu, které se mají cílit string[]: Absolutní cesty k souborům profilů nebo názvům profilů v adresáři profilu Ne (výchozí hodnota: @()) @('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ávání profilů podle názvu a použití pro generování sjednocovacího profilu string: absolutní cesta k novému adresáři profilu Ne (výchozí hodnota je compatibility_profiles adresář v modulu PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreTypes Úplné názvy typů neboakcech string[]: názvy typů, které se mají ignorovat Ne (výchozí hodnota: @()) @('System.Collections.ArrayList','string')

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

@{
    Rules = @{
        PSUseCompatibleTypes = @{
            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 types to not check like this, which will also ignore methods and members on it:
            IgnoreTypes = @(
                'System.IO.Compression.ZipFile'
            )
        }
    }
}

Případně můžete zadat objekt nastavení následujícím způsobem:

PS> $settings = @{
      Rules = @{
        PSUseCompatibleTypes = @{
          Enable = $true
          TargetProfiles = @('win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework')
        }
      }
}
PS> Invoke-ScriptAnalyzer -Settings $settings -ScriptDefinition "[System.Management.Automation.SemanticVersion]'1.18.0-rc1'"

RuleName                Severity     ScriptName Line  Message
--------                --------     ---------- ----  -------
PSUseCompatibleTypes    Warning                 1     The type 'System.Management.Automation.SemanticVersion' is
                                                      not available by default in PowerShell version
                                                      '5.1.17763.316' on platform 'Microsoft Windows 10 Pro'

Potlačení

Diagnostiku kompatibility příkazů lze potlačit atributem na param bloku skriptu jako u jiných pravidel.

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

Pravidlo lze také potlačit pouze pro konkrétní typy:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes',
    'System.Management.Automation.Security.SystemPolicy')]

A také potlačeno pouze pro členy typu:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'System.Management.Automation.LanguagePrimitives/ConvertTypeNameToPSTypeName')]