UseCompatibleTypes

Article
12/12/2024

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>: 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/PSCompatibilityCollector/profiles (où $PSScriptRoot ici fait 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 tout profil dans le dir de profil). Si un type n’est pas présent dans le profil union, il est supposé être créé localement et ignoré. Sinon, si un type est présent dans le profil union mais pas présent 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 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`
`IgnoreTypes`	Noms complets de types ou accélérateurs de type pour ignorer la compatibilité des scripts	string[] : noms de 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 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

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('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')]

Partager via

UseCompatibleTypes

Description

Paramètres de configuration

Répression

Commentaires

Ressources supplémentaires