Verwenden von PSScriptAnalyzer zum Überprüfen der Kompatibilität der PowerShell-Version

PSScriptAnalyzer Version 1.18 wurde kürzlich veröffentlicht und enthält leistungsstarke neue Regeln, mit denen PowerShell-Skripte auf Inkompatibilitäten mit anderen PowerShell-Versionen und-Umgebungen überprüft werden können.

In diesem Blogbeitrag, dem ersten in einer Reihe, werden wir sehen, wie Sie diese neuen Regeln verwenden, um ein Skript auf Probleme mit PowerShell 3, 5.1 und 6 zu überprüfen.

Warte, was ist PSScriptAnalyzer?,

PSScriptAnalzyer ist ein Modul, das statische Analysen (oder Linting) und dynamische Analysen (basierend auf dem Status Ihrer Umgebung) für PowerShell bereitstellt. Es ist in der Lage, Probleme zu finden und schlechte Gewohnheiten in PowerShell-Skripten zu beheben, während Sie sie erstellen, ähnlich wie der C# – Compiler Warnungen ausgibt und Fehler im C# – Code findet, bevor er ausgeführt wird.,

Wenn Sie die VSCode PowerShell-Erweiterung verwenden, haben Sie möglicherweise die „grünen Squigglies“ und Problemberichte gesehen, die PSScriptAnalyzer für Skripte generiert, die Sie verfassen:

Sie können PSScriptAnalyzer für Ihre eigenen Skripte installieren mit:

Install-Module PSScriptAnalyzer -Scope CurrentUser

PSScriptAnalyzer führt eine Reihe von Regeln für Ihre Skripte aus, von denen jedes ein Problem unabhängig bewertet., Beispiel: AvoidUsingCmdletAliases überprüft, ob Aliase in Skripten nicht verwendet werden, und MisleadingBackticks überprüft, ob Backticks an den Zeilenenden nicht gefolgt werden Leerzeichen.

weitere Informationen finden Sie in der PSScriptAnalyzer deep dive blog-Serie.

Einführung der Kompatibilitätsprüfungsregeln

Die neue Kompatibilitätsprüfungsfunktion wird durch drei neue Regeln bereitgestellt:

• PSUseCompatibleSyntax, mit denen überprüft wird, ob eine in einem Skript verwendete Syntax in anderen PowerShell-Versionen funktioniert.,
• PSUseCompatibleCommands, mit dem überprüft wird, ob in einem Skript verwendete Befehle in anderen PowerShell-Umgebungen verfügbar sind.
• PSUseCompatibleTypes, mit dem überprüft wird, ob.NET-Typen und statische Methoden/Eigenschaften in anderen PowerShell-Umgebungen verfügbar sind.

Die Syntaxprüfungsregel erfordert lediglich eine Liste der PowerShell-Versionen, auf die Sie abzielen möchten, und teilt Ihnen mit, ob eine in Ihrem Skript verwendete Syntax in keiner dieser Versionen funktioniert.,

Die Regeln für die Befehls – und Typprüfung sind ausgefeilter und basieren auf Profilen (Katalogen verfügbarer Befehle und Typen) häufig verwendeter PowerShell-Plattformen. Sie erfordern eine Konfiguration, um diese Profile zu verwenden, auf die wir unten eingehen werden.

In diesem Beitrag werden wir uns mit der Konfiguration und Verwendung von PSUseCompatibleSyntax und PSUseCompatibleCommands befassen, um zu überprüfen, ob ein Skript mit verschiedenen Versionen von PowerShell funktioniert. Wir werden uns PSUseCompatibleTypes in einem späteren Beitrag ansehen, obwohl es PSUseCompatibleCommands sehr ähnlich konfiguriert ist.,

Arbeitsbeispiel: ein kleines PowerShell-Skript

Stellen Sie sich vor, wir haben ein kleines (und erfundenes) Archivskript gespeichert .\archiveScript.ps1:

Dieses Skript wurde in PowerShell 6.2 geschrieben und wir haben getestet, dass es dort funktioniert. Wir möchten es aber auch auf anderen Computern ausführen, auf denen einige PowerShell 5.1 und andere PowerShell 3.0 ausführen.

