Im Automator

Beim Erstellen von PowerShell-Funktionen ist die Validierung von Eingaben in Parameter wichtig. Mit der Parametervalidierung können Sie einschränken, was an Funktionen übergeben wird. In diesem Artikel erfahren Sie, wie Sie Probleme mit dem ValidateScript-Validierungsattribut von PowerShell erkennen, bevor sie eins werden.

Mit der Parametervalidierung stellen Sie nicht nur sicher, dass keine Probleme auftreten, sobald die Funktion ausgeführt wird, sondern fördern auch einen saubereren Code, da die Validierungslogik nicht im Hauptteil der Funktion platziert ist.

In Powershell sind mehrere erweiterte Parametervalidierungsattribute verfügbar. In diesem Artikel erfahren Sie jedoch mehr über eine der flexibelsten Parametervalidierungen, die PowerShell ValidateScript-Validierung.

Sie werden sehen, wie es funktioniert und sehen auch Beispiele, wie man es benutzt.

Inhaltsverzeichnis

Parametervalidierung (eine Analogie)

Parametervalidierung

Ich aß zu Mittag und hatte plötzlich Lust auf eine Limonade. Ich ging zum Getränkeautomaten, zog einen ₱ 100-Schein aus meiner Tasche und steckte ihn in den Geldscheinschlitz. Die Maschine spuckt es sofort aus.

Mir ist dann aufgefallen, dass direkt über dem Steckplatz nur bills20- und ₱50-Scheine akzeptiert werden. Am Ende hatte ich kein Soda, weil ich nur diese bill 100-Rechnung bei mir hatte.

Und wie bezieht sich die Geschichte auf die PowerShell-Parametervalidierung? Lass es uns brechen.

  • Die Soda-Maschine dient als Funktion
  • Die Rechnung ist der Parameter
  • Die Rechnungen ₱50 und ₱20 sind die gültigen Parameterwerte
  • Die ₱100 wurde abgelehnt, weil es sich um den falschen Parameterwert handelt
  • Infolgedessen hat die Maschine meine Anfrage aufgrund der falschen Eingabe nicht verarbeitet. Daher kein Soda für mich. ….und ich hatte auch Durst!

Das obige Soda Machine-Szenario ist nur eine Analogie, um das Konzept der Parametervalidierung zu beschreiben.

Logischer Ablauf der Parametervalidierung

Das Konzept der Parametervalidierung folgt einem groben Workflow. Das folgende Bild zeigt einen Überblick über die Funktionsweise der Parametervalidierung.

PowerShell-Parameterüberprüfungsablauf
  1. Die Funktion wird in PowerShell ausgeführt, indem sie ihren Namen aufruft und die Parameterwerte
  2. PowerShell wertet die angegebenen Werte aus.
  3. Wenn das Ergebnis der Validierung wahr ist, ermöglicht PowerShell der Funktion, ihren Prozess fortzusetzen, bevor sie beendet wird.
  4. Wenn das Ergebnis der Validierung falsch ist, zeigt PowerShell einen Fehler an und die Funktion wird beendet.

Walkthrough-Anforderungen

Der Rest dieses Artikels enthält nicht nur Beispiele für die Validierung von PowerShell-Funktionsparametern, sondern auch Beispiele, die Sie kopieren und selbst ausprobieren können. Um zu folgen, benötigen Sie ein paar Dinge, die Sie befolgen müssen.

  • Ein Windows 10-Computer mit einer der folgenden PowerShell-Versionen:
  • Windows PowerShell 5.1
  • PowerShell Core 6.2
  • PowerShell Core 7 (neueste Version dieses Schreibens ist Preview 4)
  • Ein Skript-Editor Ihrer Wahl. Wie Notepad ++, PowerShell ISE oder Visual Studio Code.

Grundlegendes zum ValidateScript-Validierungsattribut

ValidateScript ist eines der Parametervalidierungsattribute, die für die Verwendung in PowerShell verfügbar sind und in PowerShell 3.0 eingeführt wurden. Es kann innerhalb des Parameterdefinitionsblocks einer Funktion hinzugefügt oder direkt in der PowerShell-Konsole verwendet werden.

ValidateScript wird verwendet, um den Wert des eingegebenen Parameters zu validieren. Wenn das Validierungsergebnis $true ist, wird das Skript weiterhin ausgeführt. Auf der anderen Seite, wenn das Ergebnis $false ist, wird die Funktion einen Abschlussfehler auslösen.

Lassen Sie uns eintauchen und sehen, wie es funktioniert.

