Share via

UseCompatibleTypes

  • Article

Niveau de gravité : Avertissement

Description

Cette règle identifie les types qui ne sont pas disponibles (chargés par défaut) dans les plateformes PowerShell ciblées.

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>: architecture de machine sur laquelle le système d’exploitation s’exécute (il s’agit généralement x64de ).
  • <os-version>: version autodéclaré 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 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 du 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 powerShell 6.2.0 s’exécute 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 dépôt GitHub.

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

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

L’analyse de compatibilité compare un type utilisé à la fois à un profil cible et à un profil « union » (contenant tous les types disponibles dans n’importe quel profil dans la dir de profil). Si un type n’est pas présent dans le profil d’union, il est supposé être créé localement et ignoré. Sinon, si un type est présent dans le profil d’union, mais pas dans une cible, il est considéré 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 des fichiers de profil 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 string : chemin absolu du nouveau dir de profil Non (la valeur par défaut est compatibility_profiles le répertoire dans le module PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreTypes Noms complets des types ou accélérateurs de types pour ignorer la compatibilité de dans les scripts string[] : noms des types à ignorer Non (valeur par défaut : @()) @('System.Collections.ArrayList','string')

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 settings 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'

Suppression

Les diagnostics de compatibilité des commandes peuvent être supprimées avec un attribut sur le param bloc d’un scriptblock comme avec d’autres règles.

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

La règle peut également être supprimée uniquement pour des types particuliers :

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

Et également supprimé uniquement pour les membres de type :

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