ved Hjelp av PSScriptAnalyzer å sjekke PowerShell versjon kompatibilitet

PSScriptAnalyzer versjon 1.18 ble lansert nylig, og leveres med kraftige nye regler som kan sjekke PowerShell script for inkompatibilitet med andre PowerShell-versjoner og miljøer.

I denne bloggen, den første i en serie, vi får se hvordan å bruke disse nye regler for å kontrollere et skript for problemer som kjører på PowerShell-3, 5.1 og 6.

Vent, hva er PSScriptAnalyzer?,

PSScriptAnalzyer er en modul som gir statisk analyse (eller linting) og noen dynamisk analyse (basert på tilstanden din miljø) for PowerShell. Det er i stand til å finne problemer og fikse dårlige vaner i PowerShell-skript som du oppretter dem, på samme måte som C# kompilatoren vil gi deg advarsler og finne feil i C# – kode før det er utført.,

Hvis du bruker VSCode PowerShell extension, du har kanskje sett den «grønne squigglies» og problemet rapporter som PSScriptAnalyzer genererer skript og du forfatteren:

Du kan installere PSScriptAnalyzer å bruke på dine egne skript med:

Install-Module PSScriptAnalyzer -Scope CurrentUser

PSScriptAnalyzer fungerer ved å kjøre en rekke regler om dine skript, som hver uavhengig vurderer noen problem., For eksempel AvoidUsingCmdletAliases kontroller at aliaser ikke brukes i prosedyrer, og MisleadingBackticks kontroller at backticks i endene av linjene er ikke etterfulgt av mellomrom.

For mer informasjon, se PSScriptAnalyzer dypdykk blogg-serien.

Innføre kompatibilitet sjekk regler

Den nye kompatibilitet kontrollere funksjonaliteten er levert av tre nye reglene:

• PSUseCompatibleSyntax, som sjekker om en syntaks som er brukt i et skript vil fungere i andre PowerShell-versjoner.,
• PSUseCompatibleCommands, som sjekker om kommandoer som brukes i et manus, er tilgjengelige i andre PowerShell-miljøer.
• PSUseCompatibleTypes, som sjekker om .NETTO typer og statiske metoder/egenskaper er tilgjengelige i andre PowerShell-miljøer.

syntaks sjekk regel bare krever en liste over PowerShell versjoner du vil målrette mot, og vil fortelle deg hvis en syntaks som brukes i skriptet ikke fungerer i noen av disse versjonene.,

– kommandoen og skrive sjekker reglene er mer sofistikert og stole på profiler (kataloger av kommandoer og typer er tilgjengelig) fra brukte PowerShell plattformer. De krever konfigurering hvis du vil bruke disse, eller profiler, som vi vil gå over under.

For dette innlegget, vil vi se på hvordan du konfigurerer og bruker PSUseCompatibleSyntax og PSUseCompatibleCommands for å sjekke at et skript arbeider med ulike versjoner av PowerShell. Vi skal se på PSUseCompatibleTypes i et senere innlegg, selv om det er konfigurert svært likt PSUseCompatibleCommands.,

Arbeide eksempel: en liten PowerShell script

Tenk deg at vi har en liten (og kunstige) arkivering script lagret til .\archiveScript.ps1:

Dette manuset var skrevet i PowerShell 6.2, og vi har testet at det fungerer der. Men vi ønsker også å kjøre den på andre maskiner, noen som kjører PowerShell 5.1 og noen som kjører PowerShell 3.0.

Ideell vi vil teste det på de andre plattformene, men det ville være fint om vi kunne prøve å stryke ut så mange feil som mulig i forkant av tid.,

Sjekker syntaks med PSUseCompatibleSyntax

Den første og enkleste regelen skal gjelde er PSUseCompatibleSyntax. Vi kommer til å lage noen innstillinger for PSScriptAnalyzer for å aktivere regelen, og deretter kan du kjøre analyser på vår skript for å få tilbake noen diagnose om kompatibilitet.

Kjører PSScriptAnalyzer er grei., Det kommer som en PowerShell-modul, så når det er installert på din modul banen du bare bruke den på din fil med Invoke-ScriptAnalyzer, som dette:

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

En veldig enkel bruken som dette vil kjøre PSScriptAnalyzer bruke sin standard regler og konfigurasjoner på det skriptet du det til å peke på.

Imidlertid, fordi de krever mer målrettet konfigurasjon, kompatibilitet reglene er ikke aktivert som standard. I stedet, vi trenger for å levere noen innstillinger for å kjøre syntaks sjekk regelen., Spesielt PSUseCompatibleSyntax krever en liste av PowerShell-versjoner du er rettet med dine skript.

Kjører denne vil presentere oss med følgende resultat:

Dette forteller oss at ]::new() syntaks brukte vi vil ikke fungere i PowerShell-3. Bedre enn det, i dette tilfellet regelen har faktisk foreslått en løsning:

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

Det foreslått endring er å bruke New-Object i stedet., Måten dette er foreslått kan virke litt uheldig her med all informasjon om posisjon, men vi får se senere hvorfor dette er nyttig.

Denne ordboken eksempel er litt kunstig selvfølgelig (siden en hashtable ville komme mer naturlig nok), men å ha en fastnøkkel kastet inn i den fungerer i PowerShell 3 eller 4 på grunn av en ::new() er ikke uvanlig. Den PSUseCompatibleSyntax regelen vil også advare deg om klasser, arbeidsflyter og using uttalelser avhengig av versjoner av PowerShell du er authoring for.,

– Vi kommer ikke til å gjøre den foreslåtte endringen bare ennå, siden det er mer å vise deg først.

kommando for å Kontrollere bruk med PSUseCompatibleCommands

Vi nå ønsker å sjekke kommandoer. Fordi kommando kompatibilitet er litt mer komplisert enn syntaks (siden tilgjengeligheten av kommandoer avhengig av mer enn hvilken versjon av PowerShell er å kjøre), vi har til mål profiler i stedet.

Profiler blir kataloger av informasjon hentet fra lager maskiner som kjører felles PowerShell-miljøer., De fulgte i PSScriptAnalyzer kan ikke alltid passer dine arbeidsmiljø perfekt, men de kommer ganske nær (det er også en måte å generere din egen profil, beskrevet i et senere blogginnlegg). I vårt tilfelle, vi prøver å målrette PowerShell 3.0, PowerShell 5.1 og PowerShell 6.2 på Windows. Vi har de første to profiler, men i den siste saken vi trenger for å målrette 6.1 i stedet. Disse målene er svært nær, så advarsler vil fortsatt være relevant å bruke PowerShell 6.2. Senere når en 6.2 profil er gjort tilgjengelig, vil vi være i stand til å bytte over til det.,

Vi trenger å se under PSUseCompatibleCommands dokumentasjon for en liste over profiler som er tilgjengelige som standard. For vår ønskede målene vi velger:

Den lange navn på den høyre er kanonisk profil identifikatorer, som vi bruker i innstillinger:

Det kan være en forsinkelse første gang du utfører dette fordi reglene nødt til å laste ned kataloger til en buffer. Hver katalog av en PowerShell-plattformen inneholder detaljer over alle moduler og .,NET forsamlinger tilgjengelig for PowerShell på at plattformen, som kan være så mange som 1700-kommandoer med 15,000 parametere og 100 samlinger med 10.000 typer. Men når det er lastet, mer kompatibilitet analyse vil være rask. Vi får utgang 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 forteller oss at:

• Import-Module ikke støtter -FullyQualifiedName i PowerShell 3.0;
• Get-FileHash ikke finnes i PowerShell 3.0;
• Split-Path ikke -LeafBase i PowerShell 5.1 eller PowerShell-3.,0;
• Compress-Archive er ikke tilgjengelig i PowerShell 3.0, og;
• Out-File ikke støtter -NoNewline i PowerShell 3.0

En ting du vil legge merke til, er at Get-FoldersToArchive funksjon blir ikke varslet om. Dette er fordi kompatibilitet reglene er utformet for å ignorere brukerdefinert kommandoer; en kommando vil bare bli markert som uforenlig hvis det er til stede i noen profil og ikke i en av dine mål.,

Igjen, vi kan endre skript for å fikse disse advarslene, men før vi gjør det, vil jeg vise deg hvordan å gjøre dette til en mer sammenhengende opplevelse, som du vil endre skriptet du ønsker å vite om endringene du gjør bryte kompatibilitet, og det er lett å gjøre med trinnene nedenfor.

ved Hjelp av en innstillingsfil for gjentatt bruk

Det første vi ønsker å gjøre PSScriptAnalyzer bruken mer automatisert og reproduserbar. En fin skritt mot dette er å ta innstillinger hashtable vi gjorde og snu den til en deklarativ data fil, skille ut «hva» fra «hvordan».,

PSScriptAnalyzer vil godta en bane til en PSD1 i -Settings parameter, så alt vi trenger å gjøre er å slå våre hashtable i en PSD1 fil, som vi vil gjøre ./PSScriptAnalyzerSettings.psd1. Merker vi kan slå innstillingene for både PSUseCompatibleSyntax og PSUseCompatibleCommands:

Nå kan vi kjøre PSScriptAnalyzer igjen på skriptet ved å bruke innstillinger-fil:

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

Dette gir utgang:

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

