UseCompatibleTypes

niveau de gravité : avertissement

Description

Cette règle détecte les types qui ne sont pas disponibles par défaut sur vos plateformes PowerShell ciblées.

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/PSCompatibilityCollector/profiles (où $PSScriptRoot ici fait référence au répertoire contenant PSScriptAnalyzer.psd1).

L’analyse de compatibilité compare chaque type utilisé à un profil cible et un profil union. Le profil Union contient tous les types disponibles dans n’importe quel profil du répertoire du profil.

Si un type n’est pas dans le profil syndical, la règle suppose qu’il est local à votre environnement et l’ignore. Si un type est dans le profil union mais absent d’un profil cible, la règle le signale comme incompatible avec cette cible.

Exemple

Les exemples suivants supposent TargetProfiles inclut win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework (Windows 10 Pro, PowerShell 5.1).

Non conforme

System.Management.Automation.SemanticVersion n'est pas disponible par défaut dans Windows PowerShell 5.1, donc la règle signale ce type d'utilisation pour ce profil cible.

$version = [System.Management.Automation.SemanticVersion]'1.2.3'

Compliant

System.Version est disponible en Windows PowerShell 5.1 et PowerShell 7, donc il passe les vérifications de compatibilité entre ces cibles.

$version = [System.Version]'1.2.3.0'

Règle de configuration

Un exemple de configuration peut ressembler à ceci :

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

Vous pouvez également fournir un objet de paramètres comme suit :

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'

Répression

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

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

Vous pouvez aussi supprimer la règle pour certains types :

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

Vous pouvez aussi le supprimer pour des membres spécifiques de type :

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

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.

IgnoreTypes

Ce paramètre spécifie les noms complets des types ou des accélérateurs de types à exclure des vérifications de compatibilité. Il accepte une série de chaînes de noms de type. La valeur par défaut est @().