Adam Automatorn

när du skapar PowerShell-funktioner är det viktigt att validera inmatning till parametrar. Parametervalidering gör att du kan begränsa vad som skickas till funktioner. I den här artikeln kommer du att lära dig att fånga problem innan de blir ett med PowerShell ValidateScript validation-attributet.

med parametervalidering säkerställer du inte bara att problem inte uppstår när funktionen körs utan främjar också renare kod eftersom valideringslogiken inte placeras i funktionens kropp.

det finns flera avancerade parametervalideringsattribut tillgängliga i Powershell. Men i den här artikeln kommer du att lära dig om en av de mest flexibla parametervalideringarna, PowerShell ValidateScript validation.

du ser hur det fungerar och ser också exempel på hur du använder det.

Parametervalidering (en analogi)

jag åt lunch och kände mig plötsligt som att ha en läsk. Jag gick till läskmaskinen, drog ut en 100-sedel från min ficka och satte in den i räkningen. Maskinen spottar ut det omedelbart.

jag märkte då att precis precis ovanför spåret står det att det bara accepterar 20-och 50-räkningar för 20-och 50-räkningar. Jag slutade med att inte ha läsken eftersom jag bara hade den 100-fakturan med mig.

och hur relaterar historien till PowerShell-parametervalidering? Låt oss bryta ner det.

• soda-maskinen fungerar som funktionen
• räkningen är parametern
• de 50-och 20-räkningarna är de giltiga parametervärdena
• 100-kuberna avvisades eftersom det är fel parametervärde
• som ett resultat behandlade maskinen inte min begäran på grund av fel inmatning. Ingen läsk för mig. ….jag var också törstig!

soda-maskinscenariot ovan är bara en analogi för att beskriva begreppet parametervalidering.

Parametervalideringslogikflöde

begreppet parametervalidering följer ett grovt arbetsflöde. Bilden nedan visar en översikt över hur parametervalidering fungerar.

1. funktionen körs i PowerShell genom att ringa sitt namn och tillhandahålla parametervärdena
2. PowerShell utvärderar de angivna värdena.
3. om resultatet av valideringen är sant tillåter PowerShell funktionen att fortsätta sin process innan den avslutas.
4. om resultatet av valideringen är falskt visar PowerShell ett fel och funktionen avslutas.

Genomgångskrav

mer än att bara prata om PowerShell-funktionsparametervalidering, kommer resten av den här artikeln att ha exempel som du kan kopiera och prova på egen hand. För att följa med behöver du några saker att följa med.

• en Windows 10-dator med någon av PowerShell-versionerna nedan:
• Windows PowerShell 5.1
• PowerShell Core 6.2
• Power Core 7 (senaste versionen av detta skrivande är Preview 4)
• ett skript redaktör för ditt val. Gilla, Notepad++, PowerShell ISE eller Visual Studio Code.

förstå Valideringsattributet ValidateScript

ValidateScript är ett av parametervalideringsattributen som är tillgängliga för användning i PowerShell introducerad i PowerShell 3.0. Det kan läggas till i parameterdefinitionsblocket för en funktion, eller det kan också användas direkt i PowerShell-konsolen.

ValidateScript används för att validera värdet på parametern du angav. Om valideringsresultatet är $true fortsätter skriptet att köras. Å andra sidan, om resultatet är $false, kommer funktionen att kasta ett avslutande fel.

låt oss dyka in och se hur det fungerar.

använda ValidateScript i en funktion

den vanligaste användningen av ValidateScript-attributet är kopplad till en funktionsparameter. I det här avsnittet skapar du en dummy-funktion och tillämpar ValidateScript-parametervalidering.

dummy-funktionen utför följande åtgärder:

1. Acceptera input för beloppet.
2. validera om det angivna beloppet är lika med accepterade värden.
3. Kör processen om valideringen passerade.
4. visa ett fel om valideringen misslyckades.

du lär dig hur du bygger den här funktionen steg för steg i nästa avsnitt. Brand upp ditt manus redaktör och börja kodning!

Bygg funktionen

skapa först en funktion och ge den ett namn. Detta kan vara vilket namn du väljer. Det är bästa praxis att följa namnkonventionen för Verb-substantiv för att göra din funktion beskrivande. I det här exemplet använder du namnet Get-Soda.

Function Get-Soda { param ()}

