Freigeben über

UseCompatibleCommands

  • Artikel

Schweregrad: Warnung

Beschreibung

Diese Regel identifiziert Befehle, die auf einer bestimmten PowerShell-Plattform nicht verfügbar sind.

Eine PowerShell-Plattform wird durch einen Namen im folgenden Format identifiziert:

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

Wo:

  • <os-name>: Der Name des Betriebssystems PowerShell wird ausgeführt. Unter Windows enthält dies die SKU-Nummer. Unter Linux ist dies der Name der Verteilung.
  • <os-arch>: Die Computerarchitektur, auf der das Betriebssystem ausgeführt wird (dies ist in der Regel x64).
  • <os-version>: Die selbst gemeldete Version des Betriebssystems (unter Linux, dies ist die Verteilungsversion).
  • <ps-version>: Die PowerShell-Version (von $PSVersionTable.PSVersion).
  • <ps-arch>: Die Computerarchitektur des PowerShell-Prozesses.
  • <dotnet-version>: Die gemeldete Version der .NET-Laufzeit-PowerShell wird ausgeführt (von System.Environment.Version).
  • <dotnet-edition>: Die .NET-Laufzeit-Aroma-PowerShell wird ausgeführt (derzeit framework oder core).

Zum Beispiel:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework ist PowerShell 5.1 unter Windows 10 Enterprise (Build 18312) für x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core ist PowerShell 6.1.2 auf demselben Betriebssystem ausgeführt.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core ist PowerShell 6.2.0 unter Ubuntu 18.04 ausgeführt.

Einige Plattformen werden mit PSScriptAnalyzer als JSON-Dateien gebündelt, die auf diese Weise für die Zielbestimmung in Ihrer Konfiguration benannt sind.

Standardmäßig gebündelte Plattformen sind:

PowerShell-Version Betriebssystem 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

Weitere Profile finden Sie im GitHub-Repository.

Sie können auch Ihr eigenes Plattformprofil mithilfe des PSCompatibilityCollector-Modulsgenerieren.

Die Kompatibilitätsprofileinstellungen enthalten eine Liste der Plattformen, die unter TargetProfilesals Ziel verwendet werden sollen. Eine Plattform kann wie möglich angegeben werden:

  • Ein Plattformname (z. B. ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), der am Ende .json hinzugefügt und im Standardprofilverzeichnis gesucht wird.
  • Ein Dateiname (wie my_custom_platform.json), der im Standardprofilverzeichnis nach dem gesucht wird.
  • Ein absoluter Pfad zu einer Datei (z. B. D:\PowerShellProfiles\TargetMachine.json).

Das Standardprofilverzeichnis befindet sich unter dem PSScriptAnalzyer-Modul bei $PSScriptRoot/compatibility_profiles (wobei $PSScriptRoot hier auf das Verzeichnis verweist, das PSScriptAnalyzer.psd1enthält).

Die Kompatibilitätsanalyse vergleicht einen Befehl, der sowohl mit einem Zielprofil als auch mit einem "Union"-Profil verwendet wird (mit allen befehlen, die in einem beliebigen Profil im Profilverzeichnis verfügbar sind). Wenn kein Befehl im Union-Profil vorhanden ist, wird davon ausgegangen, dass er lokal erstellt und ignoriert wird. Andernfalls gilt ein Befehl, wenn ein Befehl im Union-Profil vorhanden, aber nicht in einem Ziel vorhanden ist, als nicht mit diesem Ziel kompatibel ist.

Konfigurationseinstellungen

Konfigurationsschlüssel Bedeutung Akzeptierte Werte Obligatorisch Beispiel
Enable Aktiviert die Regel. bool ($true/$false) Nein (Standard: $false) $true
TargetProfiles Die Liste der powerShell-Profile, die als Ziel verwendet werden sollen string[]: absolute Pfade zu Profildateien oder Namen von Profilen im Profilverzeichnis Nein (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 Der Speicherort für die Suche nach Profilen nach Name und Verwendung für die Union-Profilgenerierung string: absoluter Pfad zu neuem Profil dir Nein (Standardeinstellung für compatibility_profiles Verzeichnis im PSScriptAnalyzer-Modul C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Befehle zum Ignorieren der Kompatibilität von Skripts string[]: Namen der zu ignorierenden Befehle Nein (Standard: @()) @('Get-ChildItem','Import-Module')

Eine Beispielkonfiguration könnte wie folgt aussehen:

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

Unterdrückung

Die Befehlskompatibilitätsdiagnose kann mit einem Attribut im param Block eines Scriptblocks wie bei anderen Regeln unterdrückt werden.

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

Die Regel kann auch nur für bestimmte Befehle unterdrückt werden:

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

Und auch nur für Parameter unterdrückt:

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