Twoje własne polecenie, czyli pierwsza funkcja w PowerShellu

Cześć, witaj w kolejnym wpisie z cyklu PowerShell Podstawy. Do tej pory nauczyłeś się już całkiem sporo: wiesz czym jest Powershell i jak z nim pracować, rozumiesz logikę obiektową i znasz podstawy pracy ze zmiennymi. Czas zatem na kolejny krok i budowę własnych fragmentów kodu. W tym wpisie wyjaśnię czym jest, jak działa oraz jak tworzyć własne funkcje w PowerShellu.

Zacznijmy od teorii – co to właściwie jest funkcja?

Funkcja w PowerShellu to mały fragment kodu, który wykonuje konkretne zadanie, coś w rodzaju mini-programu w Twoim skrypcie. Dzięki niej możesz raz napisać kod, a potem wielokrotnie go wykorzystywać, bez potrzeby powtarzania tych samych poleceń. Takie podejście pozwala utrzymać porządek w skryptach, ułatwia ich czytanie i wprowadzanie zmian. Każda funkcja ma swoją nazwę i może przyjmować dane wejściowe, czyli parametry, które wpływają na jej działanie. Używanie funkcji to krok w stronę bardziej profesjonalnego i uporządkowanego pisania skryptów w PowerShellu.

Jak działa funkcja?

Definiując funkcję, nadajesz jej nazwę i określasz, jaki kod ma się uruchomić, gdy ją wywołasz.

Podstawowa składnia wygląda tak:

function Nazwa-Funkcji {
    <kod, który wykona się po wywołaniu funkcji>
}

A przykładowy kod może wyglądać np. tak:

function Show-Greeting {
    Write-Output "Hello, welcome to my first function!"
}

Jak to działa?

• Zaczynamy od słowa kluczowego function — oznacza ono, że właśnie definiujemy funkcję
• Następnie podajemy nazwę funkcji, dobrą praktyką w PowerShellu jest stosowanie schematu czasownik-rzeczownik, np. Show-Greeting, Get-FreeSpace itp.
• W nawiasach klamrowych { } umieszczamy kod, który funkcja ma wykonać

⚠️Ważne

Kiedy tworzysz funkcję, nie uruchamiasz jej od razu tylko definiujesz, co ma robić.
Żeby PowerShell „zapamiętał” Twoją funkcję, musisz wykonać jej definicję przynajmniej raz. Po tym PowerShell będzie wiedział, że taka funkcja istnieje i co powinna robić.

Przykład:

function Show-Greeting { Write-Output "Hello, welcome to my first function!"}

Wklej powyższy kod do konsoli i naciśnij Enter. Na ekranie nic się jeszcze nie pojawi bo właśnie w tym momencie tylko zdefiniowałeś funkcję. Teraz, aby ją wywołać wpisz jej nazwę:

PS C:\Users\Admin> Show-Greeting
Hello, welcome to my first function!

PowerShell wykonał kod wewnątrz funkcji i zwróci wynik.

Podsumowanie kroków:

1. Uruchom definicję funkcji – wczytujesz ją do pamięci
2. Wywołaj funkcję po nazwie – uruchamiasz jej kod

⚠️Ważne

Taka funkcja działa tylko w bieżącej sesji PowerShella.
Jeśli zamkniesz okno, funkcja zniknie i trzeba będzie ją wczytać ponownie.

Funkcja z parametrem

Do tej pory nasza funkcja zawsze zwracała ten sam wynik, a w zasadzie to, co wpisałeś jako kod. Jednak w praktyce często zachodzi potrzeba działania na różnych danych i właśnie w tym pomogą nam parametry.

Podstawowa składnia funkcji z parametrami może wyglądać następująco:

function Nazwa-Funkcji {
    param (
        # Deklaracja parametrów (opcjonalnie)
        [string]$Parametr1,
        [int]$Parametr2
    )

    # Treść funkcji
    Write-Host "Wykonuję zadanie z parametrami: $Parametr1 i $Parametr2"
}

⚠️Ważne

Parametr to sposób przekazania informacji do funkcji w momencie jej wywołania.

