W poprzednich dwóch artykułach zaprezentowałem. jak konfigurować podstawowe komponenty, tak by Visual Studio Code działał podobnie do PowerShell ISE. W części trzeciej przy prezentowaniu wbudowanych w VS Code funkcjonalności, przedstawiłem korzystanie ze skrótów klawiaturowych. Teraz omówię wykorzystanie funkcjonalności modułu „PSScriptAnalyzer”.

PSScriptAnalyzer to statyczny kontroler kodu dla modułów i skryptów Windows PowerShell. Sprawdza jakość kodu Windows PowerShell, uruchamiając zestaw reguł, które opierają się na najlepszych praktykach określonych przez społeczność i zespół PowerShell oraz generuje wyniki diagnostyczne (błędy i ostrzeżenia) informujące użytkowników o potencjalnych wadach kodu i sugerujące możliwe ulepszenia. PSScriptAnalyzer jest dostarczany z kolekcją wbudowanych reguł, które sprawdzają różne aspekty kodu PowerShell.

Domyślna instalacja programu Visual Studio Code zawiera moduł PSScriptAnalyzer, nie ma więc potrzeby instalowania go osobno tak jak w przypadku PowerShell ISE. Po wykonaniu polecenia:

Get-Module -ListAvailable

 możemy zaobserwować, że moduł jest zlokalizowany w profilu danego użytkownika:

.vscode\extensions\ms-vscode.powershell-2019.9.0\modules

Aktualna wersja modułu PSScriptAnalyzer, czyli 1.18.3, zawiera 59 reguł.  Są one podzielone według stopnia dotkliwości na Error (6), Warning (43) oraz Information (10). Wykorzystując poniższe polecenia, możemy wyświetlić reguły według stopnia dotkliwości.

Get-ScriptAnalyzerRule -Severity Error

Get-ScriptAnalyzerRule -Severity Warning

Get-ScriptAnalyzerRule -Severity Information

Nie wszystkie reguły są aktywne po zainstalowaniu rozszerzenia do PowerShell;  w Visual Studio Code domyślnie włączone są tylko niektóre z nich.  Aby uzyskać dostęp do reguł, należy przejść do palety komend (F1 lub ctrl+shift+p) i wpisać PowerShell, bądź, jeśli ktoś skonfigurował skróty klawiaturowe tak jak jest to opisane w poprzednim artykule, wcisnąć shift+windows+insert i wybrać „Select PSScriptAnalyzer Rules”. Domyślna konfiguracja obejmuje 14 reguł.

W wielu wypadkach będziemy chcieli dostosować zachowanie się PSScriptAnalyzer do własnych potrzeb. Możemy to zrealizować korzystając z prekonfigurowanych ustawień, które następnie zmodyfikujemy. Przykładowe pliki znajdziemy w dwóch lokalizacjach w profilu użytkownika:

.vscode\extensions\ms-vscode.powershell-2019.11.0\examples – PSScriptAnalyzerSettings.psd1

PSScriptAnalyzerSettings.psd1 – obejmuje reguły obowiązujące i reguły wykluczone. Generowane będą tylko rekordy diagnostyczne o określonej ważności. Jeśli potrzebujemy wyłącznie reguł dotyczących Błędów i Ostrzeżeń, ale bez informacji diagnostycznych, musimy usunąć znak komentarza  przed Severity = @ („Błąd”, „Ostrzeżenie”). Jeśli chcemy analizować tylko określone zasady, wykorzystujemy „IncludeRules” do wywołania niewielkiego podzbioru reguł domyślnych. Kolejnym konfigurowalnym elementem jest możliwość nieanalizowania określonych zasad. W tym wypadku użyjemy ExcludeRules. Reguły domyślne będą dostępne poza wyjątkiem, który zostanie tutaj zdefiniowany. Należy pamiętać, że jeśli reguła znajduje się zarówno w regułach IncludeRules, jak i ExcludeRules, zostanie wykluczona. Można również użyć  Whitelist, aby  zapobiec m.in. oznaczaniu przez PSScriptAnalyzer preferowanych aliasów.

.vscode\extensions\ms-vscode.powershell-2019.11.0\examples\.vscode – settings.json

Plik „settings.json” – zawiera informację o tym jak skonfigurować ustawienia, by plik „PSScriptAnalyzerSettings.psd1” stał się obowiązujący, czyli jak użyć niestandardowego pliku ustawień PSScriptAnalyzer dla naszego obszaru roboczego.  Jest to możliwe np.  dzięki ustawieniu ścieżki względnej do katalogu głównego:

„powershell.scriptAnalysis.settingsPath”: „./PSScriptAnalyzerSettings.psd1”

lub ścieżki bezwzględnej (w naszym przykładzie użyłem właśnie jej):

„powershell.scriptAnalysis.settingsPath”: „c:\\MyScripts\\PSScriptAnalyzerSettings.psd1”

Aktualna konfiguracja pliku “settings.json” wygląda następująco:

Skonfigurowane opcje to:

Do czego służą wybrane opcje?

PSAvoidUsingCmdletAliases – alias to alternatywna nazwa lub pseudonim dla polecenia CMDlet lub elementu polecenia, takiego jak funkcja, skrypt, plik lub plik wykonywalny. Aliasów  można używać zamiast zwykłych nazw  w dowolnych poleceniach Windows PowerShell. Istnieją również ukryte aliasy – gdy PowerShell nie może znaleźć nazwy polecenia cmdlet, spróbuje dołączyć do niego „Get-„. Niestety aliasy mogą czasem utrudniać odczytanie i zrozumienie kodów oraz źle wpływać na ich dostępność. Podczas pisania skryptów PowerShell, które będą zarządzane i wykonywane przez innych użytkowników, należy zawsze używać pełnych nazw poleceń.

PSUseApprovedVerbs – wszystkie CMDlety muszą używać zatwierdzonych czasowników.  Czasowniki te można znaleźć po uruchomieniu polecenia  „Get-Verb”. Dodatkowa dokumentacja na ich temat jest dostępna na stronie z dokumentami Microsoft w sekcji „Zatwierdzone czasowniki dla poleceń programu PowerShell”. Dobrą praktyka jest używanie zatwierdzonych czasowników dla naszych własnych funkcji.

Efekt skonfigurowanych reguł.

PSAvoidUsingCmdletAliases

Jeśli zamiast pełnej nazwy cmdlet użyliśmy aliasu, pojawi  nam się symbol żółtej żarówki, a po najechaniu na nią kursorem  – okna „Show Fixes”. Poniżej panelu skryptowego w zakładce „Problems” zobaczymy cyfrę informującą o ilości problemów.

Po zaznaczeniu opcji „Show Fixes” ujrzymy następujący komunikat.

W moim przypadku alias FT jest już zamieniony na pełne polecenie Format-Table. Mogę teraz podobnie postąpić z „gwmi” lub wyświetlić dokumentację danego problemu, która znajduje się na portalu GitHub. W tym wypadku zachęcam do zapoznania się z dokumentacją.

PSUseApprovedVerbs

Skorzystam teraz z gotowego skryptu ze zdefiniowaną funkcją „ Active-ADComputers” oraz dodam kolejną regułę „PSUseSingularNouns” do pliku „ PSScriptAnalyzerSettings.psd1”

Nasz problem wygląda następująco:

W tym wypadku nie mamy opcji naprawczych, ale na portalu GitHub możemy zapoznać się z dokumentacją dotyczącą danego problemu.

Jak rozwiązać problem? Rzeczownik musi być w liczbie pojedynczej, zamieniamy więc „ADComputers” na „ADComputer”. Pierwszy problem usunięty. Dokumentacja do drugiego zaleca nam skorzystać z polecenia „get-verb”, gdzie dostajemy listę zatwierdzonych czasowników. W tym wypadku, gdy mamy do czynienia z funkcją wykorzystującą protokół ICMP, logicznym wyborem będzie czasownik „Ping”, który znajduje się w grupie Diagnostic.

Teraz wrócimy do reguły „PSAvoidUsingCmdletAliases”. Naszym zadaniem jest taka konfiguracja,  w której pewne aliasy nie spowodują wyświetlania komunikatu błędu. W tym przykładzie będziemy chcieli korzystać z następujących aliasów: „gm, cd i ?”. Dopóki nie zmienimy konfiguracji, sytuacja wygląda następująco:

Aby wyeliminować  komunikaty błędów, wracamy do pliku „ PSScriptAnalyzerSettings.psd1” i konfigurujemy następujące opcje.

Po wykonaniu poleceń

Get-Process | gm

cd c:\temp

Get-Service | ? { $psitem.Status -eq ‚running’ }

 możemy się przekonać, że zakładka „Problems” nie wyświetla już komunikatów błędów.

Niniejszy artykuł  przybliża tematykę poprawności kodu w PowerShell, z pewnością jednak jej nie wyczerpuje.  Każdy użytkownik może wybrać zestaw reguł odpowiednich w jego środowisku  oraz zapoznać się z wytycznymi do danej reguły poprzez obejrzenie dokumentacji na portalu GitHub.