Idealerweise werden wir es auf diesen anderen Plattformen testen, aber es wäre schön, wenn wir versuchen könnten, so viele Fehler wie möglich im Voraus auszubügeln.,

Syntax mit PSUseCompatibleSyntax überprüfen

Die erste und einfachste anzuwendende Regel ist PSUseCompatibleSyntax. Wir werden einige Einstellungen für PSScriptAnalyzer erstellen, um die Regel zu aktivieren, und dann eine Analyse in unserem Skript ausführen, um Diagnosen zur Kompatibilität zu erhalten.

Das Ausführen von PSScriptAnalyzer ist unkompliziert., Sobald es in Ihrem Modulpfad installiert ist, rufen Sie es einfach in Ihrer Datei mit Invoke-ScriptAnalyzer auf:

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

Ein sehr einfacher Aufruf wie dieser führt PSScriptAnalyzer mit seinen Standardregeln und Konfigurationen für das Skript aus, auf das Sie verweisen.

Da sie jedoch eine gezieltere Konfiguration erfordern, sind die Kompatibilitätsregeln standardmäßig nicht aktiviert. Stattdessen müssen wir einige Einstellungen angeben, um die Syntaxprüfungsregel auszuführen., Insbesondere erfordert PSUseCompatibleSyntax eine Liste der PowerShell-Versionen, auf die Sie mit Ihrem Skript abzielen.

Wenn Sie dies ausführen, erhalten wir die folgende Ausgabe:

Dies sagt uns, dass die von uns verwendete]::new() – Syntax in PowerShell 3 nicht funktioniert. Besser noch, in diesem Fall hat die Regel tatsächlich einen Fix vorgeschlagen:

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

Die vorgeschlagene Korrektur besteht darin, stattdessen New-Object zu verwenden., Die Art und Weise, wie dies vorgeschlagen wird, mag hier mit allen Positionsinformationen etwas nicht hilfreich erscheinen, aber wir werden später sehen, warum dies nützlich ist.

Dieses Wörterbuchbeispiel ist natürlich etwas künstlich (da eine Hashtabelle natürlicher wäre), aber ein Schlüssel in PowerShell 3 oder 4 aufgrund einer ::new() ist nicht ungewöhnlich. Die PSUseCompatibleSyntax-Regel warnt Sie auch vor Klassen, Workflows und using – Anweisungen, abhängig von den Versionen von PowerShell, für die Sie erstellen.,

Wir werden die vorgeschlagene Änderung noch nicht vornehmen, da es Ihnen zuerst mehr zu zeigen gibt.

Überprüfen der Befehlsverwendung mit PSUseCompatibleCommands

Wir möchten jetzt die Befehle überprüfen. Da die Befehlskompatibilität etwas komplizierter ist als die Syntax (da die Verfügbarkeit von Befehlen davon abhängt, welche Version von PowerShell ausgeführt wird), müssen wir stattdessen auf Profile abzielen.

Profile sind Kataloge von Informationen aus Standardmaschinen, auf denen gängige PowerShell-Umgebungen ausgeführt werden., Die in PSScriptAnalyzer gelieferten können nicht immer perfekt zu Ihrer Arbeitsumgebung passen, aber sie kommen ziemlich nahe (es gibt auch eine Möglichkeit, ein eigenes Profil zu erstellen, das in einem späteren Blogbeitrag detailliert beschrieben wird). In unserem Fall versuchen wir, PowerShell 3.0, PowerShell 5.1 und PowerShell 6.2 unter Windows anzuvisieren. Wir haben die ersten beiden Profile, aber im letzten Fall müssen wir stattdessen auf 6.1 abzielen. Diese Ziele liegen sehr nahe beieinander, sodass Warnungen für die Verwendung von PowerShell 6.2 weiterhin relevant sind. Später, wenn ein neues Profil verfügbar gemacht wird, können wir dazu wechseln.,

Wir müssen in der Dokumentation zu PSUseCompatibleCommands nach einer Liste der standardmäßig verfügbaren Profile suchen. Für unsere gewünschten Ziele wählen wir:

Die langen Namen auf der rechten Seite sind kanonische Profilbezeichner, die wir in den Einstellungen verwenden:

Beim ersten Ausführen kann es zu einer Verzögerung kommen, da die Regeln die Kataloge in einen Cache laden müssen. Jeder Katalog einer Powershell-Plattform enthält Details aller Module und .,NET Assemblies verfügbar PowerShell auf dieser Plattform, die so viele wie 1700 Befehle mit 15.000 Parametern und 100 Baugruppen mit 10.000 Typen sein kann. Aber sobald es geladen ist, wird eine weitere Kompatibilitätsanalyse schnell sein. Wir erhalten eine Ausgabe wie folgt:

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"

Dies sagt uns, dass:

• Import-Module -FullyQualifiedName in PowerShell 3.0 nicht unterstützt;
• Get-FileHash existiert nicht in PowerShell 3.0;
• Split-Path hat in PowerShell 5.1 oder PowerShell 3 keine -LeafBase.,0;
• Compress-Archive ist in PowerShell 3.0 nicht verfügbar, und;
• Out-File unterstützt -NoNewline in PowerShell 3.0

Sie werden feststellen, dass die Funktion Get-FoldersToArchive nicht gewarnt wird. Dies liegt daran, dass die Kompatibilitätsregeln so konzipiert sind, dass vom Benutzer bereitgestellte Befehle ignoriert werden. Ein Befehl wird nur dann als inkompatibel markiert, wenn er in einem Profil und nicht in einem Ihrer Ziele vorhanden ist.,

Auch hier können wir das Skript ändern, um diese Warnungen zu beheben, aber bevor wir dies tun, möchte ich Ihnen zeigen, wie Sie dies zu einer kontinuierlicheren Erfahrung machen können; Wenn Sie Ihr Skript ändern, möchten Sie wissen, ob die Änderungen, die Sie vornehmen, die Kompatibilität beeinträchtigen, und das ist einfach mit den folgenden Schritten zu tun.

Verwenden einer Einstellungsdatei für wiederholten Aufruf

Als erstes möchten wir den PSScriptAnalyzer-Aufruf automatisierter und reproduzierbarer machen. Ein schöner Schritt dazu ist, die von uns vorgenommene Einstellungen-Hashtabelle in eine deklarative Datendatei umzuwandeln und das „Was“ vom „Wie“zu trennen.,

PSScriptAnalyzer akzeptiert einen Pfad zu einem PSD1 im Parameter -Settings, also müssen wir nur unsere Hashtabelle in eine PSD1-Datei umwandeln, die wir machen werden ./PSScriptAnalyzerSettings.psd1. Beachten Sie, dass wir die Einstellungen für PSUseCompatibleSyntax und PSUseCompatibleCommands zusammenführen können:

Jetzt können wir den PSScriptAnalyzer mithilfe der Einstellungsdatei erneut im Skript ausführen:

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

Dies gibt die Ausgabe:

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

Jetzt sind wir nicht mehr auf Variablen angewiesen, und haben eine separate spefication der Analyse, die Sie wollen., Auf diese Weise können Sie dies beispielsweise in kontinuierliche Integrationsumgebungen einfügen, um zu überprüfen, ob Änderungen in Skripten die Kompatibilität nicht beeinträchtigen.

Aber was wir wirklich wollen, ist zu wissen, dass PowerShell-Skripte beim Bearbeiten kompatibel bleiben. Darauf baut die Einstellungsdatei auf und auch dort ist es am einfachsten, die Änderungen vorzunehmen, die Sie benötigen, um Ihr Skript kompatibel zu machen. Dafür wollen wir mit der VSCode PowerShell Erweiterung integrieren.,

Integration mit VSCode für On-the-fly-Kompatibilitätsprüfung

Wie am Anfang dieses Beitrags erläutert, VSCode Powershell-Erweiterung hat eingebaute Unterstützung für PSScriptAnalyzer. Tatsächlich wird die PowerShell-Erweiterung ab Version 1.12.0 mit PSScriptAnalyzer 1.18 ausgeliefert, was bedeutet, dass Sie nichts anderes tun müssen, als eine Einstellungsdatei für die Kompatibilitätsanalyse zu erstellen.

Wir haben bereits unsere Einstellungsdatei bereit, vom letzten Schritt an zu gehen, also müssen wir nur die PowerShell-Erweiterung auf die Datei in den VSCode-Einstellungen zeigen.,

