UseCompatibleCommands

Article
12/12/2024

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

Par exemple:

win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework est PowerShell 5.1 s’exécutant sur Windows 10 Entreprise (build 18312) pour x64.
win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core est PowerShell 6.1.2 s’exécutant 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 regroupées 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 :

PowerShell Version	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 Professionnel	`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`

Vous trouverez d’autres profils dans le dépôt 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 :

Nom de la plateforme (comme ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), qui aura .json ajouté à la fin et est recherché dans le répertoire de profil par défaut.
Nom de fichier (comme my_custom_platform.json), qui sera recherché dans le répertoire de profil par défaut.
Chemin absolu d’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 ici fait référence au répertoire contenant PSScriptAnalyzer.psd1).

L’analyse de compatibilité compare une commande utilisée à la fois pour un profil cible et un profil « union » (contenant toutes les commandes disponibles dans tout profil dans le dir de profil). Si une commande n’est pas présente dans le profil union, elle est supposée être créée localement et ignorée. Dans le cas contraire, si une commande est présente dans le profil union mais qu’elle n’est pas présente 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 absolus pour profiler des fichiers ou des noms de profils dans le répertoire de profil	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 union	chaîne : chemin absolu du nouveau dir de profil	Non (valeur par défaut du répertoire `compatibility_profiles` dans le module PSScriptAnalyzer	`C:\Users\me\Documents\pssaCompatProfiles`
`IgnoreCommands`	Commandes pour ignorer la compatibilité des scripts	string[] : noms des commandes à ignorer	Non (valeur par défaut : `@()`)	`@('Get-ChildItem','Import-Module')`

Un exemple de configuration peut ressembler à ceci :

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

Répression

Les diagnostics de compatibilité des commandes peuvent être supprimés avec un attribut sur le bloc param 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')]

Partager via

UseCompatibleCommands

Description

Paramètres de configuration

Répression

Commentaires

Ressources supplémentaires