Share via

UseCompatibleCommands

  • Article

Niveau de gravité : avertissement

Description

Cette règle identifie les commandes qui ne sont pas disponibles sur une plateforme PowerShell ciblée.

Une plateforme PowerShell est identifiée par un nom au format suivant :

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

Où :

  • <os-name>: nom du système d’exploitation PowerShell en cours d’exécution. Sur Windows, cela inclut le numéro de référence SKU. Sur Linux, il s’agit du nom de la distribution.
  • <os-arch>: architecture de machine sur laquelle le système d’exploitation s’exécute (il s’agit généralement x64de ).
  • <os-version>: version auto-déclarée du système d’exploitation (sur Linux, il s’agit de la version de distribution).
  • <ps-version>: version PowerShell (à partir de $PSVersionTable.PSVersion).
  • <ps-arch>: architecture de machine du processus PowerShell.
  • <dotnet-version>: la version signalée du runtime .NET PowerShell s’exécute sur (à partir de System.Environment.Version).
  • <dotnet-edition>: la version de runtime .NET PowerShell s’exécute sur (actuellement framework ou core).

Par exemple :

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_frameworkPowerShell 5.1 s’exécute sur Windows 10 Entreprise (build 18312) pour x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core PowerShell 6.1.2 s’exécute sur le même système d’exploitation.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core est PowerShell 6.2.0 s’exécutant sur Ubuntu 18.04.

Certaines plateformes sont fournies avec PSScriptAnalyzer en tant que fichiers JSON, nommés de cette façon pour le ciblage dans votre configuration.

Les plateformes regroupées par défaut sont les suivantes :

Version de PowerShell Système d’exploitation 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 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

Vous trouverez d’autres profils dans le référentiel GitHub.

Vous pouvez également générer votre propre profil de plateforme à l’aide du module PSCompatibilityCollector.

Les paramètres du profil de compatibilité prennent une liste de plateformes à cibler sous TargetProfiles. Une plateforme peut être spécifiée comme suit :

  • Un nom de plateforme (comme ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), qui sera .json ajouté à la fin et recherché dans le répertoire de profil par défaut.
  • Un nom de fichier (comme my_custom_platform.json), qui sera recherché dans le répertoire de profil par défaut.
  • Chemin d’accès absolu à un fichier (comme D:\PowerShellProfiles\TargetMachine.json).

Le répertoire de profil par défaut se trouve sous le module PSScriptAnalzyer à $PSScriptRoot/compatibility_profiles (où $PSScriptRoot fait ici référence au répertoire contenant PSScriptAnalyzer.psd1).

L’analyse de compatibilité compare une commande utilisée à la fois à un profil cible et à un profil « union » (contenant toutes les commandes disponibles dans n’importe quel profil dans la dir de profil). Si aucune commande n’est présente dans le profil d’union, elle est supposée être créée et ignorée localement. Sinon, si une commande est présente dans le profil d’union, mais pas dans une cible, elle est considérée comme incompatible avec cette cible.

Paramètres de configuration

Clé de configuration Signification Valeurs acceptées Obligatoire Exemple
Enable Active la règle bool ($true/$false) Non (valeur par défaut : $false) $true
TargetProfiles Liste des profils PowerShell à cibler string[] : chemins d’accès absolus aux fichiers de profil ou noms de profils dans le répertoire de profils Non (valeur par défaut : @()) @('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 Emplacement à rechercher des profils par nom et à utiliser pour la génération de profil d’union string : chemin absolu vers le nouveau dir de profil Non (valeur par défaut du compatibility_profiles répertoire dans le module PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Commandes pour ignorer la compatibilité de dans les scripts string[]: noms des commandes à ignorer Non (valeur par défaut : @()) @('Get-ChildItem','Import-Module')

Un exemple de configuration peut ressembler à :

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

Suppression

La compatibilité des commandes diagnostics peut être supprimée avec un attribut sur le param bloc d’un scriptblock comme avec d’autres règles.

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

La règle peut également être supprimée uniquement pour des commandes particulières :

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

Et également supprimé uniquement pour les paramètres :

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