Sie können die Einstellungen mit Strg + öffnen (verwenden Sie Cmd anstelle von Strg unter macOS). In der Ansicht Einstellungen möchten wir PowerShell > Script Analysis: Settings Path. In dersettings.json Ansicht ist dies "powershell.scriptAnalysis.settingsPath"., Wenn Sie hier einen relativen Pfad eingeben, finden Sie eine Einstellungsdatei in unserem Arbeitsbereich, also setzen wir einfach ./PSScriptAnalyzerSettings.psd1:

In die settings.json Ansicht Dies wird so aussehen:

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

Jetzt beim Öffnen des Skripts in VSCode sehen wir „green squigglies“ für Kompatibilitätswarnungen:

Im Problembereich erhalten Sie eine vollständige desrciption aller Inkompatibilitäten:

Lassen Sie uns zuerst das Syntaxproblem beheben., Wenn Sie sich erinnern, liefert pssriptanalyzer eine vorgeschlagene Korrektur für dieses Problem. VSCode integriert sich in die vorgeschlagenen Korrekturen von PSScriptAnalyzer und kann sie anwenden, wenn Sie auf die Glühbirne oder mit Strg+Leerzeichen klicken, wenn sich der Bereich unter dem Cursor befindet:

Wenn Sie diese Änderung anwenden, ist das Skript jetzt:

Die anderen Inkompatibilitäten haben keine Korrekturen; PSUseCompatibleCommands weiß vorerst, welche Befehle auf jeder Plattform verfügbar sind, aber nicht, was zu ersetzen ist, wenn ein Befehl ist nicht verfügbar., Wir müssen also nur etwas PowerShell-Wissen anwenden:

Am Ende haben wir so etwas (die spezifische Implementierung ist unwichtig, aber wir haben etwas, das in allen Versionen funktioniert):

Sie sollten bemerken, dass VSCode beim Tippen eine neue Analyse dessen anzeigt, was Sie schreiben, und die grünen Squigglies fallen weg. Wenn wir fertig sind, erhalten wir eine saubere Rechnung für die Skriptkompatibilität:

Dies bedeutet, dass Sie dieses Skript jetzt in allen PowerShell-Versionen verwenden können, auf die Sie abzielen müssen., Besser noch, Sie haben jetzt eine Konfiguration in Ihrem Arbeitsbereich, sodass beim Schreiben weiterer Skripte kontinuierlich die Kompatibilität überprüft wird. Und wenn sich Ihre Kompatibilitätsziele ändern, müssen Sie lediglich Ihre Konfigurationsdatei an einem Ort ändern, um auf die gewünschten Ziele zu zeigen, an diesem Punkt erhalten Sie eine Analyse für Ihre aktualisierten Zielplattformen.

Zusammenfassung

Hoffentlich haben Sie in diesem Blogbeitrag eine Vorstellung von den neuen Kompatibilitätsregeln, die mit PSScriptAnalyzer 1.18 geliefert werden.,

Wir haben behandelt, wie die Syntaxkompatibilitätsprüfungsregel PSUseCompatibleSyntax und die Befehlsprüfungsregel PSUseCompatibleCommands eingerichtet und verwendet werden, wobei sowohl eine Hashtable-Konfiguration als auch eine Einstellungen-PSD1-Datei verwendet werden.

Wir haben uns auch die Verwendung der Kompatibilitätsregeln in der PowerShell-Erweiterung für VSCode angesehen, wo sie standardmäßig ab Version 1.12.0 stammen.

Wenn Sie die neueste Version der PowerShell-Erweiterung für VSCode (1.12.1) haben, können Sie Ihre Konfigurationsdatei festlegen und sofort die Kompatibilitätsprüfung erhalten.,

Im nächsten Blogbeitrag werden wir uns die Verwendung dieser Regeln und PSUseCompatibleTypes ansehen (die prüfen, ob.NET-Typen und statische Methoden auf Zielplattformen verfügbar sind), um Ihnen beim plattformübergreifenden Schreiben von Skripten zu helfen Windows und Linux mit Windows PowerShell und PowerShell Core.

Rob Holt

Software Engineer

PowerShell-Team