Brug PSScriptAnalyzer at kontrollere PowerShell version kompatibilitet

PSScriptAnalyzer version 1.18 blev udgivet for nylig, og skibe med kraftfulde nye regler, der kan kontrollere PowerShell-scripts til uoverensstemmelser med andre PowerShell versioner og miljøer.

i dette blogindlæg, det første i en serie, ser vi, hvordan du bruger disse nye regler til at kontrollere et script for problemer, der kører på Po .ershell 3, 5.1 og 6.

Vent, hvad er Psscriptanaly ?er?,

PSScriptAnalzyer er et modul, der giver statisk analyse (eller linting) og nogle dynamisk analyse (baseret på tilstanden af dit miljø) til PowerShell. Det er i stand til at finde problemer og løse dårlige vaner i Po .ershell-scripts, når du opretter dem, svarende til den måde, C# compiler giver dig advarsler og finder fejl i C# kode, før den udføres.,

Hvis du bruger VSCode PowerShell udvidelse, du kunne have set det “grønne squigglies” og problemet er rapporter om, at PSScriptAnalyzer genererer for scripts, du forfatter:

Du kan installere PSScriptAnalyzer til at bruge på dine egne scripts med:

Install-Module PSScriptAnalyzer -Scope CurrentUser

PSScriptAnalyzer virker ved at køre en række regler på dine scripts, der hver som selvstændigt vurderer nogle spørgsmål., For eksempel kontrollerer AvoidUsingCmdletAliases, at aliaser ikke bruges i scripts, og MisleadingBackticks kontrollerer, at backticks i enderne af linjer ikke efterfølges af mellemrum.for mere information, se psscriptanaly .er deep dive blog serien.

Indføre kompatibilitet se regler

De nye kompatibilitet kontrol funktionalitet er fastsat af tre nye regler:

• PSUseCompatibleSyntax, som kontrollerer, om en syntaks der bruges i et script, vil arbejde i andre PowerShell versioner.,
• PSUseCompatibleCommands, som kontrollerer, om kommandoer, der bruges i et script er tilgængelige i andre PowerShell miljøer.
• PSUseCompatibleTypes, som undersøger om .NET typer og statiske metoder/egenskaber er tilgængelige i andre PowerShell miljøer.

syntakscheck-reglen kræver blot en liste over Po .ershell-versioner, du vil målrette mod, og vil fortælle dig, om en syntaks, der bruges i dit script, ikke fungerer i nogen af disse versioner.,

reglerne for kommando-og typekontrol er mere sofistikerede og er afhængige af profiler (kataloger over kommandoer og typer tilgængelige) fra almindeligt anvendte Po .ershell-platforme. De kræver konfiguration for at bruge disse profiler, som vi vil gå over nedenfor.

For dette indlæg ser vi på konfiguration og brug af Psusecompatiblesynta.og PSUseCompatibleCommands for at kontrollere, at et script fungerer med forskellige versioner af Po .ershell. Vi vil se på PSUseCompatibleTypes i et senere indlæg, selvom det er konfigureret meget på samme måde som PSUseCompatibleCommands.,

Arbejder eksempel: et lille PowerShell script

Forestil dig at vi har en lille (og kunstige) arkivers scriptet gemmes .\archiveScript.ps1:

Dette script er skrevet i PowerShell 6.2, og vi har testet at den virker der. Men vi vil også køre det på andre maskiner, hvoraf nogle kører Po .ershell 5.1 og nogle kører Po .ershell 3.0.

ideelt set vil vi teste det på de andre platforme, men det ville være rart, hvis vi kunne forsøge at udjævne så mange fejl som muligt på forhånd.,

kontrol af syntaks med Psusecompatiblesynta.

den første og nemmeste regel at anvende er Psusecompatiblesynta.. Vi vil oprette nogle indstillinger for Psscriptanaly .er for at aktivere reglen, og kør derefter analyse på vores script for at få nogen diagnostik om kompatibilitet tilbage.at køre Psscriptanaly .er er ligetil., Det kommer som et PowerShell-modul, så snart det er installeret på dit modul sti, du lige påberåbe sig det på din fil med Invoke-ScriptAnalyzer, som dette:

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

En meget simpel påberåbelse som denne vil køre PSScriptAnalyzer ved hjælp af dens standard regler og konfigurationer på det script, du peger den til.

da de kræver mere målrettet konfiguration, er kompatibilitetsreglerne dog ikke aktiveret som standard. I stedet skal vi levere nogle indstillinger for at køre synta .check-reglen., Især kræver Psusecompatiblesynta.en liste over de Po .ershell-versioner, du målretter mod med dit script.dette vil give os følgende output:

dette fortæller os, at ]::new() syntaks, vi brugte, ikke fungerer i Po .ershell 3. Bedre end det, i dette tilfælde reglen er faktisk foreslået en rettelse:

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

Den foreslåede korrektion er at bruge New-Object i stedet for., Den måde, dette foreslås på, kan virke lidt uhensigtsmæssigt her med alle positionsoplysninger, men vi vil se senere, hvorfor dette er nyttigt.

Denne ordbog eksempel er en smule kunstig selvfølgelig (da en hashtabelsamling ville komme mere naturligt), men med en skruenøgle kastet ind i de værker, i PowerShell 3 eller 4 på grund af en ::new() er ikke ualmindeligt. Den PSUseCompatibleSyntax regel vil også advare dig om klasser, arbejdsgange og using udsagn, afhængigt af de versioner af PowerShell du authoring for.,

Vi vil ikke foretage den foreslåede ændring endnu, da der er mere at vise dig først.

kontrol af kommandoforbrug med PSUseCompatibleCommands

Vi vil nu kontrollere kommandoerne. Fordi kommandokompatibilitet er lidt mere kompliceret end syntaks (da tilgængeligheden af kommandoer afhænger af mere end hvilken version af Po .ershell der køres), skal vi målrette profiler i stedet.

profiler er kataloger over oplysninger taget fra lagermaskiner, der kører almindelige Po .ershell-miljøer., Dem, der leveres i Psscriptanaly .er, kan ikke altid matche dit arbejdsmiljø perfekt, men de kommer temmelig tæt på (der er også en måde at generere din egen profil, detaljeret i et senere blogindlæg). I vores tilfælde, vi forsøger at målrette PowerShell 3.0, PowerShell 5.1 og PowerShell 6.2 på Windows. Vi har de to første profiler, men i det sidste tilfælde skal vi målrette 6.1 i stedet. Disse mål er meget tæt, så advarsler vil stadig være relevante for at bruge Po .ershell 6.2. Senere, når en 6.2-profil stilles til rådighed, kan vi skifte til den.,

Vi er nødt til at se under psusecompatiblecommands-dokumentationen for en liste over profiler, der er tilgængelige som standard. For vores ønskede mål vælger vi:

de lange navne til højre er kanoniske profilidentifikatorer, som vi bruger i indstillingerne:

der kan være en forsinkelse første gang du udfører dette, fordi reglerne skal indlæse katalogerne i en cache. Hvert katalog af en Po .ershell platform indeholder oplysninger om alle moduler og .,NET samlinger til rådighed for PowerShell på denne platform, der kan være så mange som 1700-kommandoer med 15.000 parametre og 100 forsamlinger med 10.000 typer. Men når den er indlæst, vil yderligere kompatibilitetsanalyse være hurtig. Vi får output som dette:

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"

Dette fortæller os at:

• Import-Module ikke understøtter -FullyQualifiedName i PowerShell 3.0;
• Get-FileHash ikke eksisterer i PowerShell 3.0;
• Split-Path ikke -LeafBase i PowerShell 5.1 eller PowerShell-3.,0;
• Compress-Archive er ikke tilgængelig i PowerShell 3.0, og;
• Out-File ikke understøtter -NoNewline i PowerShell 3.0

En ting du vil bemærke er, at Get-FoldersToArchive funktion er ikke at være blevet advaret om. Dette skyldes, at kompatibilitetsreglerne er designet til at ignorere brugerleverede kommandoer; en kommando vil kun blive markeret som inkompatibel, hvis den er til stede i en eller anden profil og ikke i et af dine mål.,

igen kan vi ændre scriptet for at rette disse advarsler, men før vi gør det, vil jeg vise dig, hvordan du gør dette til en mere kontinuerlig oplevelse; når du ændrer dit script, vil du vide, om de ændringer, du foretager, bryder kompatibilitet, og det er let at gøre med nedenstående trin.

brug af en indstillingsfil til gentagen påkaldelse

det første, vi ønsker, er at gøre psscriptanaly .er-påkaldelsen mere automatiseret og reproducerbar. Et godt skridt mod dette er at tage indstillingerne hashtable vi lavede og gøre det til en deklarativ datafil, der adskiller “Hvad” fra “hvordan”.,

PSScriptAnalyzer vil acceptere en sti til en PSD1 i -Settings parameter, så alt vi skal gøre er at tænde vores hashtabelsamling i en PSD1 fil, som vi vil gøre ./PSScriptAnalyzerSettings.psd1. Meddelelse vi kan flette indstillinger for begge PSUseCompatibleSyntax og PSUseCompatibleCommands:

Nu kan vi køre PSScriptAnalyzer igen på det script, der bruger indstillingerne fil:

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

