utilisation de PSScriptAnalyzer pour vérifier la compatibilité de la version PowerShell

PSScriptAnalyzer version 1.18 a été publié récemment et est livré avec de nouvelles règles puissantes qui peuvent vérifier les incompatibilités des scripts PowerShell avec d’autres versions et environnements PowerShell.

dans ce billet de blog, le premier d’une série, nous verrons comment utiliser ces nouvelles règles pour vérifier un script pour les problèmes d’exécution sur PowerShell 3, 5.1 et 6.

attendez, qu’est-ce que PSScriptAnalyzer?,

Psscriptanzyer est un module fournissant une analyse statique (ou linting) et une analyse dynamique (basée sur l’état de votre environnement) pour PowerShell. Il est capable de trouver des problèmes et de corriger les mauvaises habitudes dans les scripts PowerShell lorsque vous les Créez, de la même manière que le compilateur C# vous donnera des avertissements et trouvera des erreurs dans le code C# avant son exécution.,

Si vous utilisez L’extension VSCode PowerShell, vous avez peut-être vu les « squigglies verts” et les rapports de problèmes que psscriptanalyzer génère pour les scripts que vous êtes l’auteur:

Vous pouvez installer PSScriptAnalyzer pour l’utiliser sur vos propres scripts avec:

Install-Module PSScriptAnalyzer -Scope CurrentUser

psscriptanalyzer fonctionne en exécutant une série de règles sur vos scripts, chacune évaluant indépendamment un problème., Par exemple, AvoidUsingCmdletAliases vérifie que les alias ne sont pas utilisés dans les scripts, et MisleadingBackticks vérifie que les backticks aux extrémités des lignes ne sont pas suivis d’espaces.

pour plus d’informations, consultez la série psscriptanalyzer deep dive blog.

introduction des règles de vérification de compatibilité

la nouvelle fonctionnalité de vérification de compatibilité est fournie par trois nouvelles règles:

• PSUseCompatibleSyntax, qui vérifie si une syntaxe utilisée dans un script fonctionnera dans d’autres versions de PowerShell.,
• PSUseCompatibleCommands, qui vérifie si les commandes utilisées dans un script sont disponibles dans d’autres environnements PowerShell.
• PSUseCompatibleTypes, qui vérifie si les types.net et les méthodes / propriétés statiques sont disponibles dans d’autres environnements PowerShell.

La règle de vérification de la syntaxe nécessite simplement une liste des versions PowerShell que vous souhaitez cibler, et vous dira si une syntaxe utilisée dans votre script ne fonctionnera dans aucune de ces versions.,

Les règles de vérification des commandes et des types sont plus sophistiquées et reposent sur des profils (catalogues de commandes et de types disponibles) provenant de plates-formes PowerShell couramment utilisées. Ils nécessitent une configuration pour utiliser ces profils, que nous allons examiner ci-dessous.

pour cet article, nous examinerons la configuration et l’utilisation de PSUseCompatibleSyntax et PSUseCompatibleCommands pour vérifier qu’un script fonctionne avec différentes versions de PowerShell. Nous examinerons PSUseCompatibleTypes dans un post ultérieur, bien qu’il soit configuré de manière très similaire à PSUseCompatibleCommands.,

exemple de travail: un petit script PowerShell

Imaginez que nous ayons un petit script d’archivage (et artificiel) enregistré dans.\archiveScript.ps1:

ce script a été écrit dans PowerShell 6.2, et nous avons testé qu’il fonctionne là-bas. Mais nous voulons aussi l’exécuter sur d’autres machines, dont certaines exécuter PowerShell 5.1 et certaines exécuter PowerShell 3.0.

Idéalement, nous allons le tester sur les autres plates-formes, mais ce serait bien si nous pouvions essayer de repasser autant de bugs que possible à l’avance.,

vérification de la syntaxe avec PSUseCompatibleSyntax

La première et la plus simple règle à appliquer est PSUseCompatibleSyntax. Nous allons créer des paramètres pour PSScriptAnalyzer pour activer la règle, puis exécuter l’analyse sur notre script pour récupérer tous les diagnostics sur la compatibilité.

