UseCompatibleCommands

niveau de gravité : avertissement

Description

Cette règle détecte les commandes qui ne sont pas disponibles sur votre plateforme PowerShell ciblée.

Un nom dans la plateforme PowerShell est identifié sous le 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, le numéro SKU est inclus. Sous Linux, la valeur correspond au nom de la distribution.
• <os-arch>: L’architecture de la machine sur laquelle le système d’exploitation fonctionne (généralement x64).
• <os-version>: La version auto-déclarée du système d’exploitation (la version de distribution sur Linux).
• <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.

PSScriptAnalyzer inclut certains profils de plateforme sous forme de fichiers JSON. Vous pouvez cibler ces profils intégrés directement dans votre configuration.

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

Vous trouverez d’autres profils dans le dépôt GitHub .

Vous pouvez également générer votre propre profil plateforme avec le module PSCompatibilityCollector.

Les paramètres de compatibilité prennent une liste des plateformes sous TargetProfiles. Vous pouvez spécifier chaque plateforme cible comme suit :

• Un nom de plateforme (par exemple, ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). PSScriptAnalyzer l’ajoute .json et le recherche dans le répertoire de profil par défaut.
• Un nom de fichier (par exemple, my_custom_platform.json), que PSScriptAnalyzer recherche 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 PSScriptAnalyzer à $PSScriptRoot/compatibility_profiles (où $PSScriptRoot ici fait référence au répertoire contenant PSScriptAnalyzer.psd1).

L’analyse de compatibilité compare chaque commande utilisée à un profil cible et un profil union. Le profil union contient toutes les commandes disponibles dans n’importe quel profil du répertoire du profil.

Si une commande n’est pas dans le profil syndical, la règle suppose qu’elle est locale à votre environnement et l’ignore. Si une commande est dans le profil union mais manquante dans un profil cible, la règle la signale comme incompatible avec cette cible.

Exemple

Les exemples suivants supposent TargetProfiles que cela inclut ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core (Ubuntu 18.04, PowerShell 6.2).

Non conforme

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

Compliant

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

Règle de configuration

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

Comme pour d’autres règles, vous pouvez supprimer les diagnostics de compatibilité des commandes en ajoutant un attribut de suppression au param bloc d’un bloc de script.

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

Vous pouvez aussi supprimer la règle pour des commandes spécifiques :

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

Vous pouvez aussi la supprimer pour des paramètres spécifiques :

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

Paramètres

Activer

Ce paramètre détermine si ScriptAnalyzer vérifie le code par rapport à cette règle. Il accepte une valeur booléenne. Pour permettre cette règle, fixez ce paramètre à $true. La valeur par défaut est $false.

ProfilsCibles

Ce paramètre spécifie la liste des profils de plateforme à vérifier pour la compatibilité. Un tableau de chaînes est accepté. Chaque valeur peut être un nom de plateforme, un nom de fichier ou un chemin absolu vers un fichier profil. La valeur par défaut est @().

ProfileDirPath

Ce paramètre contrôle le répertoire que ScriptAnalyzer recherche pour les profils par nom et utilise pour générer le profil d’union. Elle accepte une chaîne contenant un chemin absolu. L’emplacement par défaut est le compatibility_profiles répertoire dans le module PSScriptAnalyzer.

IgnorerCommandes

Ce paramètre spécifie des commandes à exclure des vérifications de compatibilité. Il accepte un tableau de chaînes de noms de commande. La valeur par défaut est @().