inuti param() – blocket, sätt in namnet på parametern du ska använda som är Bill.

Function Get-Soda { param ( $Bill )}

vid denna tidpunkt utför funktionen inget annat än att acceptera något värde för parametern Bill.

se till att du har kopierat funktionen Get-Soda till din PowerShell-konsol. När funktionen har importerats till PowerShell-sessionen, testa funktionen genom att köra kommandot: Get-Soda -Bill 100.

när du kör funktionen Get-Soda kommer du att märka att inget fel kastas och det gör ingenting. Det förväntas vid denna tidpunkt.

lägga till Parametervalidering

kanske vill du inte tillåta att alla värden skickas till parametern Bill. Med hjälp av analogin som förklaras högst upp i den här artikeln bör funktionen inte tillåta 100-räkningar på 100-talet. Det bör endast tillåta 50 och 20 20 räkningar.

Lägg till validering av ValidateScript-parametern genom att infoga före parametern Bill. Din funktion ska se ut som koden nedan.

Function Get-Soda { param ( $Bill )}

inuti blocket , sätt in valideringskoden {$_ -eq 20}. Denna valideringskod kontrollerar om värdet som anges för bill-parametern är lika med 20. Nedanstående utdrag är hur koden ska se ut.

Obs: $_ representerar värdet för den aktuella parametern i omfattning. I det här exemplet är värdet på $_värdet på parametern Bill.

Function Get-Soda { param ( $Bill )}

kör nu den här funktionen igen för att bekräfta att parametervalideringen fungerar genom att köra:

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

nedan kan du se att när 20 passeras som ett värde, händer ingenting men när något annat än 20 passeras, kastar det ett fel.

när funktionen Get-Soda inte kastar ett fel betyder det att funktionen körs framgångsrikt. För att visa det, lägg till följande kod inuti funktionen för att helt enkelt returnera ett meddelande till konsolen.

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

funktionenGet-Soda kommer då att se ut nedan:

Skicka nu ett accepterat värde som 20 till parametern Bill. Du bör se resultatet nedan.

visar mer meningsfulla felmeddelanden

jag är säker på att du har märkt nu att felmeddelandet återvände när parametervärdet inte passerar validering är inte särskilt intuitivt och fult.

tyvärr finns det inget du kan göra åt hur felet ser ut. Tills en funktion som möjliggör formatering av valideringsfelen släpps (förhoppningsvis), sitter du fast med den.

men det är möjligt att förbättra det lite och ge mer mening åt de fel som kan gynna dina användare. Du kommer att se exemplet på hur du gör det nästa.

lägga till anpassat valideringsfel med Windows PowerShell (5.1)

expandera på funktionen Get-Soda, det är möjligt att kasta specifikt felmeddelande när värdet inte uppfyller validering. För att göra detta kan du lägga till en if/then-konstruktion inuti ValidateScript-blocket.

skapa en enkel om / sedan konstruera som i exemplet nedan. I det här exemplet, om parametervärdet Bill inte är lika med 20, kommer det att returnera ett felmeddelande som du väljer (X is invalid. Valid value is 20 only.).

du kan se ett exempel på hur det här ser ut nedan:

skärmdumpen nedan visar det anpassade felmeddelandet i aktion. Felet ser fortfarande fult ut, men den här gången är meddelandet tydligt och förståeligt.

lägga till anpassade valideringsfel med hjälp av PowerShell Core (6+)

från och med Power Core 6 är möjligheten att lägga till anpassade felmeddelanden till ValidateScript-parametervalidering redan inbyggd. Låt oss kalla detta felmeddelandet teknik.

i den modifierade Get-Soda funktionskoden nedan innehåller blocket nu en ErrorMessage egenskap som kan användas på plats throw. Nu istället för att använda variabeln $_ kan du använda {0} som representerar parametervärdet som passerat.

skärmdumpen nedan visar att den förväntade utmatningen är exakt densamma som med if-else and throw-tekniken.

PowerShell ValidateScript-användningsexempel

det här är några verkliga användarfallsscenarier för vilka ValidateScript kan tillämpas. Granska och testa dessa exempel och försök sedan förbättra felmeddelandet på egen hand med hjälp av de tekniker du lärde dig i föregående avsnitt.

Datumparametervalidering

detta utdrag är en funktion som accepterar ett start-och slutdatum. Den utför validering att de angivna datumen inte är i framtiden och inte är äldre än 90 dagar.

