Funkce prostředí PowerShell

V tomto díle seriálu Naučte se PowerShell se budeme zabývat funkcemi prostředí PowerShell. V minulém díle jsme se zabývali skripty prostředí PowerShell, ve kterých jsme začali vytvářet řešení a řešit problémy pomocí prostředí PowerShell. Skripty prostředí PowerShell jsou skvělé a mnoho lidí stráví v této fázi učení prostředí PowerShell poměrně dost času. Skripty umožňují udržet věci poměrně jednoduché a mohou vám pomoci rychle automatizovat úlohy. Až se zlepšíte a začnete psát více skriptů PowerShell, budete se muset zaměřit na vytváření funkcí PowerShell!

Video

Pokud dáváte přednost formátu videa před psanou dokumentací, probírám toto téma v následujícím videu TechThoughts:

Kdy byste měli psát funkci prostředí PowerShell

Skript prostředí PowerShell je nakonec soubor kódu, který provádí určitou úlohu. To také dělá funkce prostředí PowerShell! Proč byste se tedy měli rozhodnout napsat funkci oproti skriptu? Níže se ponoříme do několika důvodů. Obecně však platí, že skript je něco pro vás. Až budete chtít začít sdílet svůj kód nebo do něj zapojit kolegy z týmu, budete chtít začít využívat některé z možností, které poskytují funkce. Neexistuje žádná pevná hranice. Pro rychlou úlohu, která se na vaší pracovní stanici spustí jednorázově, může mít skript smysl. Pokud píšete nějaký PowerShell, který by mohli používat i ostatní nebo který byste mohli použít vícekrát, pravděpodobně lépe poslouží funkce.

• Jednoúčelová – funkce se obvykle používá k provedení úzké úlohy a „dělá jednu věc, a to skvěle“. Díky tomu jsou funkce vysoce opakovaně použitelné. Napíšete-li například funkci pro protokolování, můžete pak tuto funkci pro protokolování v prostředí PowerShell použít s jinými funkcemi nebo skripty.
• Nápověda – funkce podporují komentáře založené na nápovědě. Uživatelé tak mohou například zadat příkaz Get-Help a zjistit, jak funkci použít.
• Parametry – podpora jednoduchých i pokročilých deklarací a ovládání parametrů umožňuje, aby vaše funkce byla dynamická a přijímala různé formy uživatelských vstupů.
• Testovatelné – funkce lze testovat a zesměšňovat, což výrazně zlepšuje kvalitu kódu.

Anatomie funkce PowerShell

Zde je uvedeno základní uspořádání a pořadí funkce PowerShell. Níže se ponoříme do každé z těchto částí a podrobně je prozkoumáme.

# 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 { }}

Nápověda funkce

Pokud na začátek funkce uvedete nápovědu, zobrazí se při spuštění funkce Get-Help proti vaší funkci. To je mocná schopnost, když ostatní zkoumají váš kód. Pokud věnujete čas vyplnění dobrého Synopse a Popisu v kombinaci se solidními příklady, pomůže to ostatním pochopit, k čemu vaše funkce slouží a jak ji používat.

Všechna pole nápovědy jsou volitelná a můžete je přidat nebo odebrat podle svých představ. Doporučuji zahrnout minimálně níže uvedená pole.

<#.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

Když napíšete skvělou funkci a dáte jí název jako Get-AllFileInformation, bude vypadat a chovat se jako cmdlet. Je však důležité rozlišit, že funkce prostředí PowerShell není cmdlet. Cmdlet je napsán a zkompilován v jazyce C# a vaše funkce prostředí PowerShell je napsána v prostředí PowerShell.

CmdletBinding je atribut funkcí, který umožňuje možnosti, díky nimž fungují více jako zkompilované cmdlety. Přidáním tohoto příznaku na začátek funkce získáte spoustu dalších schopností, například:

• Write-Verbose – umožníte uživatelům použít přepínač -Verbose, aby viděli, co vaše funkce dělá, zatímco to dělá.
• ShouldProcess – pokud vaše funkce provede změnu v systému, která je vysoce riziková, můžete chtít, aby uživatel akci potvrdil.
• PositionalBinding – umožňuje spuštění vaší funkce, aniž byste museli explicitně uvádět názvy jednotlivých parametrů. Hodnoty lze odvodit podle pořadí, v jakém jsou vaší funkci poskytnuty

parametry

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

Parametry slouží k tomu, aby uživateli poskytly způsob dynamické interakce s vaší funkcí. Můžete přijímat různé formy vstupu a provádět nejrůznější kontroly a validace, abyste se ujistili, že dostáváte správný druh informací.

Můžete zůstat velmi základní a deklarovat pouze názvy svých parametrů. Případně můžete být velmi konkrétní v tom, co je od vašich parametrů vyžadováno:

• Zda je parametr povinný
• Pozice parametru (pořadí)
• Typ parametru (string/int/bool/atd.)
• Nastavení výchozích hodnot
• Ověření vstupu
• Sady parametrů
• Mnoho dalšího

Tento příspěvek nemůže pokrýt všechny možné konfigurace parametrů. I po letech psaní v prostředí PowerShell je pro mě obtížné zapamatovat si všechna nastavení parametrů a syntaxi. Vězte, že deklarace parametrů jsou způsobem, jak přijímat vstupy do funkce. Můžete jim poskytnout mnoho detailů a ovládacích prvků, nebo je ponechat jednoduché, v závislosti na vašich potřebách. Zakládejte si odkazy na parametry na konci tohoto příspěvku. I dnes je často navštěvuji!

Begin Process End

Tyto tři klíčová slova jsou fáze, které můžete deklarovat v rámci své funkce.

• Begin inicializuje některé kroky na začátku
• Process zpracuje každý přijatý objekt
• End může provést vyčištění.

To je užitečné zejména v případě, že chcete, aby vaše funkce podporovala zpracování vstupů z pipeline.

Teoreticky to může být obtížně uchopitelné, takže zde je příklad, který demonstruje její použití.

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'

Při spuštění výše uvedeného kódu si všimněte, že Begin se spustí jednou, stejně jako End. Process se spouští pro každou položku, která je do něj předána, a Process má přístup k aktuálnímu objektu v pipeline.

Logika funkce

Logika obsažená uvnitř funkce prostředí PowerShell se neliší od logiky skriptu. Zde se zapisuje základní logika, která provádí úlohu, k níž je funkce určena. Touto problematikou jsme se zabývali v dílech 1-10 tohoto kurzu. Celý živý příklad si můžete prohlédnout také v epizodě Skripty prostředí PowerShell.

Funkce vrací

Ne všechny funkce po spuštění něco vracejí. Pokud vaše funkce bude něco vracet, můžete volitelně použít return. Mějte na paměti, že při použití return se všechny další akce ve funkci zastaví a funkce skončí.

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

V uvedeném příkladu obsahuje tato jednoduchá funkce dva parametry typu integer. Logika funkce sečte obě čísla a vrátí uživateli celé číslo.

Vaše první funkce PowerShell

Podívejte se na níže uvedenou funkci PowerShell. Všimněte si, že rozložení se drží toho, co jsme již dříve probrali. Všimněte si také, že část nápovědy poskytuje velké množství podrobností o účelu a použití funkce.

<#.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

Jelikož je vlastní logika této funkce poměrně jednoduchá, může být lákavé ponechat ji jako skript. Všimněte si však, že dělá jednu konkrétní věc a dělá ji dobře. Nyní byste mohli tuto funkci začlenit do jiné pokročilé logiky, místo abyste museli odkazovat nebo importovat skript. Ostatní uživatelé ve vašem prostředí by také mohli začít tuto funkci zapojovat, jakmile se s ní seznámí.

Rozsah funkce

Stejně jako většina jazyků má PowerShell pravidla pro rozsah proměnných. Pokud se proměnná nachází uvnitř funkce, nebudete již moci „vidět“ její hodnotu. Zde je příklad tohoto chování:

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

Funkce se chová podle očekávání a správně vynásobí číslo dvěma. V konzoli se však zkuste podívat, jaká je hodnota $total. Nebudete toho schopni. Je to proto, že hodnota $total je omezena na funkci, a ne na vaši aktivní relaci konzoly.

To může být pro lidi, kteří s prostředím PowerShell teprve začínají, matoucí a může to ztížit psaní funkcí. Existuje několik strategií, jak se s tím vypořádat:

Většinu logiky můžete psát ve formátu skriptu a testovat proměnné za pochodu. Jakmile si budete jisti, že logika funguje tak, jak má, můžete ji zabalit do funkce.

Případně můžete použít přepínače Write-Host, Write-Output nebo ještě lépe Write-Debug, abyste viděli, co se děje s proměnnými uvnitř funkce!

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

Všimněte si, že pomocí přepínače debug získáme přístup k hodnotě uvnitř $total, abychom se ujistili, že naše logika dělá to, co zamýšlíme.

Závěrečný příklad

Zde je větší závěrečný příklad dvou funkcí prostředí PowerShell, které vám umožní surfovat na populární webové stránce reddit pomocí prostředí PowerShell!

Na níže uvedeném odkazu GitHub gist získáte přístup ke kódu a načtete jej do své konzole.

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

Při zkoumání těchto funkcí se pokuste odpovědět na následující otázky:

• Která z těchto dvou funkcí je primární?
• Jsou to standardní nebo pokročilé funkce?
• Která funkce bude podporovat vstup do potrubí?

Additional Reading

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

Series Navigation << PowerShell ScriptsManage Cloud with PowerShell >>