Adam Automator

podczas tworzenia funkcji PowerShell ważne jest walidowanie danych wejściowych do parametrów. Walidacja parametrów pozwala ograniczyć to, co jest przekazywane do funkcji. W tym artykule dowiesz się, jak wykrywać problemy, zanim staną się one jednym z atrybutem walidacji PowerShell ValidateScript.

korzystając z walidacji parametrów, nie tylko upewniasz się, że problemy nie pojawiają się po uruchomieniu funkcji, ale także promujesz czystszy Kod, ponieważ logika walidacji nie jest umieszczona w ciele funkcji.

w Powershell dostępnych jest kilka zaawansowanych atrybutów walidacji parametrów. Ale w tym artykule dowiesz się o jednym z najbardziej elastycznych walidacji parametrów, walidacji PowerShell ValidateScript.

zobaczysz jak to działa, a także zobaczysz przykłady jak z niego korzystać.

spis treści

Walidacja parametrów (analogia)

Walidacja parametrów

jadłem lunch i nagle poczułem, że mam ochotę na napój. Podszedłem do automatu z napojami, wyciągnąłem z kieszeni banknot o wartości ₱100 i włożyłem go do gniazda na banknoty. Maszyna wypluwa ją natychmiast.

wtedy zauważyłem, że tuż nad gniazdem jest napisane, że akceptuje tylko banknoty ₱20 i ₱50. Skończyło się na tym, że nie wypiłem napoju, bo miałem tylko ten banknot 100 $ ze sobą.

i jak historia odnosi się do walidacji parametrów PowerShell? Rozwalmy to.

  • maszyna soda służy jako funkcja
  • rachunek jest parametrem
  • rachunki ₱50 i ₱20 są poprawnymi wartościami parametrów
  • ₱100 zostało odrzucone, ponieważ jest to niewłaściwa wartość parametru
  • w rezultacie maszyna nie przetworzyła mojego żądania z powodu niewłaściwego wejścia. Dlatego nie ma dla mnie wody sodowej. ….i też byłem spragniony!

powyższy scenariusz maszyny soda jest tylko jedną analogią opisującą koncepcję walidacji parametrów.

przepływ logiczny walidacji parametrów

koncepcja walidacji parametrów opiera się na przybliżonym przepływie pracy. Poniższy obrazek przedstawia przegląd sposobu walidacji parametrów.

przepływ walidacji parametrów PowerShell
  1. funkcja jest wykonywana w PowerShell przez wywołanie jej nazwy i podanie wartości parametrów
  2. PowerShell oblicza podane wartości.
  3. jeśli wynik walidacji jest prawdziwy, PowerShell pozwoli funkcji kontynuować proces przed zakończeniem.
  4. jeśli wynik walidacji jest fałszywy, PowerShell wyświetli błąd i funkcja zakończy działanie.

wymagania dotyczące przejścia

więcej niż tylko mówienie o sprawdzaniu parametrów funkcji PowerShell, reszta tego artykułu będzie zawierać przykłady, które możesz skopiować i wypróbować samodzielnie. Aby podążać za nim, musisz mieć kilka rzeczy do naśladowania.

  • komputer z systemem Windows 10 z dowolną z poniższych wersji PowerShell:
  • Windows PowerShell 5.1
  • PowerShell Core 6.2
  • PowerShell Core 7 (najnowsza wersja tego zapisu to Preview 4)
  • Edytor skryptów do wyboru. Jak Notepad++, PowerShell ISE lub Visual Studio Code.

zrozumienie atrybutu walidacji ValidateScript

ValidateScript jest jednym z atrybutów walidacji parametrów dostępnych do użycia w PowerShell wprowadzonym w PowerShell 3.0. Może być dodany wewnątrz bloku definicji parametrów funkcji, lub może być również używany bezpośrednio w konsoli PowerShell.

ValidateScript służy do weryfikacji wartości wprowadzonego parametru. Jeśli wynikiem walidacji jest $true, skrypt będzie nadal działał. Z drugiej strony, jeśli wynikiem jest $false, funkcja wyrzuci błąd zakończenia.