exécuter PSScriptAnalyzer est simple., Il s’agit d’un module PowerShell, donc une fois installé sur le chemin de votre module, vous l’invoquez simplement sur votre fichier avec Invoke-ScriptAnalyzer, comme ceci:

Invoke-ScriptAnalyzer -Path ".\archiveScript.ps1`

une invocation très simple comme celle-ci exécutera PSScriptAnalyzer en utilisant ses règles et configurations par défaut sur le script

cependant, comme elles nécessitent une configuration plus ciblée, les règles de compatibilité ne sont pas activées par défaut. Au lieu de cela, nous devons fournir certains paramètres pour exécuter la règle de vérification de la syntaxe., En particulier, PSUseCompatibleSyntax nécessite une liste des versions PowerShell que vous ciblez avec votre script.

exécuter ceci nous présentera la sortie suivante:

cela nous dit que la syntaxe]::new() que nous avons utilisée ne fonctionnera pas dans PowerShell 3. Mieux que cela, dans ce cas, la règle a effectivement proposé un correctif:

$diagnostics = Invoke-ScriptAnalyzer -Path .\archiveScript.ps1 -Settings $settings$diagnostics.SuggestedCorrections

La suggestion de correction est d’utiliser New-Object à la place., La façon dont cela est suggéré peut sembler légèrement inutile ici avec toutes les informations de position, mais nous verrons plus tard pourquoi cela est utile.

cet exemple de dictionnaire est un peu artificiel bien sûr (car une table de hachage viendrait plus naturellement), mais avoir une clé jetée dans les travaux dans PowerShell 3 ou 4 à cause d’un::new() n’est pas rare. La règle PSUseCompatibleSyntax vous avertira également des classes, des workflows et des instructions using en fonction des versions de PowerShell pour lesquelles vous créez.,

nous n’allons pas faire le changement suggéré pour l’instant, car il y a plus à vous montrer en premier.

vérification de l’utilisation des commandes avec PSUseCompatibleCommands

nous voulons maintenant vérifier les commandes. Parce que la compatibilité des commandes est un peu plus compliquée que la syntaxe (puisque la disponibilité des commandes dépend de plus que de la version de PowerShell en cours d’exécution), nous devons plutôt cibler les profils.

Les profils sont des catalogues d’informations provenant de machines en stock exécutant des environnements PowerShell courants., Ceux livrés dans PSScriptAnalyzer ne peuvent pas toujours correspondre parfaitement à votre environnement de travail, mais ils sont assez proches (il existe également un moyen de générer votre propre profil, détaillé dans un article de blog ultérieur). Dans notre cas, nous essayons de cibler PowerShell 3.0, PowerShell 5.1 et PowerShell 6.2 sur Windows. Nous avons les deux premiers profils, mais dans le dernier cas, nous devrons cibler 6.1 à la place. Ces cibles sont très proches, donc les avertissements seront toujours pertinents pour utiliser PowerShell 6.2. Plus tard, lorsqu’un profil 6.2 sera disponible, nous pourrons passer à cela.,

nous devons rechercher dans la documentation PSUseCompatibleCommands une liste de profils disponibles par défaut. Pour nos cibles souhaitées, nous choisissons:

les noms longs à droite sont des identifiants de profil canoniques, que nous utilisons dans les paramètres:

Il peut y avoir un retard la première fois que vous exécutez cela car les règles doivent charger les catalogues dans un cache. Chaque catalogue d’une plateforme PowerShell contient des détails sur tous les modules et.,Assemblages NET disponibles pour PowerShell sur cette plate-forme, qui peut être jusqu’à 1700 commandes avec 15 000 paramètres et 100 assemblages avec 10 000 types. Mais une fois qu’il est chargé, une analyse de compatibilité supplémentaire sera rapide. Nous obtenons en sortie comme ceci:

RuleName Severity ScriptName Line Message-------- -------- ---------- ---- -------PSUseCompatibleCommands Warning archiveScr 2 The parameter "FullyQualifiedName" is not available for ipt.ps1 command "Import-Module" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 12 The command "Get-FileHash" is not available by default in ipt.ps1 PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 18 The parameter "LeafBase" is not available for command ipt.ps1 "Split-Path" by default in PowerShell version "5.1.17763.316" on platform "Microsoft Windows Server 2019 Datacenter"PSUseCompatibleCommands Warning archiveScr 18 The parameter "LeafBase" is not available for command ipt.ps1 "Split-Path" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 19 The command "Compress-Archive" is not available by ipt.ps1 default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 23 The parameter "NoNewline" is not available for command ipt.ps1 "Out-File" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"

