Adam Automator

při vytváření funkcí PowerShell Je důležité ověřovat vstup do parametrů. Ověření parametrů umožňuje omezit to, co je předáno funkcím. V tomto článku se dozvíte, jak zachytit problémy dříve, než se stanou jedním z atributů ověření PowerShell ValidateScript.

pomocí ověření parametrů nejen zajistíte, že problémy nevzniknou po spuštění funkce, ale také podpoříte čistší kód, protože validační logika není umístěna v těle funkce.

v Powershell je k dispozici několik pokročilých atributů ověření parametrů. V tomto článku se však dozvíte o jedné z nejflexibilnějších validací parametrů, validaci PowerShell ValidateScript.

uvidíte, jak to funguje, a také uvidíte příklady, jak jej používat.

obsah

ověření parametrů (analogie)

ověření parametrů

obědval jsem a najednou jsem měl chuť na limonádu. Došel jsem k automatu na limonádu, vytáhl z kapsy bankovku 100 a vložil ji do slotu na účet. Stroj to okamžitě vyplivne.

pak jsem si všiml, že těsně nad slotem se říká, že přijímá pouze účty ₱20 a ₱50. Nakonec jsem si nedal limonádu, protože jsem měl u sebe jen tu 100Kč.

a jak příběh souvisí s ověřením parametrů PowerShell? Pojďme to rozebrat.

  • soda stroj slouží jako funkce
  • účet je parametr
  • účty ₱50 a 20 20 jsou platné hodnoty parametrů
  • ₱100 byl odmítnut, protože se jedná o nesprávnou hodnotu parametru
  • v důsledku toho stroj nezpracoval můj požadavek kvůli nesprávnému vstupu. Proto pro mě žádná soda. ….a taky jsem měl žízeň!

výše uvedený scénář soda machine je pouze jednou analogií k popisu konceptu validace parametrů.

logický tok validace parametrů

koncept validace parametrů sleduje hrubý pracovní postup. Obrázek níže ukazuje přehled o tom, jak ověření parametrů funguje.

Tok ověření parametrů PowerShell
  1. funkce se provádí v PowerShell voláním jejího názvu a poskytnutím hodnot parametrů
  2. PowerShell vyhodnotí poskytnuté hodnoty.
  3. pokud je výsledek ověření pravdivý, PowerShell umožní funkci pokračovat ve svém procesu před ukončením.
  4. pokud je výsledek ověření nepravdivý, PowerShell zobrazí chybu a funkce se ukončí.

návod požadavky

více než jen mluvit o ověření parametrů funkce PowerShell, zbytek tohoto článku bude mít příklady, které můžete zkopírovat a vyzkoušet sami. Chcete-li následovat, budete potřebovat pár věcí, které budete následovat.

  • počítač se systémem Windows 10 s některou z níže uvedených verzí PowerShell:
  • Windows PowerShell 5.1
  • PowerShell Core 6.2
  • PowerShell Core 7 (nejnovější verze tohoto psaní je náhled 4)
  • editor skriptů podle vašeho výběru. Například Notepad++, PowerShell ISE nebo Visual Studio Code.

pochopení atributu Validatescript Validation

ValidateScript je jedním z atributů validace parametrů dostupných pro použití v PowerShell zavedeném v PowerShell 3.0. Může být přidán do bloku definice parametrů funkce nebo může být také použit přímo v konzole PowerShell.

ValidateScript se používá k ověření hodnoty zadaného parametru. Pokud je výsledek ověření $true, skript bude pokračovat v běhu. Na druhou stranu, pokud je výsledek $false, funkce vyvolá chybu ukončení.

pojďme se ponořit a uvidíme, jak to funguje.

použití validatescript ve funkci

nejběžnější použití atributu ValidateScript je připojeno k parametru funkce. V této části vytvoříte fiktivní funkci a použijete validatescript validation parameter.

fiktivní funkce provede následující akce:

  1. přijměte vstup pro částku.
  2. ověřte, zda se zadaná částka rovná přijatým hodnotám.
  3. spusťte proces, pokud validace prošla.
  4. zobrazí chybu, pokud Ověření selhalo.

v další části se dozvíte, jak tuto funkci sestavit krok za krokem. Spusťte editor skriptů a začněte kódovat!

Vytvořte funkci

nejprve vytvořte funkci a pojmenujte ji. Může to být libovolné jméno, které si vyberete. Nejlepší praxí je dodržovat konvenci pojmenování slovesa a substantiva, aby byla vaše funkce popisná. Pro tento příklad použijte název Get-Soda.

Function Get-Soda { param ()}

do bloku param() vložte název parametru, který budete používat, což je Bill.

Function Get-Soda { param ( $Bill )}

v tomto okamžiku funkce zatím nevykonává nic jiného, než přijmout jakoukoli hodnotu pro parametr Bill.