ValidateScript in einer Funktion verwenden

Das ValidateScript-Attribut wird am häufigsten an einen Funktionsparameter angehängt. In diesem Abschnitt erstellen Sie eine Dummy-Funktion und wenden die Validierung der ValidateScript-Parameter an.

Die Dummy-Funktion führt die folgenden Aktionen aus:

  1. Akzeptieren Sie die Eingabe für den Betrag.
  2. Überprüfen Sie, ob der eingegebene Betrag den akzeptierten Werten entspricht.
  3. Führen Sie den Prozess aus, wenn die Validierung bestanden wurde.
  4. Zeigt einen Fehler an, wenn die Validierung fehlgeschlagen ist.

Im nächsten Abschnitt erfahren Sie Schritt für Schritt, wie Sie diese Funktion erstellen. Starten Sie Ihren Skript-Editor und beginnen Sie mit dem Codieren!

Erstellen Sie die Funktion

Erstellen Sie zunächst eine Funktion und geben Sie ihr einen Namen. Dies kann ein beliebiger Name sein, den Sie wählen. Es empfiehlt sich, der Namenskonvention Verb-Substantiv zu folgen, um Ihre Funktion beschreibend zu machen. Verwenden Sie für dieses Beispiel den Namen Get-Soda.

Function Get-Soda { param ()}

Geben Sie im Block param()den Namen des Parameters ein, der Bill sein soll.

Function Get-Soda { param ( $Bill )}

Zu diesem Zeitpunkt führt die Funktion noch nichts aus, als einen Wert für den Parameter Bill zu akzeptieren.

Stellen Sie sicher, dass Sie die Funktion Get-Soda in Ihre PowerShell-Konsole kopiert haben. Nachdem die Funktion in die PowerShell-Sitzung importiert wurde, testen Sie die Funktion, indem Sie den folgenden Befehl ausführen: Get-Soda -Bill 100.

Wenn Sie die Funktion Get-Soda ausführen, werden Sie feststellen, dass kein Fehler ausgelöst wird und nichts bewirkt. Das wird an dieser Stelle erwartet.

Hinzufügen der Parametervalidierung

Möglicherweise möchten Sie nicht zulassen, dass alle Werte an den Parameter Bill übergeben werden. Anhand der oben in diesem Artikel erläuterten Analogie sollte die Funktion keine ₱100-Rechnungen zulassen. Es sollte nur bills50 und ₱20 Rechnungen erlauben.

Fügen Sie die Validierung des ValidateScript-Parameters hinzu, indem Sie vor dem Parameter Bill einfügen. Ihre Funktion sollte wie der folgende Code aussehen.

Function Get-Soda { param ( $Bill )}

Geben Sie innerhalb des -Blocks den Validierungscode {$_ -eq 20} ein. Dieser Validierungscode überprüft, ob der für den Parameter Rechnung angegebene Wert gleich 20 ist. Das folgende Snippet zeigt, wie der Code aussehen sollte.

Hinweis: Der $_ repräsentiert den Wert des aktuellen Parameters in scope. In diesem Beispiel ist der Wert von $_ der Wert des Parameters Bill.

Function Get-Soda { param ( $Bill )}

Führen Sie nun diese Funktion erneut aus, um zu bestätigen, dass die Parametervalidierung funktioniert, indem Sie Folgendes ausführen:

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

Unten können Sie sehen, dass, wenn 20 als Wert übergeben wird, nichts passiert, aber wenn etwas anderes als 20 übergeben wird, wird ein Fehler ausgegeben.

Fehler

Wenn die Funktion Get-Soda keinen Fehler auslöst, bedeutet dies, dass die Funktion erfolgreich ausgeführt wurde. Um dies zu demonstrieren, fügen Sie den folgenden Code in die Funktion ein, um einfach eine Nachricht an die Konsole zurückzugeben.

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

Die Get-Soda -Funktion sieht dann wie folgt aus:

Übergeben Sie nun einen akzeptierten Wert wie 20 an den Parameter Bill. Sie sollten das Ergebnis unten sehen.

Ausgabe von Get-Soda -bill 20

Anzeigen aussagekräftigerer Fehlermeldungen

Ich bin sicher, Sie haben inzwischen bemerkt, dass die Fehlermeldung, die zurückgegeben wird, wenn der Parameterwert die Validierung nicht besteht, nicht sehr intuitiv und hässlich ist.

Validierungsfehler ist unklar