Dette giver output:

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 er vi ikke afhængige af nogen variabler længere, og har en separat spefication af den analyse, du ønsker., Ved hjælp af dette kan du sætte dette i kontinuerlige integrationsmiljøer for eksempel for at kontrollere, at ændringer i scripts ikke bryder Kompatibilitet.men hvad vi virkelig ønsker, er at vide, at po .ershell-scripts forbliver kompatible, når du redigerer dem. Det er, hvad indstillingsfilen bygger til, og også hvor det er nemmest at foretage de ændringer, du har brug for for at gøre dit script kompatibelt. Til det ønsker vi at integrere med VSCode Po .ershell-udvidelsen.,

Integration med VSCode for on-the-fly kompatibilitet kontrol

Som det er forklaret i starten af dette indlæg, VSCode PowerShell udvidelse har indbygget support for PSScriptAnalyzer. I virkeligheden, som i version 1.12.0, PowerShell udvidelse skibe med PSScriptAnalyzer 1.18, hvilket betyder at du ikke behøver at gøre andet end at oprette en fil med indstillinger til at gøre kompatibilitet analyse.

Vi har allerede vores indstillingsfil klar til at gå fra det sidste trin, så alt hvad vi skal gøre er at pege Po .ershell-udvidelsen til filen i VSCode-indstillingerne.,

Du kan åbne indstillingerne med Ctrl+, (brug Cmd i stedet for Ctrl på macOS). I Indstillingsvisningen ønsker vi PowerShell > Script Analysis: Settings Path. I settings.json se dette er "powershell.scriptAnalysis.settingsPath"., Indtastning af en relativ sti her vil finde en fil med indstillinger i vores arbejdsplads, så vi bare sætte ./PSScriptAnalyzerSettings.psd1:

I settings.json vis dette vil se ud som:

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

Nu, at åbne script i VSCode vi se “grøn squigglies” for kompatibilitet advarsler:

I problemer i ruden, vil du få en fuld desrciption af alle uoverensstemmelser:

Lad os løse den syntaks, der er problemet først., Hvis du husker, leverer Psscriptanaly .er en foreslået korrektion af dette problem. VSCode integrerer med PSScriptAnalyzer ‘ s foreslåede rettelser og kan anvende dem, hvis du klikker på pære eller med Ctrl+Mellemrum, når regionen er under markøren:

Anvendelse af denne ændring, scriptet er nu:

De andre uoverensstemmelser ikke har rettelser; for nu PSUseCompatibleCommands ved, hvilke kommandoer der er tilgængelige på hver platform, men ikke, hvad de skal erstatte med, når en kommando er ikke tilgængelig., Så vi er bare nødt til at anvende nogle PowerShell viden:

Vi ende op med noget som dette (den konkrete gennemførelse er uvigtige, men vi har noget, der vil arbejde i alle versioner):

Du bør lægge mærke til, at efterhånden som du skriver, VSCode viser nye analyse af, hvad du skriver, og den grønne squigglies slippe væk. Når vi er færdig, får vi en ren sundhedsattest for script-kompatibilitet:

Dette betyder, at du nu være i stand til at bruge dette script på tværs af alle PowerShell-versioner, du er nødt til at målrette., Bedre, du har nu en konfiguration i dit arbejdsområde, så når du skriver flere scripts, der kontrolleres løbende for kompatibilitet. Og hvis dine kompatibilitetsmål ændres, alt hvad du skal gøre er at ændre din konfigurationsfil Onet sted for at pege på dine ønskede mål, på hvilket tidspunkt får du analyse for dine opdaterede målplatforme.

resum Hopefully

forhåbentlig i dette blogindlæg fik du en ID.om de nye kompatibilitetsregler, der følger med Psscriptanaly .er 1.18.,

Vi har dækket, hvordan du konfigurerer og bruger syntakskompatibilitetskontrolreglen, Psusecompatiblesynta.og kommandokontrolreglen, PSUseCompatibleCommands, både ved hjælp af en Hashtabel konfiguration og en PSD1-fil med indstillinger.

Vi har også kigget på hjælp kompatibilitet regler i med PowerShell udvidelse til VSCode, hvor de kommer som standard fra version 1.12.0.

Hvis du har den seneste udgivelse af Po .ershell-udvidelsen til VSCode (1.12.1), kan du indstille din konfigurationsfil og øjeblikkeligt få kompatibilitetskontrol.,

I næste blog-indlæg, vil vi se på, hvordan man kan bruge disse regler og PSUseCompatibleTypes (som kontrollerer om .NET typer og statiske metoder, der er tilgængelige på mål, platforme) kan bruges til at hjælpe dig med at skrive scripts, der arbejder på tværs af platforme på tværs af Windows-og Linux-bruger både Windows PowerShell og PowerShell Kerne.

Rob Holt

Soft Engineerare Engineer

Po Powerershell Team