Adam the Automator

kun luodaan PowerShell-toimintoja, parametrien syötteen validointi on tärkeää. Parametrin validoinnin avulla voit rajoittaa, mitä siirretään funktioille. Tässä artikkelissa opit nappaamaan ongelmia ennen kuin niistä tulee yhtä PowerShell ValidateScript validation-attribuutin kanssa.

käyttämällä parametrin validointia varmistat, että ongelmia ei synny, kun toiminto suoritetaan, ja edistät myös puhtaampaa koodia, koska validointilogiikka ei ole sijoitettu funktion runkoon.

Powershellissa on saatavilla useita advanced parameter validation attribuutteja. Mutta tässä artikkelissa, opit yksi joustavimmista parametrien validations, PowerShell ValidateScript validation.

näet, miten se toimii ja näet myös esimerkkejä siitä, miten sitä käytetään.

parametrin validointi (analogia)

olin lounaalla ja yhtäkkiä teki mieli limsaa. Kävelin limuautomaatille, vedin taskustani 100 setelin ja asetin sen laskuluukkuun. Kone sylkee sen ulos välittömästi.

sitten huomasin, että aivan korttipaikan yläpuolella se sanoo hyväksyvänsä vain ₱20 ja ₱50 seteliä. Päädyin ilman limsaa, koska minulla oli vain se ₱100-seteli mukanani.

ja miten tarina liittyy PowerShell-parametrin validointiin? Murretaan se.

• soodakone toimii funktiona
• lasku on parametri
• ₱50 ja ₱20 laskut ovat kelvollisia parametriarvoja
• ₱100 hylättiin, koska se on väärä parametrin arvo
• tämän seurauksena kone ei käsitellyt pyyntöäni väärän syötteen vuoksi. Siksi en saa limsaa. ….ja minullakin oli jano!

yllä oleva soda-koneskenaario on vain yksi analogia kuvaamaan parametrin validoinnin käsitettä.

parametrin Validointilogiikkavirta

parametrin validoinnin käsite noudattaa karkeaa työnkulkua. Alla olevassa kuvassa on yleiskatsaus siitä, miten parametrin validointi toimii.

1. funktio suoritetaan Powershellissa kutsumalla sen nimeä ja antamalla parametrin arvot
2. PowerShell arvioi annetut arvot.
3. jos validoinnin tulos on tosi, PowerShell sallii funktion jatkaa prosessiaan ennen poistumista.
4. jos validoinnin tulos on väärä, PowerShell näyttää virheen ja funktio päättyy.

Walkthrough Requirements

More than just talking about PowerShell function parameter validation, the rest of this article will have examples that you can copy and try on your own. Seurataksesi mukana, tarvitset muutamia asioita seurattavaksi.

• Windows 10-tietokone, jossa on jokin alla olevista PowerShell-versioista:
• Windows PowerShell 5.1
• PowerShell Core 6.2
• PowerShell Core 7 (tämän kirjoituksen uusin julkaisu on Preview 4)
• valitsemasi skriptieditori. Kuten Notepad++, PowerShell ISE tai Visual Studio Code.

ValidateScript Validation Attribute

ValidateScript on yksi parametrin validointiominaisuuksista, joita voidaan käyttää Powershellissa, joka on otettu käyttöön PowerShell 3.0: ssa. Se voidaan lisätä funktion parametrimäärityslohkon sisään tai sitä voidaan käyttää myös suoraan PowerShell-konsolissa.

Validatescriptiä käytetään antamasi parametrin arvon validointiin. Jos validointitulos on $true, skripti jatkuu. Toisaalta, jos tulos on $false, funktio heittää päättymisvirheen.

sukelletaan ja katsotaan, miten se toimii.

ValidateScript-attribuutin käyttäminen funktiossa

yleisimmin ValidateScript-attribuutin käyttö liitetään funktioparametriin. Tässä osiossa luot valetoiminnon ja käytät ValidateScript-parametrin validointia.

nukkefunktio suorittaa seuraavat toiminnot:

1. hyväksy panos summalle.
2. validoi, jos ilmoitettu määrä on yhtä suuri kuin hyväksytyt arvot.
3. suorita prosessi, jos validointi hyväksytään.
4. Näytä virhe, jos validointi epäonnistui.

tämän funktion rakentamiseen tutustutaan seuraavassa osassa vaihe vaiheelta. Fire up your script editor ja alkaa koodaus!

Rakenna funktio

ensin, Luo funktio ja anna sille nimi. Tämä voi olla mikä tahansa nimi. On parasta noudattaa verbin ja substantiivin nimeämiskäytäntöä, jotta funktiosi olisi kuvaileva. Tästä esimerkistä käytetään nimeä Get-Soda.

Function Get-Soda { param ()}

param() – lohkon sisään lisätään sen parametrin nimi, jota käytät ja joka on Bill.

Function Get-Soda { param ( $Bill )}

tässä vaiheessa funktio ei suorita vielä mitään muuta kuin hyväksyy minkä tahansa arvon Bill parametrille.