C’est de nous dire que:

• Import-Module ne supporte pas la balise -FullyQualifiedName dans PowerShell 3.0;
• Get-FileHash n’existe pas dans PowerShell 3.0;
• Split-Path n’est pas -LeafBase dans PowerShell 5.1 ou PowerShell 3.,0;
• Compress-Archive n’est pas disponible dans PowerShell 3.0, et;
• Out-File ne supporte pas la balise -NoNewline dans PowerShell 3.0

Une chose que vous remarquerez est que le Get-FoldersToArchive la fonction n’est pas averti. En effet, les règles de compatibilité sont conçues pour ignorer les commandes fournies par l’utilisateur; une commande ne sera marquée comme incompatible que si elle est présente dans un profil et non dans l’une de vos cibles.,

encore une fois, nous pouvons changer le script pour corriger ces avertissements, mais avant de le faire, je veux vous montrer comment en faire une expérience plus continue; lorsque vous modifiez votre script, vous voulez savoir si les modifications que vous apportez rompent la compatibilité, et c’est facile à faire avec les étapes ci-dessous.

utilisation d’un fichier de paramètres pour l’invocation répétée

la première chose que nous voulons est de rendre L’invocation PSScriptAnalyzer plus automatisée et reproductible. Un bon pas en avant consiste à prendre la table de hachage des paramètres que nous avons créée et à la transformer en un fichier de données déclaratif, en séparant le « quoi” du « comment”.,

PSScriptAnalyzer acceptera un chemin vers un PSD1 dans le paramètre-Settings, donc tout ce que nous devons faire est de transformer notre table de hachage en un fichier PSD1, que nous allons faire./PSScriptAnalyzerSettings.psd1. Notez que nous pouvons fusionner les paramètres pour PSUseCompatibleSyntax et PSUseCompatibleCommands:

maintenant, nous pouvons exécuter le PSScriptAnalyzer à nouveau sur le script en utilisant le fichier de paramètres:

Invoke-ScriptAnalyzer -Path ./archiveScript.ps1 -Settings ./PSScriptAnalyzerSettings.psd1

cela donne la sortie:

RuleName Severity ScriptName Line Message-------- -------- ---------- ---- -------PSUseCompatibleCommands Warning archiveScr 1 The parameter "FullyQualifiedName" is not available for ipt.ps1 command "Import-Module" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 9 The command "Get-FileHash" is not available by default in ipt.ps1 PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 12 The parameter "LeafBase" is not available for command ipt.ps1 "Split-Path" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 12 The parameter "LeafBase" is not available for command ipt.ps1 "Split-Path" by default in PowerShell version "5.1.17763.316" on platform "Microsoft Windows Server 2019 Datacenter"PSUseCompatibleCommands Warning archiveScr 13 The command "Compress-Archive" is not available by ipt.ps1 default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleCommands Warning archiveScr 16 The parameter "NoNewline" is not available for command ipt.ps1 "Out-File" by default in PowerShell version "3.0" on platform "Microsoft Windows Server 2012 Datacenter"PSUseCompatibleSyntax Warning archiveScr 6 The constructor syntax ipt.ps1 "]::new()" is not available by default in PowerShell versions 3,4

maintenant, nous ne dépendons plus de variables, et avons une spefication séparée de L’analyse que vous voulez., En utilisant cela, vous pouvez le mettre dans des environnements d’intégration continue, par exemple pour vérifier que les modifications apportées aux scripts ne rompent pas la compatibilité.

Mais ce que nous voulons vraiment, c’est savoir que les scripts PowerShell restent compatibles lorsque vous les modifiez. C’est ce à quoi le fichier de paramètres est construit, et aussi là où il est le plus facile d’apporter les modifications dont vous avez besoin pour rendre votre script compatible. Pour cela, nous voulons intégrer avec L’extension VSCode PowerShell.,

intégration avec VSCode pour vérifier la compatibilité à la volée

