Psscriptanalyzer gebruiken om PowerShell versie compatibiliteit te controleren

PSScriptAnalyzer versie 1.18 is onlangs uitgebracht, en wordt geleverd met krachtige nieuwe regels die PowerShell scripts kunnen controleren op onverenigbaarheden met andere PowerShell versies en omgevingen.

in deze blogpost, de eerste in een serie, zullen we zien hoe we deze nieuwe regels kunnen gebruiken om een script te controleren op problemen die draaien op PowerShell 3, 5.1 en 6.

wacht, Wat is PSScriptAnalyzer?,

PSScriptAnalzyer is een module die statische analyse (of linting) en een aantal dynamische analyse (gebaseerd op de toestand van uw omgeving) voor PowerShell. Het is in staat om problemen te vinden en slechte gewoonten op te lossen in PowerShell scripts als je ze maakt, vergelijkbaar met de manier waarop de C# compiler je waarschuwingen geeft en fouten vindt in C# code voordat het wordt uitgevoerd.,

Als u de VSCode PowerShell extensie, u zou kunnen hebben gezien de “groene squigglies” en probleem rapporten die PSScriptAnalyzer genereert voor scripts die je auteur:

U kunt installeren PSScriptAnalyzer gebruiken op uw eigen scripts:

Install-Module PSScriptAnalyzer -Scope CurrentUser

PSScriptAnalyzer werkt door het uitvoeren van een reeks van regels op uw scripts, die elk onafhankelijk van elkaar beoordeelt enkele probleem., Bijvoorbeeld AvoidUsingCmdletAliases controleert of aliassen niet worden gebruikt in scripts, en MisleadingBackticks controleert of backticks aan het einde van regels niet worden gevolgd door witruimte.

voor meer informatie, zie de psscriptanalyzer deep dive blog series.

introductie van de compatibiliteitscontrole regels

de nieuwe compatibiliteitscontrole functionaliteit wordt geleverd door drie nieuwe regels:

• PSUseCompatibleSyntax, die controleert of een syntaxis gebruikt in een script zal werken in andere PowerShell versies.,
• PSUseCompatibleCommands, die controleert of commando ‘ s die in een script worden gebruikt beschikbaar zijn in andere PowerShell-omgevingen.
• PSUseCompatibleTypes, die controleert of. net-typen en statische methoden/eigenschappen beschikbaar zijn in andere PowerShell-omgevingen.

De syntaxiscontroleregel vereist gewoon een lijst met PowerShell-versies die u wilt benaderen, en zal u vertellen of een syntaxis die in uw script wordt gebruikt, in geen van deze versies zal werken.,

de regels voor het controleren van commando ’s en typen zijn geavanceerder en zijn gebaseerd op profielen (catalogi van commando’ s en typen beschikbaar) van veelgebruikte PowerShell-platforms. Ze hebben configuratie nodig om deze profielen te gebruiken, die we hieronder zullen bespreken.

voor dit bericht zullen we kijken naar het configureren en gebruiken van PSUseCompatibleSyntax en PSUseCompatibleCommands om te controleren of een script werkt met verschillende versies van PowerShell. We zullen kijken naar PSUseCompatibleTypes in een later bericht, hoewel het is geconfigureerd zeer vergelijkbaar met PSUseCompatibleCommands.,

werkvoorbeeld: een klein PowerShell-script

stel je voor dat we een klein (en gekunsteld) archiefscript hebben opgeslagen in .\archiveScript.ps1:

Dit script is geschreven in PowerShell 6.2, en we hebben getest dat het daar werkt. Maar we willen het ook draaien op andere machines, waarvan sommige draaien PowerShell 5.1 en sommige draaien PowerShell 3.0.

idealiter zullen we het testen op die andere platforms, maar het zou leuk zijn als we zouden kunnen proberen om zoveel mogelijk bugs van te voren uit te strijken.,

syntaxis controleren met PSUseCompatibleSyntax

De eerste en gemakkelijkste regel om toe te passen is PSUseCompatibleSyntax. We gaan een aantal instellingen voor PSScriptAnalyzer maken om de regel in te schakelen, en voer vervolgens analyse uit op ons script om alle diagnostiek over compatibiliteit terug te krijgen.

het uitvoeren van PSScriptAnalyzer is eenvoudig., Het wordt geleverd als een PowerShell-module, dus als het eenmaal op uw modulepad is geïnstalleerd, roept u het gewoon aan in uw bestand met Invoke-ScriptAnalyzer, als volgt:

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

een zeer eenvoudige aanroep als deze zal PSScriptAnalyzer uitvoeren met behulp van de standaardregels en configuraties op het script waarnaar u het verwijst.

echter, omdat ze meer gerichte configuratie vereisen, zijn de compatibiliteitsregels standaard niet ingeschakeld. In plaats daarvan moeten we enkele instellingen opgeven om de syntaxiscontroleregel uit te voeren., In het bijzonder, PSUseCompatibleSyntax vereist een lijst van de PowerShell versies die je targeet met je script.