zanurkujmy i zobaczmy, jak to działa.

używanie atrybutu ValidateScript w funkcji

najczęstsze użycie atrybutu validatescript jest dołączone do parametru funkcji. W tej sekcji utworzysz funkcję pozorowaną i zastosujesz walidację parametrów ValidateScript.

funkcja dummy wykona następujące czynności:

  1. Akceptuj wejście dla kwoty.
  2. sprawdź, czy wprowadzona kwota jest równa zaakceptowanym wartościom.
  3. Uruchom proces, jeśli Walidacja przeszła.
  4. wyświetla błąd, jeśli Walidacja nie powiodła się.

w następnej sekcji dowiesz się, jak zbudować tę funkcję krok po kroku. Uruchom swój edytor skryptów i rozpocznij kodowanie!

Zbuduj funkcję

najpierw Utwórz funkcję i nadaj jej nazwę. Może to być dowolna nazwa, którą wybierzesz. Najlepiej jest postępować zgodnie z konwencją nazewnictwa czasowników i rzeczowników, aby Twoja funkcja była opisowa. W tym przykładzie użyj nazwy Get-Soda.

Function Get-Soda { param ()}

wewnątrz bloku param() Wstaw nazwę parametru, którego będziesz używał, czyli Bill.

Function Get-Soda { param ( $Bill )}

w tym momencie funkcja nie wykonuje jeszcze niczego, ale przyjmuje dowolną wartość dla parametru Bill.

upewnij się, że skopiowałeś funkcję Get-Soda do konsoli PowerShell. Po zaimportowaniu funkcji do sesji PowerShell przetestuj ją, uruchamiając polecenie: Get-Soda -Bill 100.

po uruchomieniu funkcji Get-Soda zauważysz, że żaden błąd nie jest wyrzucany i nic nie robi. Tego się teraz spodziewamy.

dodawanie walidacji parametrów

być może nie chcesz zezwalać na przekazywanie wszystkich wartości do parametru Bill. Korzystając z analogii wyjaśnionej na górze tego artykułu, funkcja nie powinna zezwalać na ₱100 banknotów. Powinien zezwalać tylko na banknoty ₱50 i ₱20.

Dodaj walidację parametru ValidateScript, wstawiając przed parametrem Bill. Twoja funkcja powinna wyglądać jak poniższy kod.

Function Get-Soda { param ( $Bill )}

wewnątrz bloku wstaw kod weryfikacyjny {$_ -eq 20}. Ten kod weryfikacyjny sprawdza, czy wartość podana do parametru bill jest równa 20. Poniższy fragment przedstawia jak powinien wyglądać kod.

Uwaga: $_ reprezentuje wartość bieżącego parametru w zakresie. W tym przykładzie wartość $_ jest wartością parametru Bill.

Function Get-Soda { param ( $Bill )}

Teraz uruchom tę funkcję ponownie, aby potwierdzić, że Walidacja parametrów działa, uruchamiając:

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

poniżej możesz zobaczyć, że gdy wartość 20 jest przekazywana jako wartość, nic się nie dzieje, ale gdy coś innego niż 20 jest przekazywana, generuje błąd.

błąd

gdy funkcja Get-Soda nie wyrzuca Błędu, oznacza to, że funkcja została pomyślnie wykonana. Aby to zademonstrować, Dodaj następujący kod wewnątrz funkcji, aby po prostu zwrócić wiadomość do konsoli.

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

funkcja Get-Soda będzie wtedy wyglądać jak poniżej:

teraz przekazuje zaakceptowaną wartość, taką jak 20 do parametru Bill. Powinieneś zobaczyć wynik poniżej.

wyjście Get – soda-bill 20

wyświetlanie bardziej znaczących komunikatów o błędach

jestem pewien, że zauważyłeś już, że komunikat o błędzie zwracany, gdy wartość parametru nie przechodzi walidacji, nie jest zbyt intuicyjny i brzydki.

błąd walidacji jest niejasny

