Wiele poradników, książek, kursów o PowerShell zaczyna od podstawowych cmdletów takich jak Get-Command i Get-Help. Sam również polecam się z nimi zapoznać, jeśli zaczynasz naukę PowerShell.

Mimo że polecenia realizują inne zadania, to mają jedną wspólną rzecz. Dzięki jednemu i drugiemu poznasz składnie interesujących Cię poleceń.

polecenia PowerShell - interpretacja skladni poleceń

Jeśli używasz PowerShell od jakiegoś czasu to jestem pewien, że takie składnie oglądałeś setki razy. Czy jednak dobrze wiesz jak ją interpretować Poniżej kilka informacji na temat, które pozwolą Ci lepiej czytać składnie poleceń w plikach pomocy PowerShell.

Zestawy parametrów

Polecenia PowerShell mogą posiadać wiele zestawów parametrów. Spójrz na poniższy przykład, składnia polecenia wymieniona jest 2 razy, co oznacza, że posiada dwa zestawy parametrów.

polecenia PowerShell - zestawy parametrow

Niektóre parametry są unikalne dla zestawu i jeśli użyjesz jednego z nich, wykluczysz możliwość wykorzystania pewnych parametrów z innego zestawu. Próba przechytrzenia PowerShella zakończy się błędem.

Get-AzResourceGroup: Parameter set cannot be resolved using the specified named parameters. One or more parameters 
issued cannot be used together or an insufficient number of parameters were provided.

Przekładając to na konkretny przykład, jeden zestaw polecenia Remove-AzResourceGroup, umożliwia usuwanie poprzez wskazanie nazwy (-Name), drugi poprzez identyfikator (-Id) grupy zasobów. Natomiast reszta parametrów jest wspólna.

Mimo zestawów (których może być nawet kilka, np. Where-Object ma ich 32), zawsze się znajdzie grupa parametrów wspólnych.

Rodzaje parametrów

Wyróżniamy parametry przyjmujące i nieprzyjmujące wartości, czyli tzw. przełączniki.

Te pierwsze rozpoznasz, po dodatkowych elementach w klamrach ostrokątnych <>, które są również dla Ciebie informacją o oczekiwanym typie danych (string, int, string[], itd.). Przełączniki natomiast to osamotnione nazwy parametrów.

polecenia PowerShell - parametry przyjmujące i nie przyjmujące wartości

Wśród tych dwóch rodzai możemy wyróżnić parametry obowiązkowe (obligatoryjne) oraz opcjonalne.

Parametry opcjonalne

Zacznijmy od parametrów opcjonalnych, które ułatwią później wyjaśnienie niuansu związanego z parametrami obowiązkowymi.

Przede wszystkim zapamiętaj, że wszystko, co otoczone nawiasami kwadratowymi [] to elementy opcjonalne. Parametr i jego wartość mogą być wprowadzone, ale nie muszą. Polecenie poradzi sobie bez nich, np. użyje wartości domyślnych.

polecenia PowerShell - parametry opcjonalne

Zostając przy poleceniach do zarządzania grupami zasobów, poniższe polecenie utworzy nową grupe zasobów w Azure bez dodatkowych tagów.

New-AzResourceGroup -Name apwebsite-rg

Element [<CommonParameter>] w składni to opcjonalny zestaw wspólnych parametrów (tj. Verbose, ErrorAction, Debug), które znajdziesz we wszystkich natywnych poleceniach oraz funkcjach z atrybutem [cmdletbinding()].

Parametry obowiązkowe

Na końcu mamy najważniejsze elementy do poprawnego działania poleceń. W zasadzie wszystkie co nie jest umieszczone, w żadnym nawiasie to parametry obligatoryjne, ale..

Wyżej wspomniałem o nawiasach kwadratowych [], które wskazują elementy opcjonalne. Otoczenie samej nazwy parametru oznacza, że możemy skrócić polecenie, wprowadzając tylko wymaganą wartość takiego parametru. Takie parametry nazywamy parametrami pozycyjnymi.

parametry obowiązkowe

Dla przykładu, dla polecenia Remove-AzResourceGroup wystarczy podać nazwę usuwanej grupy zasobów. PowerShell w takiej sytuacji identyfikuje wartość nienazwanego parametru na podstawie pozycji (wykorzystany zostanie pierwszy zestaw parametrów).

Remove-AzResourceGroup apwebsite-rg

Jak uzyskać parametry obligatoryjne w swoich funkcjach lub skryptach? Wystarczy, że dodasz atrybut Mandatory do swoich parametrów.

function Set-Parameter {
    param (
        [Parameter(Mandatory,Position=0)]
        $Param1,
        [Parameter(Mandatory=$false)]
        $Param2
    )
 
    $Param1
    $Param2
}
# Syntax
# Set-Parameter [-Param1] <Object> [-Param2 <Object>] [<CommonParameters>]

Podsumowanie

Celem wpisu było wyjaśnienie konwencji składni w plikach pomocy, aby lepiej rozumieć, które parametry są niezbędne, jakiego typu danych potrzebują i czemu pewne parametry nie są podpowiadane.

Mam nadzieje, że chociażby w minimalnym stopniu to się udało i znalazleś coś o czymś wcześniej nie wiedziałeś.

22 Najważniejsze Wskazówki Pisania Skryptów PowerShell

Mateusz Nadobnik

Zachwycony językiem skryptowym Windows PowerShell. Swoją wiedzę, doświadczenia i spostrzeżenia opisuję na blogu.

read more