UseCompatibleTypes

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

Výchozí stav: Zakázáno

Popis

Toto pravidlo detekuje typy, které nejsou ve výchozím nastavení dostupné na vašich cílových platformách PowerShell.

PowerShell názvy platforem používají následující formát:

<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ý. Na Windows je číslo SKU. Na Linuxu je hodnota název distribuce.
<os-arch>: Architektura stroje, na které operační systém běží (obvykle x64).
<os-version>: Verze operačního systému, která se sama hlásila (distribuční verze na Linuxu).
<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.

PSScriptAnalyzer zahrnuje některé profily platforem jako JSON soubory. Tyto vestavěné profily můžete cílit přímo ve své 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 si také vytvořit vlastní profil platformy pomocí modulu PSCompatibilityCollector.

Nastavení kompatibility uvádí seznam platforem pod .TargetProfiles Každou cílovou platformu můžete specifikovat jako:

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

Výchozí adresář profilu je pod modulem PSScriptAnalyzer na ( $PSScriptRoot/PSCompatibilityCollector/profiles kde $PSScriptRoot zde odkazuje na adresář obsahující PSScriptAnalyzer.psd1).

Analýza kompatibility porovnává každý typ, který použijete, jak s cílovým profilem, tak s odborovým profilem. Sjednocený profil obsahuje všechny typy dostupné v jakémkoli profilu v adresáři profilů.

Pokud typ není v profilu svazu, pravidlo předpokládá, že je lokální pro vaše prostředí a ignoruje ho. Pokud je typ v union profilu, ale chybí v cílovém profilu, pravidlo ho označí jako nekompatibilní s tímto cílem.

Příklad

Následující příklady předpokládají, že TargetProfiles zahrnuje win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework (Windows 10 Pro, PowerShell 5.1).

Nesplňující

System.Management.Automation.SemanticVersion není ve Windows PowerShell 5.1 ve výchozím nastavení dostupný, takže pravidlo označuje tento typ použití pro daný cílový profil.

$version = [System.Management.Automation.SemanticVersion]'1.2.3'

Kompatibilní

System.Version je dostupný v Windows PowerShell 5.1 a PowerShell 7, takže prochází kontrolami kompatibility napříč těmito cíli.

$version = [System.Version]'1.2.3.0'

Konfigurovat pravidlo

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'

Parameters

Enable

Tento parametr ovládá, zda ScriptAnalyzer kontroluje kód podle tohoto pravidla. Přijímá booleovskou hodnotu. Pro povolení tohoto pravidla nastavte tento parametr na .$true Výchozí hodnota je $false.

TargetProfiles

Tento parametr specifikuje seznam profilů platforem, proti kterým je třeba ověřit kompatibilitu. Přijímá pole řetězců. Každá hodnota může být název platformy, název souboru nebo absolutní cesta k souboru profilu. Výchozí hodnota je @().

ProfileDirPath

Tento parametr řídí adresář, který ScriptAnalyzer vyhledává profily podle názvu a používá k generování union profilu. Přijímá řetězec obsahující absolutní cestu. Výchozí umístění je compatibility_profiles adresář v modulu PSScriptAnalyzer.

IgnoreTypes

Tento parametr specifikuje plné názvy typů nebo akcelerátorů typů, které je třeba vyloučit z kontrol kompatibility. Přijímá pole řetězců typových jmen. Výchozí hodnota je @().

Potlačení

Stejně jako u jiných pravidel můžete diagnostiku kompatibility typů potlačit přidáním atributu potlačení do bloku param skriptbloku.

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

Pravidlo můžete také potlačit pro konkrétní typy:

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

Můžete ji také potlačit pro konkrétní typové členy:

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-21