PowerShell függvények

A PowerShell tanulása sorozat ezen epizódjában a PowerShell függvényeket vizsgáljuk. Az előző epizódban a PowerShell szkriptekkel foglalkoztunk, ahol elkezdtünk megoldásokat létrehozni és problémákat megoldani a PowerShell segítségével. A PowerShell szkriptek nagyszerűek, és sokan elég sok időt töltenek ebben a szakaszban a PowerShell tanulása során. A szkriptek lehetővé teszik, hogy a dolgok meglehetősen egyszerűek legyenek, és segíthetnek a feladatok gyors automatizálásában. Ahogy egyre jobb leszel, és elkezdesz több PowerShellt írni, úgy kell majd PowerShell függvények létrehozására törekedned!

Videó

Ha az írott dokumentáció helyett inkább a videó formátumot kedveli, a következő TechThoughts videóban tárgyalom ezt a témát:

Mikor érdemes PowerShell függvényt írni

A nap végén egy PowerShell script egy kódkészlet, amely végrehajt egy feladatot. Ezt teszi egy PowerShell függvény is! Szóval, miért érdemes függvényt írni egy szkript helyett? Az alábbiakban elmerülünk néhány okban. Általánosságban véve azonban egy szkript valami olyasmi, ami neked szól. Amikor el akarod kezdeni megosztani a kódodat, vagy a csapattársaidat is be akarod vonni, akkor a függvények által biztosított képességek egy részét is be akarod vonni. Nincs határozott határvonal. Egy gyors, a munkaállomásodon egyszer lefutó feladathoz lehet értelme egy szkriptnek. Ha olyan PowerShellt írsz, amelyet mások is használhatnak, vagy amelyet többször is használhatsz, akkor egy függvény valószínűleg jobb szolgálatot tesz.

• Egyetlen célú – egy függvényt jellemzően egy szűk feladat elvégzésére használnak, és “egy dolgot csinálnak, méghozzá nagyszerűen”. Ez teszi a függvényeket nagymértékben újrafelhasználhatóvá. Ha például írsz egy naplózási függvényt, akkor ezt a PowerShell naplózási függvényt más függvényekkel vagy szkriptekkel is használhatod.
• Súgó – a függvények támogatják a súgó alapú megjegyzéseket. Ez lehetővé teszi a felhasználók számára, hogy olyan dolgokat tegyenek, mint például a Get-Help beírása, és kitalálják, hogyan használják a függvényt.
• Paraméterek – az egyszerű és fejlett paraméterek deklarációjának és vezérlésének támogatása lehetővé teszi, hogy a függvény dinamikus legyen, és különböző felhasználói bemeneti formákat fogadjon el.
• Tesztelhető – a függvények tesztelhetők és mockolhatók, ami jelentősen javítja a kód minőségét.

Egy PowerShell függvény anatómiája

Itt van egy PowerShell függvény alapvető elrendezése és sorrendje. Az alábbiakban minden egyes szakaszba belemerülünk, és részletesen megvizsgáljuk őket.

# function help - (optional but strongly encouraged)# function name# CmdletBinding - (optional)# parameters - (optional)# function logic (optional Begin / Process / End)# return - (optional)function Verb-Noun { param ( ) begin { } process { } end { }}

A függvény súgója

Ha a függvénye tetején súgó szerepel, akkor a Get-Help futtatásakor a függvénye ellenében megjelenik. Ez egy hatékony képesség, amikor mások vizsgálják a kódodat. Ha időt szánsz egy jó szinopszis és leírás kidolgozására, szilárd példákkal kombinálva, az segít másoknak megérteni, hogy mire való a függvényed, és hogyan kell használni.

Minden súgó mező opcionális, és tetszés szerint hozzáadhatod vagy eltávolíthatod őket. Javaslom, hogy legalább az alábbi mezőket legalább tartalmazza.

<#.SYNOPSIS Short description.DESCRIPTION Long description.EXAMPLE C:\PS> Example of how to use this cmdlet.EXAMPLE C:\PS> Another example of how to use this cmdlet.PARAMETER InputObject Specifies the object to be processed. You can also pipe the objects to this command..OUTPUTS Output from this cmdlet (if any).NOTES General notes.COMPONENT The component this cmdlet belongs to#>

CmdletBinding

Ha írsz egy nagyszerű függvényt, és olyan nevet adsz neki, mint a Get-AllFileInformation, akkor úgy néz ki és úgy fog viselkedni, mint egy cmdlet. De fontos különbség, hogy egy PowerShell függvény nem cmdlet. A cmdleteket C# nyelven írják és fordítják le, a PowerShell-funkciót pedig PowerShell nyelven írják.

ACmdletBinding a függvények olyan attribútuma, amely olyan képességeket tesz lehetővé, amelyek révén a függvények inkább úgy működnek, mint a lefordított cmdletek. Ha ezt hozzáadja a függvénye tetejéhez, a függvénye számos további képességet kap, például:

• Write-Verbose – lehetővé teszi a felhasználók számára, hogy a -Verbose kapcsoló használatával lássák, mit csinál a függvénye, miközben csinálja.
• ShouldProcess – ha a függvénye olyan változtatást hajt végre egy rendszerben, amely nagy kockázatot jelent, akkor azt szeretné, ha a felhasználó megerősítené a műveletet.
• PositionalBinding – lehetővé teszi a függvényed futtatását az egyes paraméterek nevének explicit megadása nélkül. Az értékek kikövetkeztethetők a függvényednek megadott sorrendjükből

paraméterek

param ( $City, $Units = 'USCS', $Language = 'en', $Short)

A paraméterek arra szolgálnak, hogy a felhasználónak módot biztosítsanak a függvényeddel való dinamikus interakcióra. A bemenet különböző formáit fogadhatja be, és sokféle ellenőrzést és érvényesítést végezhet, hogy biztosítsa, hogy a megfelelő információt kapja.

Maradhat nagyon egyszerű, és csak a paraméterek nevét deklarálhatja. Alternatív megoldásként nagyon pontosan meghatározhatod, hogy mire van szükség a paramétereidhez:

• A paraméter kötelező-e
• A paraméter pozíciója (a sorrend)
• A paraméter típusa (string/int/bool/etc)
• Az alapértelmezett értékek beállítása
• A bemeneti érvényesítés
• Paraméterkészletek
• Sokkal több

Ez a bejegyzés nem tud minden lehetséges paraméterkonfigurációval foglalkozni. Még több évnyi PowerShell-írás után is nehéz megjegyezni az összes paraméterbeállítást és szintaxist. Tudd, hogy a paraméterdeklarációkkal a függvényedbe történő bemenetet veszed fel. Sok részletet és vezérlést adhatsz nekik, vagy az igényeidtől függően egyszerűen tarthatod őket. Tegye könyvjelzőbe a paraméterekre mutató linkeket a bejegyzés alján. Még ma is gyakran látogatom őket!

Begin Process End

Ez a három kulcsszó olyan fázisok, amelyeket a függvényeden belül deklarálhatsz.

• A Begin inicializál néhány lépést az elején
• Process feldolgozza az egyes objektumokat a beérkezéskor
• End elvégezheti a tisztítást.

Ez különösen akkor hasznos, ha azt szeretnénk, hogy a függvényünk támogassa a csővezetékből érkező bemenetek feldolgozását.

Ez elméletben nehezen érthető, ezért íme egy példa, amely bemutatja a használatát.

function Get-PipelineBeginEnd { param ( $SomeInput ) begin { "Begin: The input is $SomeInput" } process { "The value is: $_" } end { "End: The input is $SomeInput" }}#Get-PipelineBeginEnd1, 2, 3 | Get-PipelineBeginEnd -SomeInput 'Test'

A fenti kód futtatásakor vegyük észre, hogy a Begin egyszer fut le, ahogy az End is. A Process minden egyes átadott elemre lefut, és a Process hozzáfér a csővezeték aktuális objektumához.

Funkció logikája

A PowerShell-funkcióban található logika nem különbözik egy szkript logikájától. Itt írja meg az alapvető logikát, amely végrehajtja azt a feladatot, amelyre a függvényt szánja. Ezt a tanfolyam 1-10. epizódjában tárgyaltuk. Egy teljes élő példát is láthat a PowerShell szkriptek című epizódban.

Funkció visszatérése

Nem minden függvény ad vissza valamit futtatáskor. Ha a függvénye vissza fog adni valamit, akkor opcionálisan használhatja a return-t. Ne feledje, hogy a return használatakor a függvényben minden további művelet leáll, és a függvény véget ér.

