UseCompatibleCommands

Allvarlighetsgrad: Varning

Description

Den här regeln identifierar kommandon som inte är tillgängliga på en riktad PowerShell-plattform.

En PowerShell-plattform identifieras med ett namn i följande format:

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

Plats:

  • <os-name>: Namnet på operativsystemet som PowerShell körs på. I Windows inkluderar detta SKU-numret. I Linux är det här namnet på distributionen.
  • <os-arch>: Datorarkitekturen som operativsystemet körs på (detta är vanligtvis x64).
  • <os-version>: Den självrapporterade versionen av operativsystemet (i Linux är det här distributionsversionen).
  • <ps-version>: PowerShell-versionen (från $PSVersionTable.PSVersion).
  • <ps-arch>: Datorarkitekturen i PowerShell-processen.
  • <dotnet-version>: Den rapporterade versionen av .NET Runtime PowerShell körs på (från System.Environment.Version).
  • <dotnet-edition>: .NET-körningssmaken PowerShell körs på (för närvarande framework eller core).

Ett exempel:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_frameworkär PowerShell 5.1 som körs på Windows 10 Enterprise (version 18312) för x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core är PowerShell 6.1.2 som körs på samma operativsystem.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core är PowerShell 6.2.0 som körs på Ubuntu 18.04.

Vissa plattformar levereras med PSScriptAnalyzer som JSON-filer, namngivna på det här sättet för målanpassning i konfigurationen.

Plattformar som paketeras som standard är:

PowerShell-version Operativsystem 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

Andra profiler finns på GitHub-lagringsplatsen.

Du kan också generera en egen plattformsprofil med hjälp av modulen PSCompatibilityCollector.

Kompatibilitetsprofilinställningarna tar en lista över plattformar som ska riktas under TargetProfiles. En plattform kan anges som:

  • Ett plattformsnamn (till exempel ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), som har .json lagts till i slutet och söks efter i standardprofilkatalogen.
  • Ett filnamn (till exempel my_custom_platform.json), som söks efter i standardprofilkatalogen.
  • En absolut sökväg till en fil (som D:\PowerShellProfiles\TargetMachine.json).

Standardprofilkatalogen finns under PSScriptAnalzyer-modulen på $PSScriptRoot/compatibility_profiles (där $PSScriptRoot här refererar till katalogen som innehåller PSScriptAnalyzer.psd1).

Kompatibilitetsanalysen jämför ett kommando som används för både en målprofil och en "union"-profil (som innehåller alla kommandon som är tillgängliga i alla profiler i profildir). Om ett kommando inte finns i union-profilen antas det vara lokalt skapat och ignorerat. Om ett kommando finns i union-profilen men inte finns i ett mål anses det annars vara inkompatibelt med det målet.

Konfigurationsinställningar

Konfigurationsnyckel Innebörd Godkända värden Obligatorisk Exempel
Enable Aktiverar regeln bool ($true/$false) Nej (standard: $false) $true
TargetProfiles Listan över PowerShell-profiler som ska riktas string[]: absoluta sökvägar till profilfiler eller namn på profiler i profilkatalogen Nej (standard: @()) @('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 Platsen för att söka efter profiler efter namn och använda för generering av union-profiler string: absolut sökväg till ny profildir Nej (standardkatalogen compatibility_profiles i PSScriptAnalyzer-modulen C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Kommandon för att ignorera kompatibilitet för i skript string[]: namn på kommandon som ska ignoreras Nej (standard: @()) @('Get-ChildItem','Import-Module')

En exempelkonfiguration kan se ut så här:

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

Undertryckning

Diagnostik för kommandokompatibilitet kan ignoreras med ett attribut i param blocket för en scriptblock som med andra regler.

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

Regeln kan också ignoreras endast för vissa kommandon:

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

Och ignoreras endast för parametrar:

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