Leider können Sie nichts dagegen tun, wie der Fehler aussieht. Bis (hoffentlich) eine Funktion veröffentlicht wird, die die Formatierung der Validierungsfehler ermöglicht, bleiben Sie dabei.

Aber es ist möglich, es ein wenig zu verbessern und den Fehlern mehr Bedeutung zu geben, von denen Ihre Benutzer profitieren können. Sie werden das Beispiel sehen, wie Sie das als nächstes tun können.

Hinzufügen eines benutzerdefinierten Validierungsfehlers Unter Verwendung von Windows PowerShell (5.1)

Wenn die Funktion Get-Soda erweitert wird, kann eine bestimmte Fehlermeldung ausgegeben werden, wenn der Wert die Validierung nicht erfüllt. Dazu können Sie ein if / then-Konstrukt innerhalb des ValidateScript-Blocks hinzufügen.

Erstellen Sie ein einfaches if / then-Konstrukt wie im folgenden Beispiel. Wenn in diesem Beispiel der Parameterwert Bill ungleich 20 ist, wird eine Fehlermeldung Ihrer Wahl zurückgegeben (X is invalid. Valid value is 20 only.).

Unten sehen Sie ein Beispiel, wie dies aussieht:

Der Screenshot unten zeigt die benutzerdefinierte Fehlermeldung in Aktion. Der Fehler sieht immer noch hässlich aus, aber diesmal ist die Meldung klar und verständlich.

ValidateScript mit einer benutzerdefinierten Fehlermeldung (PowerShell 5.1)

Hinzufügen von benutzerdefinierten Validierungsfehlern mithilfe von PowerShell Core (6+)

Ab PowerShell Core 6 ist die Möglichkeit, benutzerdefinierte Fehlermeldungen zur Validierung von ValidateScript-Parametern hinzuzufügen, bereits integriert. Nennen wir dies die ErrorMessage-Technik.

Im modifizierten Get-Soda -Funktionscode unten enthält der -Block jetzt eine ErrorMessage -Eigenschaft, die anstelle von throw verwendet werden kann. Anstatt nun die Variable $_ zu verwenden, können Sie {0} verwenden, die den übergebenen Parameterwert darstellt.

Der folgende Screenshot zeigt, dass die erwartete Ausgabe genau dieselbe ist wie bei Verwendung der if-else- und Throw-Technik.

ValidateScript mit einer benutzerdefinierten Fehlermeldung (PowerShell Core 7-Vorschau 4)

PowerShell ValidateScript-Anwendungsbeispiele

Dies sind einige reale Anwendungsfallszenarien, für die ValidateScript angewendet werden kann. Überprüfen und testen Sie diese Beispiele und versuchen Sie dann, die Fehlermeldung mithilfe der im vorherigen Abschnitt erlernten Techniken selbst zu verbessern.

Validierung von Datumsparametern

Dieses Snippet ist eine Funktion, die ein Start- und ein Enddatum akzeptiert. Es wird überprüft, ob die eingegebenen Daten nicht in der Zukunft liegen und nicht älter als 90 Tage sind.

Testen Sie die Funktion mit diesen Befehlen. Sie können Ihre eigenen startDate und endDate Werte angeben

Diese Beispielausgabe unten ist, wenn gültige Datumswerte eingegeben werden.

Search-Ergebnis mit gültigen Datumsparameterwerten protokollieren

Testen Sie es nun erneut mit startDate, das älter als 90 Tage ist. Bestätigen Sie dann, dass die Fehlermeldung angezeigt wird.

Windows Process Parameter Validation

Dieses nächste Snippet ist eine Funktion, die den Namen eines Prozesses akzeptiert. Es bestätigt, dass der Prozess im Speicher ausgeführt wird, und beendet dann alle laufenden Instanzen dieses Prozesses oder beendet ihn abhängig vom Validierungsergebnis.

Testen Sie es mit diesem Befehl: Kill-Process -Name <process name>

In der folgenden Beispielausgabe wird davon ausgegangen, dass Sie mit dem Prozess namens notepad testen.

  • Der erste Befehl wurde erfolgreich ausgeführt, da der Notepad-Prozess ausgeführt wurde und beendet wurde.
  • Der zweite Befehl ist fehlgeschlagen, da notepad nicht mehr ausgeführt wird und die Funktion mit der von Ihnen erstellten benutzerdefinierten Fehlermeldung beendet wurde.
Parameterüberprüfungsfehler

Validieren von Parametern durch einen anderen Parameterwert

Jetzt sollten Sie eine Vorstellung davon haben, welchen Wert die Verwendung von ValidateScript in Ihren Funktionen hat. Bu Es gibt eine Einschränkung, die erwähnenswert ist. Der Gültigkeitsbereich von ValidateScript liegt nur innerhalb des verwendeten Parameters. Dies bedeutet, dass ein Parameter den Wert anderer Parameter nicht verwenden kann.

Als Workaround kann die Überprüfung parameterübergreifender Werte durch Zugriff auf die automatische Variable $PSBoundParameters erfolgen.

Vielleicht haben Sie eine Funktion namens Send-Spam . Diese Funktion hat drei Parameter:

  1. From – Die E-Mail-Adresse des Absenders. (z. ). Nicht obligatorisch.
  2. To – Die E-Mail-Adresse des Empfängers. (z. ). Nicht obligatorisch.
  3. SendEmail – Ein Switch-Parameter, der keinen Wert benötigt. Bei Verwendung sind jedoch die Parameterwerte From und To erforderlich.

Wenn der Schalter SendEmailverwendet wird, wird ein Validierungscode ausgeführt, um zu bestätigen, dass die Parameter From und To verwendet werden. Dann wird der Wert True zurückgegeben. Wenn andererseits From und To nicht verwendet werden, gibt die Funktion einen Fehler aus und wird beendet.

Kopieren Sie den folgenden Code und fügen Sie ihn in Ihre PowerShell-Sitzung ein.

Der unten gezeigte Befehl führt zu einer erfolgreichen Validierung. Weil die Parameter From und To zusammen mit dem Schalter SendEmail verwendet wurden.

PS51> Send-Spam -From -To -SendEmail
Ausgabe von Send-Spam

Testen Sie es nun, ohne den Parameter From oder To zu verwenden. Dies sollte zu einem Fehler führen, da das Validierungsskript fehlschlägt. Siehe das Beispielergebnis unten.

Ausführen von Send-Spam ohne den Parameter To

Verwenden von ValidateScript in der Konsole

Obwohl das ValidateScript-Attribut am häufigsten zum Validieren von Funktionsparametern verwendet wird, kann es auch direkt von der PowerShell-Konsole aus verwendet werden. ValidateScript ist nützlich, um Ihren Validierungscode zu testen, noch bevor Sie ihn in ein Skript oder eine Funktion integrieren.

Nachfolgend finden Sie einige Beispiele für die Verwendung von ValidateScript außerhalb einer Funktion.

Ganzzahligen Wert validieren

In diesem Beispiel wird überprüft, ob ein bestimmter ganzzahliger Wert größer als fünf ist.

$i=4

Nach dem Ausführen des obigen Codes schlägt das erwartete Ergebnis fehl, da der angegebene Wert 4 ist, der kleiner als 5 ist. Der Beispiel-Screenshot unten ist das, was Sie erwarten würden.

Validierung fehlgeschlagen

Validieren eines Datumswerts

Der folgende Beispielcode zeigt, wie überprüft wird, ob das angegebene Datum neuer oder gleich dem aktuellen Datum ist.

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

Nach dem Ausführen der ersten Zeile des Codes im obigen Snippet wird das erwartete Ergebnis übergeben (True), da der angegebene DateTime-Wert gleich oder einige Sekunden größer ist.

Die zweite Codezeile führt zu einem fehlgeschlagenen Ergebnis, da der DateTime-Wert eine Stunde unter der aktuellen Zeit liegt. Siehe den Screenshot unten für die Beispielausgabe.

Fehler bei der Validierung von Datumsparametern

Zusammenfassung

In diesem Artikel erfuhren Sie, was Parametervalidierung ist und wie Sie das ValidateScript-Parametervalidierungsattribut verwenden.

Sie haben auch gelernt, wie Sie die Funktion erweitern können, um eine aussagekräftigere Fehlermeldung anzuzeigen. Während Sie den Beispielen folgen, haben Sie die Ergebnisse sowohl erfolgreicher als auch fehlgeschlagener Validierung erlebt.

Sie sollten nun die Einschränkung von ValidateScript in Bezug auf die parameterübergreifende Referenzierung verstehen und wie Sie diese Einschränkung umgehen können, indem Sie die automatische Variable $PSBoundParameters .

Ich hoffe, Sie haben in diesem Artikel genug gelernt, das Sie auf Ihrer PowerShell-Tool-Making-Reise anwenden können!

Weiterführende Literatur

  • Powershell-Funktionen Einführung
  • PowerShell-Module verstehen und erstellen
  • ValidateScript-Validierungsattribut
  • Über Throw

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.