function Get-Total { param ( $Number1, $Number2 ) $total = $Number1 + $Number2 return $total}Get-Total -Number1 2 -Number2 2

A fenti példában ez az egyszerű függvény két egész típusú paramétert tartalmaz. A függvény logikája összeadja a két számot, és az egész számot adja vissza a felhasználónak.

Az első PowerShell függvényed

Nézd meg az alábbi PowerShell függvényt. Vegye figyelembe, hogy az elrendezés tartja magát a korábban tárgyaltakhoz. Figyeljük meg azt is, hogy a súgó rész nagyon részletesen ismerteti a függvény célját és használatát.

<#.SYNOPSIS Returns your public IP address..DESCRIPTION Queries the ipify Public IP Address API and returns your public IP..EXAMPLE Get-PublicIP Returns the public IP..OUTPUTS System.String.NOTES https://github.com/rdegges/ipify-api#>function Get-PublicIP { $uri = 'https://api.ipify.org' try { $invokeRestMethodSplat = @{ Uri = $uri ErrorAction = 'Stop' } $publicIP = Invoke-RestMethod @invokeRestMethodSplat } catch { Write-Error $_ } return $publicIP}#Get-PublicIP

Mivel ennek a függvénynek a tényleges logikája meglehetősen egyszerű, csábító lehet, hogy szkriptként hagyjuk. Vegyük azonban figyelembe, hogy ez egy konkrét dolgot csinál, méghozzá jól. Ezt a függvényt most beépítheti más fejlett logikába, ahelyett, hogy egy szkriptre kellene hivatkoznia vagy importálnia. A környezetében más felhasználók is elkezdhetik használni ezt a funkciót, amint megismerkednek vele.

Funkció hatókör

A legtöbb nyelvhez hasonlóan a PowerShell is rendelkezik a változók hatókörére vonatkozó szabályokkal. Ha egy változó egy függvényen belül van, akkor már nem “láthatod” az értékét. Íme egy példa erre a viselkedésre:

function Get-NumberTimesTwo { param ( $Number ) $total = $Number * 2 return $total}#Get-NumberTimesTwoGet-NumberTimesTwo -Number 2

A függvény az elvárt módon viselkedik, és helyesen szoroz meg egy számot kettővel. A konzolban azonban próbáld megnézni, hogy mi a $total értéke. Nem fogod tudni. Ennek az az oka, hogy a $total a függvényre van korlátozva, és nem az aktív konzol-munkamenetre.

Ez zavaró lehet a PowerShellben járatlanok számára, és megnehezítheti a függvények írását. Van néhány stratégia ennek kezelésére.

A logika nagy részét írhatja szkript típusú formátumban, és menet közben tesztelheti a változókat. Ha meggyőződött arról, hogy a logika a kívánt módon működik, akkor a logikát egy függvénybe csomagolhatja.

Alternatívaként használhatja a Write-Host, Write-Output vagy még jobb esetben a Write-Debug funkciót, hogy lássa, mi történik a változókkal a függvényen belül!

function Get-NumberTimesTwo { param ( $Number ) $total = $Number * 2 Write-Debug $total return $total}#Get-NumberTimesTwoGet-NumberTimesTwo -Number 2 -Debug

Megjegyezzük, hogy a debug kapcsolóval hozzáférhetünk a $total-on belüli értékhez, hogy megbizonyosodjunk arról, hogy a logikánk a kívánt módon működik.

Záró példa

Itt egy nagyobb záró példa két PowerShell függvényből, amelyek segítségével a népszerű reddit weboldalon szörfözhetünk a PowerShell segítségével!

Látogasson el az alábbi GitHub gist linkre a kód eléréséhez és töltse be a konzoljába.

https://gist.github.com/techthoughts2/cd2b720c9b291510cbd643e6ca73e05f

A függvények felfedezése során próbáljon meg válaszolni a következő kérdésekre:

• A két függvény közül melyik az elsődleges funkció?
• Szokásos vagy speciális funkciókról van szó?
• Melyik függvény támogatja a csővezetékes bemenetet?

Additional Reading

• Functions
• Parameters
• Functions Advanced
• Functions Advanced Parameters
• PowerShell Approved Verbs
• CmdletBindingAttribute

Series Navigation << PowerShell ScriptsManage Cloud with PowerShell >>