comme expliqué au début de cet article, l’extension VSCode PowerShell prend en charge PSScriptAnalyzer. En fait, à partir de la version 1.12.0, L’extension PowerShell est livrée avec PSScriptAnalyzer 1.18, ce qui signifie que vous n’avez pas besoin de faire autre chose que de créer un fichier de paramètres pour effectuer une analyse de compatibilité.

Nous avons déjà notre fichier de paramètres prêt à partir de la dernière étape, donc tout ce que nous avons à faire est de pointer L’extension PowerShell vers le fichier dans les paramètres VSCode.,

Vous pouvez ouvrir les paramètres avec Ctrl+, (utilisez Cmd au lieu de Ctrl sur macOS). Dans la vue paramètres, nous voulons PowerShell > Script Analysis: Settings Path. Dans la balise settings.json, c’est "powershell.scriptAnalysis.settingsPath"., Entrer un chemin d’accès relatif trouverez ici un fichier de settings dans notre espace de travail, afin que nous venons de mettre ./PSScriptAnalyzerSettings.psd1:

Dans le settings.json afficher cela va ressembler:

"powershell.scriptAnalysis.settingsPath": "./PSScriptAnalyzerSettings.psd1"

Maintenant, d’ouvrir le script dans VSCode nous voir « vert squigglies” pour la compatibilité avertissements:

Dans le volet problèmes, vous obtiendrez un desrciption de tous les incompatibilités:

nous allons résoudre le problème de syntaxe en premier., Si vous vous en souvenez, PSScriptAnalyzer fournit une correction suggérée à ce problème. VSCode s’intègre aux corrections suggérées par PSScriptAnalyzer et peut les appliquer si vous cliquez sur L’ampoule ou avec Ctrl+espace lorsque la région est sous le curseur:

en appliquant cette modification, le script est maintenant:

Les autres incompatibilités n’ont pas de corrections; pour L’instant PSUseCompatibleCommands pas quoi remplacer Lorsqu’une commande N’est pas disponible., Nous avons donc juste besoin d’appliquer quelques connaissances PowerShell:

nous nous retrouvons avec quelque chose comme ça (l’implémentation spécifique est sans importance, mais nous avons quelque chose qui fonctionnera dans toutes les versions):

vous devriez remarquer que lorsque vous tapez, VSCode affiche une nouvelle analyse de ce que vous écrivez et les squigglies verts disparaissent. Lorsque nous avons terminé, nous obtenons un bon état de santé pour la compatibilité des scripts:

cela signifie que vous pourrez désormais utiliser ce script sur toutes les versions PowerShell que vous devez cibler., Mieux, vous avez maintenant une configuration dans votre espace de travail afin que vous écriviez plus de scripts, il y a une vérification continue de la compatibilité. Et si vos objectifs de compatibilité changent, il vous suffit de modifier votre fichier de configuration en un seul endroit pour pointer vers vos cibles souhaitées, à quel point vous obtiendrez une analyse pour vos plates-formes cibles mises à jour.

résumé

espérons que dans cet article de blog, vous avez une idée des nouvelles règles de compatibilité fournies avec PSScriptAnalyzer 1.18.,

Nous avons expliqué comment configurer et utiliser la règle de vérification de la compatibilité syntaxique, PSUseCompatibleSyntax, et la règle de vérification des commandes, PSUseCompatibleCommands, à la fois en utilisant une configuration hashtable et un fichier de paramètres PSD1.

Nous avons également envisagé d’utiliser les règles de compatibilité avec L’extension PowerShell pour VSCode, où elles proviennent par défaut de la version 1.12.0.

Si vous avez la dernière version de L’extension PowerShell pour VSCode (1.12.1), vous pourrez définir votre fichier de configuration et obtenir instantanément une vérification de compatibilité.,

dans le prochain article de blog, nous verrons comment utiliser ces règles et PSUseCompatibleTypes (qui vérifie si les types.net et les méthodes statiques sont disponibles sur les plates-formes cibles) peut être utilisé pour vous aider à écrire des scripts qui fonctionnent multiplateforme sur Windows et Linux en utilisant à la fois Windows PowerShell et PowerShell Core.

Rob Holt

Ingénieur Logiciel

PowerShell Équipe