niestety, nie można nic zrobić o tym, jak błąd wygląda. Dopóki nie zostanie wydana funkcja umożliwiająca formatowanie błędów walidacji (miejmy nadzieję), utknąłeś z nią.

ale można go trochę poprawić i nadać więcej znaczenia błędom, które mogą przynieść korzyści użytkownikom. Zobaczysz przykład, jak to zrobić.

Dodawanie niestandardowego błędu walidacji za pomocą programu Windows PowerShell (5.1)

rozszerzając funkcję Get-Soda, można wyrzucić określony komunikat o błędzie, gdy wartość nie spełnia walidacji. Aby to zrobić, możesz dodać konstrukcję if/then wewnątrz bloku ValidateScript.

Utwórz prostą konstrukcję if / then, jak w poniższym przykładzie. W tym przykładzie, jeśli wartość parametru Bill nie jest równa 20, zwróci on wybrany przez Ciebie komunikat o błędzie (X is invalid. Valid value is 20 only.).

możesz zobaczyć przykład tego, jak to wygląda poniżej:

poniższy zrzut ekranu pokazuje niestandardowy komunikat o błędzie w akcji. Błąd nadal wygląda brzydko, ale tym razem wiadomość jest jasna i zrozumiała.

ValidateScript z niestandardowym Komunikatem o błędzie (PowerShell 5.1)

dodawanie niestandardowych błędów walidacji przy użyciu rdzenia PowerShell(6+)

począwszy od PowerShell Core 6, możliwość dodawania niestandardowych komunikatów o błędach do walidacji parametrów ValidateScript jest już wbudowana. Nazwijmy to techniką ErrorMessage.

w zmodyfikowanym kodzie funkcji Get-Soda poniżej, blok zawiera teraz właściwość ErrorMessage, która może być użyta w miejscu throw. Teraz zamiast używać zmiennej $_, możesz użyć {0}, która będzie reprezentować przekazaną wartość parametru.

zrzut ekranu poniżej pokazuje, że oczekiwany wynik jest dokładnie taki sam jak przy użyciu techniki if-else I throw.

ValidateScript z niestandardowym Komunikatem o błędzie (PowerShell Core 7 preview 4)

przykłady użycia PowerShell ValidateScript

Oto kilka rzeczywistych scenariuszy przypadków użycia, dla których można zastosować ValidateScript. Przejrzyj i przetestuj te przykłady, a następnie spróbuj poprawić komunikat o błędzie samodzielnie, korzystając z technik poznanych w poprzedniej sekcji.

Walidacja parametrów daty

ten fragment jest funkcją, która akceptuje datę początkową i końcową. Przeprowadza walidację, że wprowadzone daty nie są w przyszłości i nie są starsze niż 90 dni.

Przetestuj funkcję za pomocą tych poleceń. Możesz określić własne wartości startDate i endDate

to Przykładowe wyjście poniżej jest, gdy wprowadzone są poprawne wartości daty.

Search-Zaloguj wynik z poprawnymi wartościami parametrów daty

teraz przetestuj go ponownie za pomocą startDate, która jest starsza niż 90 dni. Następnie potwierdź wyświetlenie komunikatu o błędzie.

Walidacja parametrów procesu systemu Windows

ten następny fragment jest funkcją akceptującą nazwę procesu. Potwierdza, że proces działa w pamięci, a następnie zabija wszystkie uruchomione instancje tego procesu lub kończy działanie w zależności od wyniku walidacji.

przetestuj to za pomocą tego polecenia: Kill-Process -Name <process name>

poniższy przykładowy wynik zakłada, że testujesz za pomocą procesu o nazwie notatnik.

  • pierwsze polecenie przebiegło pomyślnie, ponieważ okazało się, że proces notatnika jest uruchomiony i przystąpił do jego zabicia.
  • drugie polecenie nie powiodło się, ponieważ notatnik nie jest już uruchomiony, a funkcja zakończyła się utworzonym niestandardowym Komunikatem o błędzie.
błąd walidacji parametrów

Walidacja parametrów przez inną wartość parametru