varmista, että olet kopioinut Get-Soda – toiminnon PowerShell-konsoliin. Kun funktio on tuotu PowerShell-istuntoon, testaa funktio ajamalla komento: Get-Soda -Bill 100.

kun suoritat Get-Soda funktiota, huomaat, ettei virhettä heitetä eikä se tee mitään. Sitä odotetaan tässä vaiheessa.

parametrin validoinnin lisääminen

ei ehkä halua sallia kaikkien arvojen siirtämistä Bill parametriin. Käyttämällä analogiaa selitetty yläosassa tämän artikkelin, funktio ei pitäisi sallia ₱100 laskut. Sen pitäisi sallia vain ₱50 ja ₱20 laskut.

lisätään ValidateScript-parametrin validointi lisäämällä ennen Bill – parametria. Toimintosi pitäisi näyttää alla olevalta koodilta.

Function Get-Soda { param ( $Bill )}

lohkon sisälle merkitään validointikoodi {$_ -eq 20}. Tällä varmennuskoodilla tarkistetaan, onko laskuparametrille annettu arvo 20. Alla katkelma on, miten koodin pitäisi näyttää.

Huomautus: $_ kuvaa nykyisen parametrin arvoa soveltamisalalla. Tässä esimerkissä arvo $_ on parametrin arvo Bill.

Function Get-Soda { param ( $Bill )}

suorita tämä toiminto uudelleen varmistaaksesi, että parametrin validointi toimii ajamalla:

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

alla näkyy, että kun arvo 20 ohitetaan arvona, ei tapahdu mitään, mutta kun jokin muu kuin 20 ohitetaan, se heittää virheen.

kun funktio Get-Soda ei heitä virhettä, tarkoittaa se funktio suoritettua onnistuneesti. Osoittaaksesi tämän, lisää seuraava koodi funktion sisään palauttaaksesi viestin konsolille.

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

Get-Sodafunktio näyttää tämän jälkeen samalta kuin alla:

siirtää nyt hyväksytyn arvon kuten 20 Bill parametrille. Katso tulos alta.

Merkityksellisempien virheilmoitusten Näyttäminen

olen varma, että olet jo huomannut, että virheilmoitus palasi, kun parametrin arvo ei läpäise validointia, ei ole kovin intuitiivinen ja ruma.

valitettavasti et voi tehdä mitään sille, miltä virhe näyttää. Kunnes ominaisuus, joka mahdollistaa vahvistusvirheiden muotoilun, on julkaistu (toivottavasti), olet jumissa sen kanssa.

mutta on mahdollista parantaa sitä hieman ja antaa enemmän merkitystä virheille, jotka voivat hyödyttää käyttäjiä. Näet esimerkin siitä, miten se tehdään seuraavaksi.

lisäämällä mukautetun validointivirheen Windows PowerShell (5.1)

laajennetaan Get-Soda – funktiota, on mahdollista heittää erityinen virheilmoitus, kun arvo ei täytä validointia. Voit tehdä tämän lisäämällä If / then-Konstruktion ValidateScript-lohkon sisään.

Luo yksinkertainen if / then-konstruktio kuten alla olevassa esimerkissä. Tässä esimerkissä, jos parametrin Bill arvo ei ole sama kuin 20, se palauttaa valitsemasi virhesanoman (X is invalid. Valid value is 20 only.).

voit katsoa esimerkin siitä, miltä tämä näyttää alla:

alla oleva kuvakaappaus näyttää muokatun virheilmoituksen toiminnassa. Virhe näyttää edelleen rumalta, mutta tällä kertaa viesti on selkeä ja ymmärrettävä.

lisätään mukautettuja validointivirheitä käyttäen PowerShell Core (6+)

PowerShell Core 6: sta alkaen kyky lisätä mukautettuja virhesanomia ValidateScript-parametrin validointiin on jo sisäänrakennettu. Kutsutaan tätä Virhetekniikaksi.

alla olevassa muokatussa Get-Soda funktiokoodissa lohkoon sisältyy nyt ErrorMessage ominaisuus, jota voidaan käyttää paikallaan throw. Nyt voit käyttää $_ – muuttujan sijasta {0}, joka kuvaa siirrettyä parametrin arvoa.

alla oleva kuvakaappaus osoittaa odotetun tuotoksen olevan täsmälleen sama kuin if-else-ja heittotekniikalla.

PowerShell ValidateScript käyttöesimerkkejä

nämä ovat joitakin reaalimaailman käyttötapausskenaarioita, joihin ValidateScript voidaan soveltaa. Tarkista ja testaa nämä esimerkit ja yritä sitten parantaa virheilmoitusta itse käyttämällä edellisessä osiossa oppimiasi tekniikoita.

Date parametrin validointi

tämä pätkä on funktio, joka hyväksyy alkamis-ja päättymispäivän. Se validoi, että syötetyt päivämäärät eivät ole tulevaisuudessa eivätkä ne ole vanhempia kuin 90 päivää.

testaa funktiota käyttämällä näitä komentoja. Voit määrittää omat startDate ja endDate arvot