ujistěte se, že jste zkopírovali funkci Get-Soda do konzoly PowerShell. Jakmile je funkce importována do relace PowerShell, otestujte ji spuštěním příkazu: Get-Soda -Bill 100.

při spuštění funkce Get-Soda si všimnete, že není vyvolána žádná chyba a nic nedělá. To se v tuto chvíli očekává.

přidání ověření parametrů

možná nechcete povolit předání všech hodnot parametru Bill. Při použití analogie vysvětlené v horní části tohoto článku by funkce neměla umožňovat ₱100 účtů. To by mělo umožnit pouze ₱50 a ₱20 účty.

přidejte ověření parametru ValidateScript vložením před parametr Bill. Vaše funkce by měla vypadat jako níže uvedený kód.

Function Get-Soda { param ( $Bill )}

do bloku vložte ověřovací kód {$_ -eq 20}. Tento ověřovací kód kontroluje, zda je hodnota poskytnutá parametru vyúčtování rovna 20. Níže uvedený úryvek je, jak by měl kód vypadat.

Poznámka: $_ představuje hodnotu aktuálního parametru v rozsahu. V tomto příkladu je hodnota $_ hodnota parametru Bill.

Function Get-Soda { param ( $Bill )}

Nyní spusťte tuto funkci znovu a potvrďte, že ověření parametru funguje spuštěním:

PS51> Get-Soda -Bill 20PS51> Get-Soda -Bill 30

níže vidíte, že když je 20 předáno jako hodnota, nic se nestane, ale když je předáno něco jiného než 20, vyvolá chybu.

chyba

pokud funkce Get-Soda nevyhodí chybu, znamená to, že funkce byla úspěšně provedena. Chcete-li to prokázat, přidejte do funkce následující kód a jednoduše vraťte zprávu do konzoly.

Write-Host "$Bill is an accepted value. Please select your soda."

funkce Get-Soda pak bude vypadat níže:

nyní předejte přijatou hodnotu jako 20 parametru Bill. Měli byste vidět výsledek níže.

výstup Get-Soda-bill 20

zobrazení smysluplnějších chybových zpráv

jsem si jistý, že jste si všimli, že chybová zpráva vrácená, když hodnota parametru neprojde validací, není příliš intuitivní a ošklivá.

chyba ověření je nejasná

bohužel, s tím, jak chyba vypadá, nemůžete nic dělat. Dokud nebude uvolněna funkce, která umožňuje formátování chyb ověření (doufejme), zůstanete s ní.

ale je možné jej trochu vylepšit a dát větší význam chybám, které mohou být přínosem pro vaše uživatele. Uvidíte příklad, jak to udělat dále.

přidání vlastní chyby ověření pomocí Windows PowerShell (5.1)

rozšíření na funkci Get-Soda je možné hodit konkrétní chybovou zprávu, pokud hodnota nesplňuje ověření. Chcete-li to provést, můžete do bloku ValidateScript přidat konstrukci if/then.

Vytvořte jednoduchý konstrukt if / then jako v následujícím příkladu. V tomto příkladu, pokud hodnota parametru Bill není rovna 20, vrátí chybovou zprávu podle vašeho výběru (X is invalid. Valid value is 20 only.).

níže vidíte příklad toho, jak to vypadá:

Snímek obrazovky níže zobrazuje vlastní chybovou zprávu v akci. Chyba stále vypadá ošklivě, ale tentokrát je zpráva jasná a srozumitelná.

ValidateScript s vlastní chybovou zprávou (PowerShell 5.1)

přidání vlastních chyb ověření pomocí PowerShell Core (6+)

počínaje PowerShell Core 6 je již integrována možnost přidávat vlastní chybové zprávy do validatescript validation parameter validatescript. Říkejme tomu ErrorMessage technika.

v níže uvedeném modifikovaném funkčním kódu Get-Soda blok nyní obsahuje vlastnost ErrorMessage, kterou lze použít na místě throw. Nyní místo použití proměnné $_ můžete použít {0}, která bude představovat předanou hodnotu parametru.

Snímek obrazovky níže ukazuje, že očekávaný výstup je přesně stejný jako při použití techniky if-else a throw.

ValidateScript s vlastní chybovou zprávou (PowerShell Core 7 Náhled 4)

PowerShell ValidateScript příklady použití

toto jsou některé scénáře použití v reálném světě, pro které lze použít ValidateScript. Zkontrolujte a otestujte tyto příklady a pokuste se vylepšit chybovou zprávu sami pomocí technik, které jste se naučili v předchozí části.

ověření parametru data

tento úryvek je funkce, která přijímá datum zahájení a ukončení. Provádí ověření, že zadaná data nejsou v budoucnu a nejsou starší než 90 dnů.

Otestujte funkci pomocí těchto příkazů. Můžete zadat vlastní hodnoty startDate a endDate

tento ukázkový výstup níže je při zadávání platných hodnot data.

Search-Log výsledek s platnými hodnotami parametrů data

nyní jej vyzkoušejte znovu s startDate, který je starší než 90 dní. Poté potvrďte, že se zobrazí chybová zpráva.

ověření parametrů procesu Windows

Tento další úryvek je funkce, která přijímá název procesu. Potvrzuje, že proces běží v paměti, pak zabije všechny spuštěné instance tohoto procesu nebo ukončení v závislosti na výsledku ověření.

otestujte jej pomocí tohoto příkazu: Kill-Process -Name <process name>

ukázkový výstup níže předpokládá, že testujete pomocí procesu s názvem poznámkový blok.

  • první příkaz běžel úspěšně, protože zjistil, že proces poznámkového bloku běží, a pokračoval v jeho zabití.
  • druhý příkaz selhal, protože poznámkový blok již není spuštěn a funkce skončila vlastní chybovou zprávou, kterou jste vytvořili.
chyba ověření parametrů

ověření parametrů jinou hodnotou parametru

Nyní byste měli mít představu o hodnotě použití ValidateScript ve vašich funkcích. Bu existuje jedno omezení, které stojí za zmínku. Rozsah ValidateScript je pouze v rámci použitého parametru. To znamená, že jeden parametr nemůže použít hodnotu jiných parametrů.

jako řešení lze provést kontrolu hodnoty mezi parametry přístupem k automatické proměnné $PSBoundParameters.

možná máte funkci nazvanou Send-Spam. Tato funkce má tři parametry:

  1. From – e-mailová adresa odesílatele. (ego. ). Není povinné.
  2. To – e-mailová adresa příjemce. (ego. ). Není povinné.
  3. SendEmail – parametr přepínače, který nevyžaduje hodnotu. Pokud se však použije, budou vyžadovány hodnoty parametrů From a To.

pokud je použit přepínač SendEmail, spustí se ověřovací kód, který potvrdí, že jsou použity parametry From a To. Poté vrátí hodnotu True. Na druhou stranu, pokud se From a To nepoužívají, funkce vyvolá chybu a ukončí.

zkopírujte a vložte níže uvedený kód do relace PowerShell.

příkaz uvedený níže bude mít za následek úspěšné ověření. Protože parametry From a To byly použity spolu s přepínačem SendEmail.

PS51> Send-Spam -From -To -SendEmail
výstup ze Send-Spam

nyní jej Otestujte bez použití parametru From nebo To. To by mělo mít za následek chybu, protože ověřovací skript selže. Viz příklad výsledek níže.

spuštění Send-Spam bez parametru To

použití ValidateScript v konzole

ačkoli nejběžnější použití atributu ValidateScript se používá k ověření funkčních parametrů, lze jej také použít přímo z konzoly PowerShell. ValidateScript je užitečný pro testování ověřovacího kódu ještě před jeho začleněním do skriptu nebo funkce.

níže jsou uvedeny některé příklady použití ValidateScript mimo funkci.

validace celočíselné hodnoty

tento příklad níže potvrzuje, že daná celočíselná hodnota je větší než pět.

$i=4

po spuštění výše uvedeného kódu se očekávaný výsledek nezdaří, protože daná hodnota je 4, což je méně než 5. Níže uvedený příklad obrazovky je to, co byste očekávali.

ověření se nezdařilo

ověření hodnoty data

následující příklad níže ukazuje, jak ověřit, že dané datum je novější nebo rovno aktuálnímu datu.

$date = (Get-Date)$date = (Get-Date).AddHours(-1)

po spuštění prvního řádku kódu ve výše uvedeném úryvku je očekávaný výsledek předán (True) , protože zadaná hodnota DateTime je stejná nebo o několik sekund větší.

druhý řádek kódu vytvoří neúspěšný výsledek, protože hodnota DateTime je o hodinu menší než aktuální čas. Ukázkový výstup najdete na obrázku níže.

selhání ověření parametru data

shrnutí

v tomto článku jste se dozvěděli, co je validace parametrů a jak používat atribut validatescript parameter validation.

také jste se naučili, jak rozšířit jeho schopnost zobrazit popisnější chybovou zprávu. Při sledování příkladů, zažili jste výsledky úspěšné i neúspěšné validace.

nyní byste měli pochopit omezení ValidateScript, pokud jde o odkazování mezi parametry, a jak můžete toto omezení vyřešit pomocí automatické proměnné $PSBoundParameters.

doufám, že jste se v tomto článku naučili dost, že můžete použít ve své cestě k vytváření nástrojů PowerShell!

další čtení

  • Powershell funkce Úvod
  • porozumění a budování PowerShell modulů
  • validatescript validation atribut
  • o Throw

Napsat komentář

Vaše e-mailová adresa nebude zveřejněna.