teraz powinieneś mieć pojęcie o wartości używania ValidateScript w swoich funkcjach. Bu jest jedno ograniczenie, które warto wspomnieć. Zakres ValidateScript znajduje się tylko w użytym parametrze. Oznacza to, że jeden parametr nie może używać wartości innych parametrów.

jako obejście, sprawdzanie wartości między parametrami można wykonać, uzyskując dostęp do zmiennej automatycznej $PSBoundParameters.

być może masz funkcję o nazwie Send-Spam. Funkcja ta ma trzy parametry:

  1. From – adres e-mail nadawcy. (np. ). Nie jest to obowiązkowe.
  2. To – adres e-mail odbiorcy. (np. ). Nie jest to obowiązkowe.
  3. SendEmail – parametr przełącznika, który nie wymaga wartości. Jeśli jednak zostanie użyte, wymagane będą wartości parametrów From i To.

jeśli używany jest przełącznik SendEmail, zostanie uruchomiony kod weryfikacyjny, aby potwierdzić, że używane są parametry From i To. Następnie zwróci wartość True. Z drugiej strony, jeśli From i To nie są używane, funkcja wyrzuci błąd i zakończy działanie.

skopiuj i wklej poniższy kod do sesji PowerShell.

polecenie pokazane poniżej spowoduje pomyślną walidację. Ponieważ parametry From i To zostały użyte wraz z przełącznikiem SendEmail.

PS51> Send-Spam -From -To -SendEmail
wyjście z Send-Spam

teraz przetestuj go bez użycia parametru From lub To. Powinno to spowodować błąd, ponieważ skrypt walidacji nie powiedzie się. Zobacz przykładowy wynik poniżej.

uruchamianie Send-Spam bez parametru To

używanie atrybutu ValidateScript w konsoli

chociaż najczęściej używa się atrybutu validatescript do sprawdzania parametrów funkcji, można go również użyć bezpośrednio z konsoli PowerShell. ValidateScript jest przydatny do testowania kodu weryfikacyjnego nawet przed włączeniem go do skryptu lub funkcji.

poniżej kilka przykładów użycia ValidateScript poza funkcją.

sprawdzanie wartości całkowitej

poniższy przykład potwierdza, że podana wartość całkowita jest większa niż pięć.

$i=4

po uruchomieniu powyższego kodu oczekiwany wynik nie powiedzie się, ponieważ podana wartość to 4, czyli mniej niż 5. Przykładowy zrzut ekranu poniżej jest tym, czego można się spodziewać.

nieudana Walidacja

sprawdzanie wartości daty

następny przykładowy kod poniżej pokazuje, jak sprawdzić, czy podana data jest nowsza lub równa bieżącej dacie.

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

po uruchomieniu pierwszej linii kodu w powyższym fragmencie oczekiwany wynik jest przekazywany (True), ponieważ podana wartość DateTime jest taka sama lub o kilka sekund większa.

drugi wiersz kodu spowoduje błąd, ponieważ wartość DateTime jest o godzinę mniejsza niż bieżący czas. Zobacz zrzut ekranu poniżej, aby uzyskać przykładowe dane wyjściowe.

błąd walidacji parametru daty

podsumowanie

w tym artykule dowiesz się, czym jest Walidacja parametrów i jak używać atrybutu walidacji parametrów ValidateScript.

nauczyłeś się również, jak rozszerzyć jego możliwości, aby wyświetlić bardziej opisowy komunikat o błędzie. Postępując zgodnie z przykładami, doświadczyłeś wyników zarówno udanej, jak i nieudanej walidacji.

powinieneś teraz zrozumieć ograniczenie ValidateScript pod względem odwoływania się do różnych parametrów oraz sposób obejścia tego ograniczenia poprzez użycie zmiennej automatycznej $PSBoundParameters.

mam nadzieję, że nauczyłeś się w tym artykule na tyle dużo, że możesz zastosować w swojej podróży do tworzenia narzędzi PowerShell!

Czytaj dalej

  • Wprowadzenie do funkcji Powershell
  • zrozumienie i budowanie modułów PowerShell
  • atrybut walidacji ValidateScript
  • informacje o Throw

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany.