Freigeben über

UseCompatibleTypes

  • Artikel

Schweregrad: Warnung

Beschreibung

Diese Regel identifiziert Typen, die in bestimmten PowerShell-Plattformen nicht verfügbar (standardmäßig geladen) 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/PSCompatibilityCollector/profiles (wobei $PSScriptRoot hier auf das Verzeichnis verweist, das PSScriptAnalyzer.psd1enthält).

Die Kompatibilitätsanalyse vergleicht einen Typ, der sowohl mit einem Zielprofil als auch mit einem "Union"-Profil verwendet wird (mit allen typen, die in einem beliebigen Profil im Profilverzeichnis verfügbar sind). Wenn ein Typ nicht im Union-Profil vorhanden ist, wird davon ausgegangen, dass er lokal erstellt und ignoriert wird. Andernfalls gilt, wenn ein Typ 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
IgnoreTypes Vollständige Namen von Typen oder Typbeschleunigern, um die Kompatibilität von Skripts zu ignorieren string[]: Namen der zu ignorierenden Typen Nein (Standard: @()) @('System.Collections.ArrayList','string')

Eine Beispielkonfiguration könnte wie folgt aussehen:

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

Alternativ können Sie ein Einstellungsobjekt wie folgt bereitstellen:

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'

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('PSUseCompatibleTypes', '')]

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

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

Und auch nur für Typmitglieder unterdrückt:

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