tämä alla oleva otos on, kun validit päivämääräarvot syötetään.

nyt Testaa uudestaan, kun startDate on yli 90 päivää vanha. Vahvista sitten, että virheilmoitus näkyy.

Windowsin Prosessiparametrin validointi

tämä seuraava pätkä on funktio, joka hyväksyy prosessin nimen. Se vahvistaa, että prosessi on käynnissä muistissa, sitten tappaa kaikki käynnissä olevat esiintymät kyseisen prosessin tai exit riippuen validointituloksesta.

testaa tällä komennolla: Kill-Process -Name <process name>

alla oleva näytteen lähtö olettaa, että testaat prosessia nimeltä notepad.

• ensimmäinen komento toimi onnistuneesti, koska se havaitsi muistilehtiöprosessin olevan käynnissä ja eteni tappamaan sen.
• toinen komento epäonnistui, koska notepad ei ole enää käynnissä ja toiminto päättyi luomaasi muokattuun virheilmoitukseen.

parametrien validointi toisen parametrin arvolla

nyt sinulla pitäisi olla käsitys Validatescriptin käyttämisen arvosta toiminnoissasi. Bu on yksi rajoitus, joka on syytä mainita. Validatescriptin soveltamisala on vain käytössä olevan parametrin sisällä. Tämä tarkoittaa, että yksi parametri ei voi käyttää muiden parametrien arvoa.

kiertomuuttujana ristiintarkistus voidaan tehdä käyttämällä $PSBoundParameters automaattista muuttujaa.

ehkä sinulla on funktio nimeltä Send-Spam. Funktiolla on kolme parametria:

1. From – lähettäjän sähköpostiosoite. (esim. ). Ei pakollinen.
2. To – vastaanottajan sähköpostiosoite. (esim. ). Ei pakollinen.
3. SendEmail – kytkinparametri, joka ei vaadi arvoa. Mutta jos käytetään, vaaditaan parametriarvot From ja To.

jos käytetään SendEmail – kytkintä, suoritetaan validointikoodi, joka vahvistaa, että käytetään From ja To – parametreja. Silloin se palauttaa arvon True. Toisaalta, jos From ja To eivät ole käytössä, funktio heittää virheen ja poistuu.

kopioi ja liitä alla oleva koodi PowerShell-istuntoosi.

alla oleva komento johtaa onnistuneeseen validointiin. Koska From ja To parametreja käytettiin yhdessä SendEmail – kytkimen kanssa.

PS51> Send-Spam -From -To -SendEmail

nyt testata sitä ilman From tai To parametri. Tämän pitäisi johtaa virheeseen, koska validointi skripti epäonnistuu. Katso esimerkkitulos alta.

ValidateScript-ominaisuuden käyttäminen konsolissa

vaikka ValidateScript-attribuuttia käytetään yleisimmin funktioparametrien validointiin, sitä voidaan käyttää myös suoraan PowerShell-konsolista. ValidateScript on hyödyllinen validointikoodin testaamiseen jo ennen sen sisällyttämistä komentosarjan tai funktion sisään.

alla on muutamia esimerkkejä Validatescriptin käyttämisestä funktion ulkopuolella.

Validoiva kokonaisluku

tämä alla oleva esimerkki validoi, että tietty kokonaisluku on suurempi kuin viisi.

$i=4

yllä olevan koodin suorittamisen jälkeen odotettu tulos epäonnistuu, koska annettu arvo on 4, joka on pienempi kuin 5. Alla oleva esimerkki kuvakaappaus on mitä odottaa näkevänsä.

validointi päivämäärä arvo

seuraava esimerkki koodi alla osoittaa, miten vahvistaa, että annettu päivämäärä on uudempi tai yhtä suuri kuin nykyinen päivämäärä.

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

suoritettuaan koodin ensimmäisen rivin yllä olevassa pätkässä odotettu tulos ohitetaan (tosi), koska annettu aikaleiman arvo on sama tai muutama sekunti suurempi.

toinen koodirivi tuottaa epäonnistuneen tuloksen, koska aika-arvo on tunnin vähemmän kuin nykyinen aika. Katso alla olevasta kuvakaappauksesta otostulos.

Yhteenveto

tässä artikkelissa opit, mitä parametrin validointi on ja miten ValidateScript-parametrin validointi-attribuuttia käytetään.

opit myös laajentamaan sen kykyä näyttää kuvaavampi Virheilmoitus. Seuratessasi esimerkkejä olet kokenut sekä onnistuneen että epäonnistuneen validoinnin tulokset.

sinun pitäisi nyt ymmärtää Validatescriptin rajoitus ristiinparametriviittausten osalta ja miten voit kiertää tämän rajoituksen käyttämällä $PSBoundParameters automaattista muuttujaa.

toivon, että opit tarpeeksi tässä artikkelissa, että voit hakea PowerShell tool-making journey!

Further Reading

• Powershell Functions Introduction
• Understanding and Building PowerShell Modules
• ValidateScript validation attribute
• about Throw