Pomocí PSScriptAnalyzer zkontrolovat PowerShell verze kompatibilita

PSScriptAnalyzer verze 1.18 byl propuštěn v poslední době, a lodě s výkonnými nová pravidla, která můžete zkontrolovat PowerShell skripty pro neslučitelnost s jinými PowerShell verze a prostředí.

v tomto blogu, první v řadě, uvidíme, jak pomocí těchto nových pravidel zkontrolovat skript pro problémy běžící na PowerShell 3, 5.1 a 6.

počkat, co je PSScriptAnalyzer?,

PSScriptAnalzyer je modul poskytující statickou analýzu (nebo linting) a nějakou dynamickou analýzu (založenou na stavu vašeho prostředí) pro PowerShell. Je schopen najít problémy a opravit špatné návyky ve skriptech PowerShell, když je vytvoříte, podobně jako překladač C# vám dá varování a najde chyby v kódu C# před provedením.,

Pokud používáte VSCode PowerShell rozšíření, možná budete mít vidět, „zelené vlnění“ a problém hlásí, že PSScriptAnalyzer generuje skripty pro tebe autor:

můžete nainstalovat PSScriptAnalyzer použít na své vlastní skripty:

Install-Module PSScriptAnalyzer -Scope CurrentUser

PSScriptAnalyzer funguje spuštěním řadu pravidel, na své skripty, z nichž každý nezávisle hodnotí nějaký problém., Například AvoidUsingCmdletAliases zkontroluje, že aliasy nejsou použity ve skriptech, a MisleadingBackticks kontrol, které ve zpětném apostrofu na koncích řádků nejsou následovaný mezerou.

pro více informací, viz PSScriptAnalyzer deep dive blog série.

Představujeme kontrola kompatibility pravidel

nová kontrolu kompatibility funkce je poskytována tři nová pravidla:

• PSUseCompatibleSyntax, která kontroluje, zda syntaxe používané ve skriptu bude fungovat v jiných PowerShell verze.,
• PSUseCompatibleCommands, který kontroluje, zda příkazy používané ve skriptu jsou k dispozici v jiných prostředích PowerShell.
• PSUseCompatibleTypes, který kontroluje, zda typy. NET a statické metody / vlastnosti jsou k dispozici v jiných prostředích PowerShell.

kontrola syntaxe pravidlo jednoduše vyžaduje seznam PowerShell verze, na které chcete cílit, a řekne vám, pokud syntaxe používané ve skriptu nebude pracovat v žádném z těchto verzí.,

pravidla kontroly příkazů a typů jsou sofistikovanější a spoléhají se na profily (dostupné katalogy příkazů a typů) z běžně používaných platforem PowerShell. Vyžadují konfiguraci pro použití těchto profilů, které projdeme níže.

pro tento příspěvek se podíváme na konfiguraci a použití PSUseCompatibleSyntax a PSUseCompatibleCommands zkontrolovat, zda skript pracuje s různými verzemi PowerShell. Podíváme se na PSUseCompatibleTypes v pozdějším příspěvku, i když je nakonfigurován velmi podobně jako PSUseCompatibleCommands.,

Pracovní příklad: malé PowerShell skript

Představte si, že máme malou (a dokázal) archivní skript uložit do .\archiveScript.ps1:

Tento skript byl napsán v prostředí PowerShell 6.2, a které jsme testovali, že to tam funguje. Ale chceme ji spustit i na jiných strojích, z nichž některé běží PowerShell 5.1 a některé běží PowerShell 3.0.

V ideálním případě to otestujeme na těchto jiných platformách, ale bylo by hezké, kdybychom se mohli předem pokusit vyžehlit co nejvíce chyb.,

kontrola syntaxe pomocí PSUseCompatibleSyntax

první a nejjednodušší pravidlo, které se použije, je PSUseCompatibleSyntax. Budeme vytvářet nějaké nastavení pro PSScriptAnalyzer povolit pravidlo, a potom spusťte analýzu na náš script se dostat zpět diagnostiky o kompatibilitu.

Běh PSScriptAnalyzer je přímočarý., To přijde jako PowerShell modul, takže jakmile je nainstalován na vašem module cestu, právě jste jej uplatnit na váš soubor s Invoke-ScriptAnalyzer, například:

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

velmi jednoduché vyvolání jako je tento bude probíhat PSScriptAnalyzer pomocí jeho výchozí pravidla a konfigurace na scénáři si bod.

protože však vyžadují cílenější konfiguraci, pravidla kompatibility nejsou ve výchozím nastavení povolena. Místo toho musíme zadat některá nastavení pro spuštění pravidla kontroly syntaxe., Zejména PSUseCompatibleSyntax vyžaduje seznam verzí PowerShell, na které se zaměřujete pomocí skriptu.

spuštění tohoto představí se na nás s následující výstup:

To nám říká, že ]::new() syntaxe jsme použili nebude fungovat v prostředí PowerShell 3. Lepší, než to, že v tomto případě pravidlo má vlastně navrhuje opravu:

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

navrhovaná korekce je použít New-Object místo., Způsob, jakým se to navrhuje, se může zdát trochu neužitečný se všemi informacemi o poloze, ale uvidíme později, proč je to užitečné.

Tento slovník příklad je trochu umělý, samozřejmě (vzhledem k tomu, hashtable přijde více přirozeně), ale mít klíč hozený do práce v prostředí PowerShell 3 nebo 4, protože ::new() není neobvyklé. Na PSUseCompatibleSyntax pravidlo bude také varovat vás o třídách, pracovních postupů a using prohlášení v závislosti na verze PowerShell jsi authoring pro.,

navrhovanou změnu zatím neuděláme, protože je tu více, co vám nejprve ukážeme.

Kontrola využití příkazů pomocí PSUseCompatibleCommands

nyní chceme zkontrolovat příkazy. Vzhledem k tomu, že kompatibilita příkazů je o něco složitější než syntaxe (protože dostupnost příkazů závisí na více než na tom, jaká verze PowerShell je spuštěna), musíme místo toho cílit profily.

profily jsou katalogy informací převzatých ze skladových strojů s běžnými prostředími PowerShell., Ty dodávány v PSScriptAnalyzer nemůže vždy odpovídat vašeho pracovního prostředí dokonale, ale přijdou dost blízko (je to také způsob, jak vytvořit svůj vlastní profil, podrobně v dalším blogu). V našem případě se snažíme zaměřit PowerShell 3.0, PowerShell 5.1 a PowerShell 6.2 na Windows. Máme první dva profily, ale v posledním případě budeme muset místo toho zaměřit 6.1. Tyto cíle jsou velmi blízko, takže varování budou stále relevantní pro použití PowerShell 6.2. Později, když je k dispozici profil 6.2, budeme moci přejít na to.,

musíme se podívat pod dokumentaci PSUseCompatibleCommands pro seznam profilů dostupných ve výchozím nastavení. Pro naše požadované cíle vybereme:

dlouhé názvy vpravo jsou identifikátory kanonického profilu, které používáme v nastavení:

při prvním spuštění může dojít ke zpoždění, protože pravidla musí načíst katalogy do mezipaměti. Každý katalog platformy PowerShell obsahuje podrobnosti o všech modulech a .,Síťové sestavy dostupné pro PowerShell na této platformě, což může být až 1700 příkazů s 15 000 parametry a 100 sestav s 10 000 typy. Ale jakmile je načten, další analýza kompatibility bude rychlá. Dostaneme výstup jako tento:

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"

To nám říká, že:

• Import-Module nepodporuje -FullyQualifiedName v PowerShell 3.0;
• Get-FileHash neexistuje v PowerShell 3.0;
• Split-Path nemá -LeafBase v PowerShell 5.1 nebo PowerShell 3.,0;
• Compress-Archive není k dispozici v PowerShell 3.0 a;
• Out-File nepodporuje -NoNewline v PowerShell 3.0

Jedna věc, kterou si všimnete, je, že Get-FoldersToArchive funkce není varoval o tom. Je to proto, slučitelnost pravidel jsou navrženy tak, aby ignorovat uživatele-za předpokladu, příkazy, příkaz bude označen jako nekompatibilní, pokud je přítomen v některých profil a ne v jednom z vašich cílů.,

Opět, můžeme změnit scénář, aby opravit tyto varování, ale než to uděláme, chci vám ukázat, jak, aby se tento více nepřetržitý zážitek, jak si změnit nastavení skriptu, chcete vědět, jestli změny, které provedete s kompatibilitou, a to je snadné dělat s kroky níže.

Pomocí nastavení souboru pro opakované vyvolání

první věc, kterou chceme, je, aby se PSScriptAnalyzer vyvolání více automatizované a reprodukovatelné. Pěkný krok směrem to bere nastavení hashtable jsme udělali, a převést ji do deklarativní soubor dat, oddělit „co“ „jak“.,

PSScriptAnalyzer bude akceptovat cestu k PSD1 v -Settings parametr, takže vše, co musíme udělat, je otočit naše hashtable do PSD1 soubor, který uděláme ./PSScriptAnalyzerSettings.psd1. Všimněte si můžeme sloučit nastavení pro oba PSUseCompatibleSyntax a PSUseCompatibleCommands:

Nyní můžeme spustit PSScriptAnalyzer opět na skriptu pomocí souboru nastavení:

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

To dává výstup:

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

Teď nejsme závislí na žádné proměnné už, a mají samostatný spefication analýzy, které chcete., Pomocí tohoto, můžete dát to do kontinuální integrační prostředí, například pro kontrolu, že změny ve skriptech neporušují kompatibilitu.

ale to, co opravdu chceme, je vědět, že skripty PowerShell zůstávají kompatibilní, když je upravujete. To je to, co Soubor Nastavení buduje, a také tam, kde je nejjednodušší provést změny, které potřebujete, aby byl váš skript kompatibilní. Za tímto účelem se chceme integrovat s rozšířením VSCode PowerShell.,

Integrace s VSCode pro on-the-fly kontrolu kompatibility

Jak bylo vysvětleno na začátku tohoto příspěvku, VSCode PowerShell rozšíření má vestavěný podpora pro PSScriptAnalyzer. Ve skutečnosti, od verze 1.12.0, PowerShell rozšíření lodě s PSScriptAnalyzer 1.18, což znamená, že nemusíte dělat nic jiného, než vytvořit nastavení souboru udělat analýzu slučitelnosti.

již máme Soubor Nastavení připravený k přechodu z posledního kroku, takže vše, co musíme udělat, je ukázat příponu PowerShell na soubor v nastavení VSCode.,

nastavení můžete otevřít pomocí Ctrl + (použijte Cmd místo Ctrl na macOS). V zobrazení nastavení chceme PowerShell > Script Analysis: Settings Path. Vsettings.json zobrazit toto je "powershell.scriptAnalysis.settingsPath"., Zadání relativní cesty zde najdete nastavení souboru v našem prostoru, takže jsme prostě dát ./PSScriptAnalyzerSettings.psd1:

V settings.json pohled to bude vypadat jako:

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

Nyní, otevření skript v VSCode vidíme „zelené vlnění“ pro kompatibilitu varování:

V problémy panelu, dostanete plnou desrciption všech inkompatibility:

Pojďme opravit problém, syntax první., Pokud si pamatujete, PSScriptAnalyzer dodává navrhovanou opravu tohoto problému. VSCode integruje s PSScriptAnalyzer je navrhl, opravy a můžete je použít, pokud kliknete na žárovku nebo s Ctrl+Space, kdy region je pod kurzorem:

Použití tato změna, scénář je teď:

další nekompatibility nemám oprav; teď PSUseCompatibleCommands ví, jaké příkazy jsou k dispozici na každé platformě, ale není co nahradit, když příkaz není k dispozici., Takže jen musíme použít nějaký PowerShell znalosti:

skončíme s něčím, jako je toto (konkrétní implementace je nedůležité, ale máme něco, co bude fungovat ve všech verzích):

měli byste Si všimnout, že, jak píšete, VSCode zobrazí novou analýzu toho, co píšeš a zelené vlnění drop pryč. Až skončíme, získáme čistý zdravotní stav pro kompatibilitu skriptů:

to znamená, že nyní budete moci použít tento skript ve všech verzích PowerShell, které potřebujete zaměřit., Lepší je, že nyní máte v pracovním prostoru konfiguraci, takže když píšete více skriptů,neustále se kontroluje Kompatibilita. A pokud se vaše cíle kompatibility změní, vše, co musíte udělat, je změnit konfigurační soubor na jednom místě tak, aby ukázal na požadované cíle, na kterém místě získáte analýzu aktualizovaných cílových platforem.

shrnutí

doufejme, že v tomto blogu máte nějakou představu o nových pravidlech kompatibility, která přicházejí s PSScriptAnalyzer 1.18.,

Jsme probrali, jak nastavit a použít syntaxi kontrolu kompatibility pravidlo, PSUseCompatibleSyntax, a příkaz kontrola pravidlo, PSUseCompatibleCommands, jak pomocí hash tabulky konfigurace a nastavení PSD1.

také jsme se podívali na použití pravidel kompatibility s příponou PowerShell pro VSCode, kde přicházejí ve výchozím nastavení z verze 1.12.0.

Pokud máte nejnovější verzi PowerShell rozšíření pro VSCode (1.12.1), budete moci nastavit konfigurační soubor a okamžitě získat kontrolu kompatibility.,

V příštím blogu se podíváme na to, jak používat tato pravidla a PSUseCompatibleTypes (který kontroluje, zda .ČISTÉ typy a statické metody jsou k dispozici na cílové platformy), mohou být použity, aby vám pomohl napsat skripty, které pracují multiplatformní přes Windows a Linux pomocí Windows PowerShell a PowerShell Core.

Rob Holt

softwarový inženýr

PowerShell Team