Dit zal ons de volgende uitvoer geven:

Dit vertelt ons dat de ]::new() syntaxis die we gebruikten niet zal werken in PowerShell 3. Beter dan dat, in dit geval heeft de regel een oplossing voorgesteld:

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

de voorgestelde correctie is om New-Object in plaats daarvan te gebruiken., De manier waarop dit wordt voorgesteld lijkt misschien een beetje onbehulpzaam hier met alle positie informatie, maar we zullen later zien waarom dit nuttig is.

dit woordenboekvoorbeeld is natuurlijk een beetje kunstmatig (omdat een hashtabel natuurlijker zou zijn), maar het is niet ongewoon dat er een sleutel in PowerShell 3 of 4 wordt gegooid vanwege een ::new(). De psusecompatiblesyntax regel zal je ook waarschuwen voor klassen, workflows en using statements afhankelijk van de versies van PowerShell waarvoor je aan het schrijven bent.,

we gaan de voorgestelde wijziging nog niet maken, omdat er eerst meer te laten zien is.

controle commando gebruik met PSUseCompatibleCommands

we willen nu de commando ‘ s controleren. Omdat command compatibiliteit een beetje ingewikkelder is dan syntaxis (omdat de beschikbaarheid van commando ‘ s afhangt van meer dan welke versie van PowerShell wordt uitgevoerd), moeten we in plaats daarvan profielen richten.

profielen zijn catalogi van informatie die afkomstig zijn van voorraadmachines die gemeenschappelijke PowerShell-omgevingen draaien., Degene die worden verzonden in PSScriptAnalyzer kan niet altijd perfect overeenkomen met uw werkomgeving, maar ze komen vrij dicht (Er is ook een manier om uw eigen profiel te genereren, gedetailleerd in een latere blog post). In ons geval proberen we PowerShell 3.0, PowerShell 5.1 en PowerShell 6.2 op Windows te richten. We hebben de eerste twee profielen, maar in het laatste geval moeten we richten op 6.1. Deze doelen zijn zeer dichtbij, dus waarschuwingen zullen nog steeds relevant zijn voor het gebruik van PowerShell 6.2. Als er later een 6.2 profiel beschikbaar is, kunnen we daarop overschakelen.,

We moeten onder de psusecompatiblecommands documentatie kijken voor een lijst met standaard beschikbare profielen. Voor onze gewenste doelen kiezen we:

De Lange namen rechts zijn canonieke profielidentifiers, die we gebruiken in de Instellingen:

Er kan een vertraging optreden de eerste keer dat u dit uitvoert omdat de regels de catalogi in een cache moeten laden. Elke catalogus van een PowerShell platform bevat details van alle modules en .,NET assemblies beschikbaar voor PowerShell op dat platform, die kunnen worden maar liefst 1700 commando ‘ s met 15.000 parameters en 100 assemblies met 10.000 types. Maar zodra het is geladen, verdere compatibiliteitsanalyse zal snel zijn. We krijgen uitvoer als volgt:

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"

Dit vertelt ons dat:

• Import-Module ondersteunt -FullyQualifiedName in PowerShell 3.0;
• Get-FileHash bestaat niet in PowerShell 3.0;
• Split-Path heeft geen -LeafBase in PowerShell 5.1 of PowerShell 3.,0;
• Compress-Archive is niet beschikbaar in PowerShell 3.0, en;
• Out-File ondersteunt -NoNewline in PowerShell 3.0

een ding dat u zult merken is dat de Get-FoldersToArchive functie wordt niet gewaarschuwd. Dit komt omdat de compatibiliteitsregels zijn ontworpen om door de gebruiker verstrekte commando ‘ s te negeren; een commando zal alleen als incompatibel worden gemarkeerd als het aanwezig is in een profiel en niet in een van uw doelen.,

nogmaals, we kunnen het script veranderen om deze waarschuwingen op te lossen, maar voordat we dat doen, wil ik je laten zien hoe je dit een meer continue ervaring kunt maken; als je je script verandert, wil je weten of de wijzigingen die je maakt break compatibiliteit, en dat is eenvoudig te doen met de onderstaande stappen.

met behulp van een instellingenbestand voor herhaalde aanroep

het eerste wat we willen is om de psscriptanalyzer aanroep meer geautomatiseerd en reproduceerbaar te maken. Een mooie stap in de richting van dit is het nemen van de Instellingen hashtable die we hebben gemaakt en het omzetten in een declaratieve gegevensbestand, het scheiden van de “wat” van de “hoe”.,

PSScriptAnalyzer accepteert een pad naar een PSD1 in de -Settings parameter, dus het enige wat we hoeven te doen is onze hashtable om te zetten in een PSD1 bestand, dat we ./PSScriptAnalyzerSettings.psd1zullen maken. Merk op dat we de instellingen voor zowel PSUseCompatibleSyntax als PSUseCompatibleCommands kunnen samenvoegen:

nu kunnen we de PSScriptAnalyzer opnieuw uitvoeren op het script met behulp van het instellingenbestand:

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

Dit geeft de uitvoer:

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

nu we zijn niet meer afhankelijk van variabelen, en hebben een aparte Speficatie van de analyse die u wilt., Met behulp van deze, kunt u dit in continue integratie omgevingen bijvoorbeeld om te controleren of veranderingen in scripts niet breken Compatibiliteit.

maar wat we echt willen is om te weten dat PowerShell scripts compatibel blijven als je ze bewerkt. Dat is waar het instellingenbestand naar toe bouwt, en ook waar het het makkelijkst is om de wijzigingen aan te brengen die u nodig hebt om uw script compatibel te maken. Daarvoor willen we integreren met de VSCode PowerShell extensie.,

integratie met VSCode voor on-the-fly compatibiliteitscontrole

zoals uitgelegd aan het begin van dit bericht, heeft de VSCode PowerShell-extensie ingebouwde ondersteuning voor PSScriptAnalyzer. In feite, vanaf versie 1.12.0, de PowerShell-extensie wordt geleverd met PSScriptAnalyzer 1.18, wat betekent dat je niet nodig hebt om iets anders te doen dan het maken van een instellingenbestand om compatibiliteitsanalyse te doen.

we hebben ons instellingenbestand al klaar om te gaan vanaf de laatste stap, dus het enige wat we hoeven te doen is de PowerShell-extensie naar het bestand in de VSCode-instellingen te richten.,

u kunt de Instellingen openen met Ctrl+, (gebruik Cmd in plaats van Ctrl op macOS). In de Instellingen Weergave willen we PowerShell > Script Analysis: Settings Path. In de settings.json weergave is dit "powershell.scriptAnalysis.settingsPath"., Het invoeren van een relatief pad hier vindt u een bestand met instellingen in onze werkruimte, dus we zetten ./PSScriptAnalyzerSettings.psd1:

In de settings.json bekijk dit zal er als volgt uitzien:

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

Nu, het openen van het script in VSCode zien we de “groene squigglies” voor compatibiliteit waarschuwingen:

In de problemen venster, krijgt u een volledige desrciption van alle incompatibele producten:

Laten we lossen de syntaxis probleem voor het eerst., Als u zich herinnert, levert PSScriptAnalyzer een voorgestelde correctie op dit probleem. VSCode integreert met psscriptanalyzer ‘ s voorgestelde correcties en kan ze toepassen als u op de gloeilamp klikt of met Ctrl+spatie wanneer de regio onder de cursor is:

door deze wijziging toe te passen, is het script nu:

de andere onverenigbaarheden hebben geen correcties; voor nu PSUseCompatibleCommands weet welke commando ‘ s beschikbaar zijn op elk platform, maar niet wat te vervang door wanneer een commando niet beschikbaar is., Dus we hoeven alleen maar wat PowerShell kennis toe te passen:

we eindigen met iets als dit (de specifieke implementatie is onbelangrijk, maar we hebben iets dat in alle versies zal werken):

je zou moeten merken dat als je typt, VSCode nieuwe analyse toont van wat je aan het schrijven bent en de groene kronkels wegvallen. Als we klaar zijn krijgen we een clean bill of health voor scriptcompatibiliteit:

Dit betekent dat je dit script nu kunt gebruiken voor alle PowerShell-versies die je moet benaderen., Beter, je hebt nu een configuratie in uw werkruimte, zodat als je meer scripts te schrijven, is er voortdurend controleren op compatibiliteit. En als uw compatibiliteitsdoelen veranderen, hoeft u alleen maar uw configuratiebestand op één plaats te wijzigen om naar uw gewenste doelen te wijzen, waarna u een analyse krijgt voor uw bijgewerkte doelplatforms.

samenvatting

hopelijk heb je in deze blogpost een idee van de nieuwe compatibiliteitsregels die bij PSScriptAnalyzer 1.18 komen.,

we hebben besproken hoe je de syntaxis compatibiliteitscontrole regel, PSUseCompatibleSyntax, en de commando controle regel, PSUseCompatibleCommands, beide met behulp van een hashtable configuratie en een Instellingen PSD1 bestand in te stellen en te gebruiken.

we hebben ook gekeken naar het gebruik van de compatibiliteitsregels in de PowerShell extensie voor VSCode, waar ze standaard uit versie 1.12.0 komen.

Als u de nieuwste versie van de PowerShell-extensie voor VSCode (1.12.1) hebt, kunt u uw configuratiebestand instellen en direct compatibiliteitscontrole krijgen.,

in de volgende blogpost zullen we kijken hoe deze regels te gebruiken en PSUseCompatibleTypes (die controleert of.net types en statische methoden beschikbaar zijn op doelplatforms) kunnen worden gebruikt om je te helpen scripts te schrijven die platformoverschrijdend werken tussen Windows en Linux met zowel Windows PowerShell als PowerShell Core.

Rob Holt

Software Engineer

PowerShell Team