Nå er vi ikke avhengig av noen variabler lenger, og har en egen spefication av analysen du ønsker., Ved hjelp av denne kan du sette dette inn i en kontinuerlig integrasjon miljøer, for eksempel for å sjekke at endringer i prosedyrer ikke bryte kompatibilitet.

Men hva vi egentlig vil, er å vite at PowerShell-skript opphold kompatibel mens du redigerer dem. Det er hva innstillingsfil er å bygge, og også der hvor det er lettest å gjøre de endringene du trenger å gjøre skriptet kompatibel. For at vi ønsker å integrere med VSCode PowerShell-extension.,

Integrere med VSCode for on-the-fly kompatibilitet å sjekke

Som forklart i starten av dette innlegget, VSCode PowerShell-extension har innebygd støtte for PSScriptAnalyzer. Faktisk, som av versjon 1.12.0, PowerShell extension skip med PSScriptAnalyzer 1.18, som betyr at du ikke trenger å gjøre noe annet enn å lage en innstillingsfil å gjøre kompatibilitet analyse.

Vi allerede har vår innstillinger-fil klar til å gå fra det siste trinnet, så alt vi trenger å gjøre er å peke PowerShell extension til filen i VSCode innstillinger.,

Du kan åpne innstillinger med Ctrl+, (bruk Cmd i stedet for Ctrl på mac os). I Innstillinger-visningen, vi vil PowerShell > Script Analysis: Settings Path. I settings.json vis dette er "powershell.scriptAnalysis.settingsPath"., Inn i en relativ bane her vil du finne en innstillingsfil i vår arbeidsplass, slik at vi bare sette ./PSScriptAnalyzerSettings.psd1:

I settings.json vis vil dette se slik ut:

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

Nå, åpne skript i VSCode vi se «grønn squigglies» for kompatibilitet advarsler:

I problemer ruten, vil du få en full desrciption av alle uforenlighet:

La oss løse syntaks problemet først., Hvis du husker, PSScriptAnalyzer leverer en foreslått endring på dette problemet. VSCode integreres med PSScriptAnalyzer er foreslått rettelser og kan bruke dem hvis du klikker på lyspære eller med Ctrl+Mellomrom når området er under markøren:

å Anvende denne endringen, skriptet er nå:

Den andre inkompabiliteter ikke har rettelser, for nå PSUseCompatibleCommands vet hvilke kommandoer som er tilgjengelige på hver enkelt plattform, men ikke hva som skal erstatte med når en kommando er ikke tilgjengelig., Så vi trenger bare å bruke noen PowerShell kunnskap:

Vi ender opp med noe sånt som dette (den konkrete gjennomføringen er uviktig, men vi har noe som vil fungere i alle versjoner):

Du bør legge merke til at hvert som du skriver, VSCode viser en ny analyse av det du skriver og den grønne squigglies slippe unna. Når vi er ferdig får vi en ren bill. av helse-skript for kompatibilitet:

Dette betyr at du vil nå være i stand til å bruke dette skriptet på tvers av alle PowerShell-versjoner du trenger for å målrette., Bedre er det at du nå har en konfigurasjon på din arbeidsplass, slik som du skriver mer skript, det er kontinuerlig for å sjekke kompatibilitet. Og hvis din kompatibilitet mål, endre, alt du trenger å gjøre er å endre din konfigurasjonsfil på ett sted til å peke til din ønskede mål, på hvilket punkt du vil få-analyse for din oppdatert målplattformer.

Oppsummering

Forhåpentligvis i dette blogginnlegg fikk du noen inntrykk av den nye kompatibilitet regler som kommer med PSScriptAnalyzer 1.18.,

Vi har dekket hvordan å sette opp og bruke syntaksen kompatibilitet kontrollere regelen, PSUseCompatibleSyntax, og kommando-kontroll-regelen, PSUseCompatibleCommands, både ved hjelp av en hashtable konfigurasjon og innstillinger PSD1 fil.

Vi har også sett på bruk av kompatibilitet reglene i med PowerShell extension for VSCode, hvor de kommer som standard versjon 1.12.0.

Hvis du har den siste versjonen av PowerShell extension for VSCode (1.12.1), vil du være i stand til å sette din konfigurasjonsfil og umiddelbart få kompatibilitet kontroll.,

I neste blogg innlegget, vil vi se på hvordan du kan bruke disse reglene og PSUseCompatibleTypes (som sjekker om .NETTO typer og statiske metoder som er tilgjengelige på målplattformer) kan brukes til å hjelpe deg med å skrive skript som fungerer på tvers av plattformer på tvers av Windows-og Linux-bruker både Windows PowerShell og PowerShell Kjerne.

Rob Holt

Software Engineer

PowerShell-Teamet