Jako przykład wykorzystamy naszą pierwszą funkcję, ale rozszerzymy ją o parametr Imie:

function Show-Greeting {
    param(
        [string]$Imie
    )

    "Hello, $Imie!"
}

Jak to działa?

• Blok param() umieszczamy zaraz po otwarciu nawiasu klamrowego {
• Wewnątrz definiujemy zmienne (parametry), które użytkownik może przekazać do funkcji
• W tym przykładzie mamy jeden parametr $Imie typu [string]

Ponownie wklej funkcję do konsoli w celu przetestowania, następnie ją wywołaj:

PS C:\Users\Admin> Show-Greeting -Imie "Adam"
Hello, Adam!

A teraz z inną wartością:

PS C:\Users\Admin> Show-Greeting -Imie Anna
Hello, Anna!

Jak widzisz, sama funkcja się nie zmienia, ale wynik jej działania zależy od przekazanego parametru.

Kiedy warto używać funkcji?

• Gdy masz powtarzający się fragment kodu, którego nie chcesz kopiować wiele razy
• Gdy chcesz nadać fragmentowi logiki własną, czytelną nazwę
• Gdy chcesz uprościć główny skrypt, przenosząc złożone kroki do osobnych bloków kodu

Praktyczny przykład: sprawdzanie wolnego miejsca

W tym miejscu czas na mały, ale za to całkiem praktyczny przykład funkcji, która sprawdzi ilość wolnego miejsca na dysku.

function Get-FreeSpace {
    param(
        [string]$DriveLetter
    )

    $dysk = Get-PSDrive -Name $DriveLetter -ErrorAction SilentlyContinue
    Write-Output "Wolne miejsce na dysku $($dysk.Name) to $([math]::Round($dysk.Free/1GB,2)) GB."
}

Funkcję wczytujemy do pamięci PowerShella i teraz możemy z niej skorzystać:

PS C:\Users\Admin> Get-FreeSpace C
Wolne miejsce na dysku C to 61.36 GB.

Jak to działa?

• Na początek deklaracja funkcji Get-FreeSpace z parametrem $DriveLetter
• Za pomocą Get-PSDrive -Name $DriveLetter pobieramy dane o konkretnym dysku
• Wyświetlamy wynik z wykorzystaniem Write-Output i łączymy literę dysku oraz wolne miejsce w GB (przeliczając i zaokrąglając z wykorzystaniem natywnych metod .NET – o tym kiedyś opowiem nieco więcej)
• Jeśli dysk nie istnieje, nie wyświetli błędu dzięki -ErrorAction SilentlyContinue

Podsumowanie

Funkcje to fundament nowoczesnego PowerShella. Sprawiają, że skrypty stają się modularne, czytelne i elastyczne, co bezpośrednio przekłada się na czystszy kod i łatwość utrzymania. Ostatecznie, tworzenie własnych funkcji to najszybsza droga do większej efektywności i znaczącego skrócenia czasu poświęcanego na rutynowe zadania

Praca domowa

Spróbuj przekształcić omówione funkcje i dodaj więcej elementów np. nazwisko, rolę czy funkcję użytkownika w powitaniu. Baw się i eksperymentuj to najszybsza droga do nauki.

---

To wszystko na dziś!

Jeśli masz ciekawe spostrzeżenia lub doświadczenia w tym temacie – koniecznie podziel się nimi w komentarzach.
A jeśli moje materiały są dla Ciebie pomocne, możesz postawić mi wirtualną kawę.

Dzięki za wsparcie!

Adam Pietrzak

Trener IT | Autor szkoleń | Entuzjasta PowerShella

Administrator systemów i sieci wsparcia działań wojskowych z ponad 10-letnim doświadczeniem. Praktyk w dziedzinie bezpieczeństwa systemu Windows, automatyzacji zadań (PowerShell) oraz rozwiązań chmurowych. Trener i twórca materiałów edukacyjnych (szkolenia, warsztaty, artykuły, podręczniki). Pasjonat dzielenia się wiedzą i wspierania początkujących administratorów IT. Prywatnie – amator aktywnego wypoczynku i rodzinnych podróży.

---