testa funktionen genom att använda dessa kommandon. Du kan ange dina egna startDate och endDate värden

det här exempelutmatningen nedan är när giltiga datumvärden anges.

testa nu igen med startDate som är äldre än 90 dagar. Bekräfta sedan att felmeddelandet visas.

Windows Processparametervalidering

detta nästa utdrag är en funktion som accepterar namnet på en process. Det bekräftar att processen körs i minnet, dödar sedan alla kör instanser av processen eller avsluta beroende på valideringsresultatet.

testa det med det här kommandot: Kill-Process -Name <process name>

exempelutmatningen nedan förutsätter att du testar med processen som heter notepad.

• det första kommandot körde framgångsrikt eftersom det fann att notepad-processen kördes och fortsatte att döda den.
• det andra kommandot misslyckades eftersom notepad inte längre körs och funktionen slutade med det anpassade felmeddelandet du skapade.

validera parametrar med ett annat parametervärde

nu bör du ha en uppfattning om värdet av att använda ValidateScript i dina funktioner. Bu det finns en begränsning som är värt att nämna. Validatescripts omfattning ligger bara inom den parameter som används. Det betyder att en parameter inte kan använda värdet på andra parametrar.

som en lösning kan kryssparametervärdeskontroll göras genom att öppna den automatiska variabeln $PSBoundParameters.

kanske har du en funktion som heter Send-Spam. Denna funktion har tre parametrar:

1. From – avsändarens e-postadress. (t.ex. ). Inte obligatoriskt.
2. To – mottagarens e-postadress. (t.ex. ). Inte obligatoriskt.
3. SendEmail – en växelparameter som inte kräver ett värde. Men om det används krävs parametervärdena From och To.

Om SendEmail – omkopplaren används, körs en valideringskod för att bekräfta att parametrarna From och To används. Då kommer det att returnera värdet på True. Å andra sidan, om From och To inte används, kommer funktionen att kasta ett fel och avsluta.

kopiera och klistra in koden nedan i din PowerShell-session.

kommandot som visas nedan kommer att resultera i en lyckad validering. Eftersom parametrarna From och To användes tillsammans med SendEmail – omkopplaren.

PS51> Send-Spam -From -To -SendEmail

testa det nu utan att använda parametern From eller To. Detta bör resultera i ett fel eftersom valideringsskriptet misslyckas. Se exempelresultatet nedan.

använda ValidateScript i konsolen

även om den vanligaste användningen av ValidateScript-attributet används för att validera funktionsparametrar, kan den också användas direkt från PowerShell-konsolen. ValidateScript är användbart för att testa din valideringskod redan innan den införlivas i ett skript eller en funktion.

Nedan följer några exempel på att använda ValidateScript utanför en funktion.

validera heltal

detta exempel nedan validerar att ett givet heltal är större än fem.

$i=4

efter att ha kört ovanstående kod misslyckas det förväntade resultatet eftersom det angivna värdet är 4 vilket är mindre än 5. Exemplet skärmdump nedan är vad du förväntar dig att se.

validera ett datumvärde

nästa exempelkod nedan visar hur du validerar att det angivna datumet är nyare än eller lika med det aktuella datumet.

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

efter att ha kört den första raden i koden i ovanstående utdrag passeras det förväntade resultatet (sant) eftersom det angivna DateTime-värdet är detsamma eller några sekunder större.

den andra kodraden ger ett misslyckat resultat eftersom DateTime-värdet är en timme mindre än den aktuella tiden. Se skärmdumpen nedan för provutgången.

sammanfattning

i den här artikeln lärde du dig vad parametervalidering är och hur du använder valideringsattributet ValidateScript.

du lärde dig också hur du utökar dess förmåga att visa ett mer beskrivande felmeddelande. När du följer exemplen har du upplevt resultaten av både framgångsrik och misslyckad validering.

du bör nu förstå begränsningen av ValidateScript när det gäller korsparameterreferenser och hur du kan lösa den begränsningen genom att använda den automatiska variabeln $PSBoundParameters.

jag hoppas att du lärde dig tillräckligt i den här artikeln som du kan använda i din PowerShell-verktygsresa!

Vidare läsning

• Powershell-funktioner introduktion
• förstå och bygga PowerShell-moduler
• ValidateScript validation attribute
• om kast