UseCompatibleCommands

Schweregrad: Warnung

Beschreibung

Diese Regel erkennt Befehle, die auf deiner jeweiligen PowerShell-Plattform nicht verfügbar sind.

Ein Name in der PowerShell-Plattform wird 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 ist die SKU-Nummer enthalten. Unter Linux ist der Wert der Name der Distribution.
• <os-arch>: Die Maschinenarchitektur, auf der das Betriebssystem läuft (üblicherweise x64).
• <os-version>: Die selbstberichtete Version des Betriebssystems (die Distribution-Version unter Linux).
• <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.

PSScriptAnalyzer enthält einige Plattformprofile als JSON-Dateien. Du kannst diese integrierten Profile direkt in deiner Konfiguration ansteuern.

Standardmäßig gebündelte Plattformen sind:

Weitere Profile finden Sie im GitHub-Repository.

Du kannst auch dein eigenes Plattformprofil mit dem PSCompatibilityCollector-Modul erstellen.

Die Kompatibilitätseinstellungen nehmen eine Liste von Plattformen unter TargetProfiles. Sie können jede Zielplattform wie folgt angeben:

• Ein Plattformname (zum Beispiel, ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). PSScriptAnalyzer fügt .json es im Standard-Profilverzeichnis an und sucht danach.
• Ein Dateiname (zum Beispiel my_custom_platform.json), nach dem PSScriptAnalyzer im Standard-Profilverzeichnis sucht.
• Ein absoluter Pfad zu einer Datei (z. B. D:\PowerShellProfiles\TargetMachine.json).

Das Standard-Profilverzeichnis befindet sich unter dem PSScriptAnalyzer-Modul bei $PSScriptRoot/compatibility_profiles (wobei $PSScriptRoot sich hier auf das Verzeichnis PSScriptAnalyzer.psd1mit ) bezieht.

Die Kompatibilitätsanalyse vergleicht jeden von Ihnen verwendeten Befehl sowohl mit einem Zielprofil als auch mit einem Union-Profil. Das Union-Profil enthält jeden Befehl, der in jedem Profil im Profilverzeichnis verfügbar ist.

Wenn ein Befehl nicht im Union-Profil ist, nimmt die Regel an, dass er lokal in deiner Umgebung ist und ignoriert ihn. Wenn ein Befehl im Union-Profil ist, aber im Zielprofil fehlt, markiert die Regel ihn als inkompatibel mit diesem Ziel.

Beispiel

Die folgenden Beispiele nehmen Folgendes an TargetProfiles ( ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core Ubuntu 18.04, PowerShell 6.2).

Nicht konform

function Get-OsInfo {
    $os = Get-WmiObject -Class Win32_OperatingSystem
    return $os.Caption
}

Konform

function Get-OsInfo {
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
    return $os.Caption
}

Configure rule

@{
    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

Wie bei anderen Regeln kann man Befehlskompatibilitätsdiagnosen unterdrücken, indem man dem Block eines Skriptblocks ein Unterdrückungsattribut param hinzufügt.

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

Du kannst die Regel auch für bestimmte Befehle unterdrücken:

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

Du kannst es auch für bestimmte Parameter unterdrücken:

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

Parameter

Aktivieren

Dieser Parameter steuert, ob ScriptAnalyzer den Code anhand dieser Regel prüft. Es akzeptiert einen boolschen Wert. Um diese Regel zu aktivieren, setze diesen Parameter auf $true. Der Standardwert ist $false.

TargetProfiles

Dieser Parameter spezifiziert die Liste der Plattformprofile, mit denen die Kompatibilität überprüft werden soll. Für diese Angabe wird ein Zeichenfolgenarray akzeptiert. Jeder Wert kann ein Plattformname, ein Dateiname oder ein absoluter Pfad zu einer Profildatei sein. Der Standardwert ist @().

ProfileDirPath

Dieser Parameter steuert das Verzeichnis, das ScriptAnalyzer nach Profilen nach Namen sucht und verwendet, um das Union-Profil zu generieren. Sie akzeptiert eine Zeichenkette, die einen absoluten Pfad enthält. Der Standardstandort ist das compatibility_profiles Verzeichnis im PSScriptAnalyzer-Modul.

IgnorierenBefehle

Dieser Parameter spezifiziert Befehle, die von Kompatibilitätsprüfungen ausgeschlossen werden. Es akzeptiert ein Array von Befehlsnamen-Zeichenfolgen. Der Standardwert ist @().