Alle PowerShell-Befehle können einen oder mehrere Parameter haben, die manchmal als Argumente bezeichnet werden. Wenn Sie in Ihren PowerShell-Funktionen keine PowerShell-Parameter verwenden, schreiben Sie keinen guten PowerShell-Code!
In diesem Artikel erfahren Sie alles über das Erstellen und Verwenden von PowerShell-Parametern oder Argumenten!
Dies ist ein Beispiel aus meinem Buch „PowerShell für SysAdmins“. Wenn Sie PowerShell lernen oder einige Tricks des Handwerks erlernen möchten, schauen Sie es sich an!
Warum benötigen Sie einen Parameter?
Wenn Sie Funktionen erstellen, haben Sie die Möglichkeit, Parameter einzuschließen oder nicht und wie diese Parameter funktionieren.
Angenommen, Sie haben eine Funktion, die Microsoft Office installiert. Vielleicht ruft es den Office-Installer leise innerhalb der Funktion auf. Was die Funktion tut, spielt für unsere Zwecke keine Rolle. Die grundlegende Funktion sieht folgendermaßen aus, mit dem Namen der Funktion und dem Skriptblock.
In diesem Beispiel haben Sie gerade Install-Office ohne Parameter ausgeführt und es erledigt seine Aufgabe.
Es spielte keine Rolle, ob die Funktion Install-Office Parameter hatte oder nicht. Offensichtlich hatte es keine obligatorischen Parameter; sonst hätte PowerShell uns nicht erlaubt, es ohne Verwendung eines Parameters auszuführen.
Wann PowerShell-Parameter verwenden
Office hat viele verschiedene Versionen. Vielleicht müssen Sie Office 2013 und 2016 installieren. Derzeit haben Sie keine Möglichkeit, dies anzugeben. Sie könnten den Code der Funktion jedes Mal ändern, wenn Sie das Verhalten ändern möchten.
Zum Beispiel könnten Sie zwei separate Funktionen erstellen, um verschiedene Versionen zu installieren.
Das funktioniert zwar, ist aber nicht skalierbar. Es zwingt Sie dazu, für jede einzelne Version von Office eine separate Funktion zu erstellen. Sie müssen viel Code duplizieren, wenn Sie es nicht müssten.
Stattdessen benötigen Sie eine Möglichkeit, zur Laufzeit verschiedene Werte zu übergeben, um das Verhalten der Funktion zu ändern. Wie machen Sie das?
Ja! Parameter oder wie es manche Leute nennen, Argumente.
Da wir verschiedene Versionen von Office installieren möchten, ohne den Code jedes Mal zu ändern, müssen Sie dieser Funktion mindestens einen Parameter hinzufügen.
Bevor Sie schnell einen PowerShell-Parameter ausdenken, ist es wichtig, sich zuerst eine Frage zu stellen: „Welche ist die kleinste Änderung oder welche Änderungen erwarten Sie, dass in dieser Funktion vorgenommen werden müssen?“.
Daran denken, dass Sie diese Funktion erneut ausführen müssen, ohne den Code darin zu ändern. In diesem Beispiel ist Ihnen der Parameter wahrscheinlich klar; Sie müssen einen Version-Parameter hinzufügen. Aber wenn Sie eine Funktion mit zehn Zeilen Code haben, wird die Antwort nicht so offensichtlich sein. Solange Sie diese Frage so präzise wie möglich beantworten, wird es immer helfen.
Jetzt wissen Sie, dass Sie einen Version-Parameter benötigen. Und jetzt? Sie können einen hinzufügen, aber wie bei jeder großartigen Programmiersprache gibt es mehrere Möglichkeiten, die Katze zu häuten.
In diesem Tutorial zeige ich Ihnen den „besten“ Weg, Parameter zu erstellen, basierend auf meiner fast zehnjährigen Erfahrung mit PowerShell. Beachten Sie jedoch, dass dies nicht der einzige Weg ist, um einen Parameter zu erstellen.
Es gibt auch sogenannte positionale Parameter. Mit diesen Parametern können Sie Werte an Parameter übergeben, ohne den Parameternamen anzugeben. Positionale Parameter funktionieren, gelten jedoch nicht als „Best Practice“. Warum? Weil sie schwerer lesbar sind, insbesondere wenn Sie viele Parameter in einer Funktion definiert haben.
Erstellen eines einfachen PowerShell-Parameters
Das Erstellen eines Parameters für eine Funktion erfordert zwei Hauptkomponenten: einen Param-Block und den Parameter selbst. Ein Param-Block wird durch das Schlüsselwort param gefolgt von einer Klammergruppe definiert.
An dieser Stelle hat sich die eigentliche Funktionalität der Funktion noch kein bisschen verändert. Wir haben lediglich einige Vorarbeiten geleistet, um uns auf den ersten Parameter vorzubereiten.
Sobald wir den param-Block an Ort und Stelle haben, erstellen Sie nun den Parameter. Die Methode, die ich Ihnen vorschlage, um einen Parameter zu erstellen, umfasst den Parameter-Block, gefolgt vom Typ des Parameters, und darunter folgt der Parameter-Variablenname.
Wir haben nun einen Funktionsparameter in PowerShell erstellt, aber was ist hier genau passiert?
Der Parameter-Block ist ein optionaler, aber empfohlener Bestandteil jedes Parameters. Wie der param-Block ist er eine „Funktionsvorrichtung“, die den Parameter auf die Hinzufügung zusätzlicher Funktionen vorbereitet. In der zweiten Zeile definieren Sie den Typ des Parameters.
In diesem Fall haben wir uns dafür entschieden, den Parameter Version in einen String umzuwandeln. Das explizite Definieren eines Typs bedeutet, dass jeder Wert, der an diesen Parameter übergeben wird, immer versucht wird, in einen String umgewandelt zu werden, falls er dies nicht bereits ist.
Der Typ ist nicht zwingend erforderlich, wird jedoch dringend empfohlen. Durch die explizite Definition des Parametertyps werden viele unerwünschte Situationen in Zukunft erheblich reduziert. Vertrau mir.
Jetzt, da du den Parameter definiert hast, kannst du den Befehl Install-Office mit dem Parameter Version ausführen und ihm eine Versionszeichenkette wie 2013 übergeben. Der Wert, der an den Parameter Version übergeben wird, wird manchmal als Argumente oder Werte für Parameter bezeichnet.
Was passiert hier überhaupt? Du hast angegeben, dass du Version 2013 installieren möchtest, aber es zeigt immer noch an, dass Version 2016 installiert ist. Wenn du einen Parameter hinzufügst, musst du dann daran denken, den Code der Funktion in eine Variable zu ändern. Wenn der Parameter an die Funktion übergeben wird, wird diese Variable erweitert, um den übergebenen Wert anzunehmen.
Ändere den statischen Text von 2016 und ersetze ihn durch die Variable des Parameters Version und konvertiere die einfachen Anführungszeichen in doppelte Anführungszeichen, damit die Variable erweitert wird.
Jetzt kannst du sehen, dass der an den Parameter Version übergebene Wert in die Funktion als Variable $Version übergeben wird.
Das Mandatory Parameter-Attribut.
Denken Sie daran, dass ich erwähnt habe, dass die Zeile [Parameter()] nur „Funktionsplumbing“ war und die Funktion für weitere Arbeiten vorbereitet werden musste? Das Hinzufügen von Parameternattributen zu einem Parameter ist die zusätzliche Arbeit, von der ich zuvor gesprochen habe.
A parameter doesn’t have to be a placeholder for a variable. PowerShell has a concept called parameter attributes and parameter validation. Parameter attributes change the behavior of the parameter in a lot of different ways.
Zum Beispiel ist eines der häufigsten Parameternattribute, die Sie festlegen werden, das Schlüsselwort Mandatory. Standardmäßig könnten Sie die Funktion Install-Office aufrufen, ohne den Version-Parameter zu verwenden, und sie würde einwandfrei ausgeführt werden. Der Version-Parameter wäre optional. Zugegeben, er würde die $Version-Variable in der Funktion nicht erweitern, weil kein Wert vorhanden war, aber sie würde trotzdem ausgeführt werden.
Oftmals möchten Sie, wenn Sie einen Parameter erstellen, dass der Benutzer diesen Parameter immer verwendet. Sie werden vom Wert des Parameters irgendwo im Code der Funktion abhängen, und wenn der Parameter nicht übergeben wird, schlägt die Funktion fehl. In diesen Fällen möchten Sie, dass der Benutzer diesen Parameterwert an Ihre Funktion übergeben muss. Sie möchten, dass dieser Parameter obligatorisch wird.
Das Erzwingen der Verwendung eines Parameters ist einfach, sobald Sie das grundlegende Framework wie hier aufgebaut haben. Sie müssen das Schlüsselwort Mandatory innerhalb der Klammern des Parameters angeben. Sobald Sie das haben, wird die Ausführung der Funktion ohne den Parameter angehalten, bis ein Wert eingegeben wurde.
Die Funktion wartet, bis Sie einen Wert für den Version-Parameter angeben. Sobald Sie dies tun und Enter drücken, wird PowerShell die Funktion ausführen und fortsetzen. Wenn Sie einen Wert für den Parameter angeben, wird PowerShell Sie nicht bei jeder Ausführung nach dem Parameter fragen.
PowerShell-Parametervalidierungsattribute
Das Festlegen eines Parameters als obligatorisch ist eine der häufigsten Parameterattribute, die Sie hinzufügen können, aber Sie können auch Parametervalidierungsattribute verwenden. In der Programmierung ist es immer wichtig, die Benutzereingabe so stark wie möglich einzuschränken. Durch die Begrenzung der Informationen, die Benutzer (oder sogar Sie selbst!) an Ihre Funktionen oder Skripts übergeben können, wird unnötiger Code in Ihrer Funktion vermieden, der für alle möglichen Situationen berücksichtigt werden muss.
Lernen anhand eines Beispiels
Zum Beispiel habe ich in der Funktion Install-Office gezeigt, dass ich den Wert 2013 übergeben kann, weil ich wusste, dass es funktionieren würde. Ich habe den Code geschrieben! Ich gehe davon aus (niemals dies im Code tun!), dass es offensichtlich ist, dass jeder, der etwas weiß, die Version entweder als 2013 oder 2016 angeben würde. Nun, was für Sie offensichtlich ist, ist möglicherweise für andere Personen nicht so offensichtlich.
Wenn Sie es technisch betrachten möchten, wäre es wahrscheinlich genauer, die Version 2013 als 15.0 und 2016 als 16.0 anzugeben, wenn Microsoft das Versionsierungsschema verwendet hätte, das sie in der Vergangenheit verwendet haben. Aber was ist, wenn Sie davon ausgehen, dass sie eine Version von 2013 oder 2016 angeben werden und Sie den Code in der Funktion haben, der nach Ordnern mit diesen Versionen sucht oder etwas anderes macht?
Im Folgenden finden Sie ein Beispiel, in dem Sie möglicherweise den Zeichenfolgenparameter $Version in einem Dateipfad verwenden. Wenn jemand einen Wert übergibt, der keinen Ordner mit dem Namen Office2013 oder Office2016 ergänzt, schlägt dies fehl oder führt etwas Schlimmeres aus, wie das Entfernen unerwarteter Ordner oder das Ändern von Dingen, die Sie nicht berücksichtigt haben.
Um den Benutzer auf das zu beschränken, was Sie von ihm erwarten, können Sie einige PowerShell-Parameterüberprüfungen hinzufügen.
Verwendung des Validierungssatzes des Parameterüberprüfungsattributs
Es gibt verschiedene Arten der Parameterüberprüfung, die Sie verwenden können. Eine vollständige Auflistung finden Sie unter Get-Help about_Functions_Advanced_Parameters. In diesem Beispiel wäre das Attribute ValidateSet wahrscheinlich am besten geeignet.
Das Validierungssatz-Validierungsattribut ermöglicht es Ihnen, eine Liste von Werten anzugeben, die als Parameterwert erlaubt sind. Da wir nur die Zeichenfolge 2013 oder 2016 berücksichtigen, möchte ich sicherstellen, dass der Benutzer nur diese Werte angeben kann. Andernfalls schlägt die Funktion sofort fehl und benachrichtigt den Benutzer darüber, warum.
Sie können Validierungsattribute für Parameter direkt unter dem ursprünglichen Schlüsselwort Parameter hinzufügen. In diesem Beispiel haben Sie innerhalb der Klammern des Parameterattributs ein Array von Elementen; 2013 und 2016. Ein Parameterüberprüfungsattribut teilt PowerShell mit, dass die einzigen gültigen Werte für Version 2013 oder 2016 sind. Wenn Sie etwas anderes als das Set übergeben, erhalten Sie einen Fehler, der Sie darauf hinweist, dass Sie nur eine bestimmte Anzahl von Optionen zur Verfügung haben.
Das Attribut ValidateSet ist ein häufig verwendetes Validierungsattribut. Eine vollständige Übersicht über alle Möglichkeiten, wie Parameterwerte eingeschränkt werden können, finden Sie im Hilfeartikel Functions_Advanced_Parameters, indem Sie Get-Help about_Functions_Advanced_Parameters ausführen.
Parameter-Sets
Angenommen, Sie möchten nur bestimmte PowerShell-Parameter zusammen mit anderen Parametern verwenden. Vielleicht haben Sie einen Path-Parameter zur Funktion Install-Office hinzugefügt. Dieser Pfad installiert die jeweilige Version des Installationsprogramms. In diesem Fall möchten Sie nicht, dass der Benutzer den Version-Parameter verwendet.
Sie benötigen Parameter-Sets.
Parameter können in Sets gruppiert werden, die nur mit anderen Parametern im selben Set verwendet werden können. Mit der folgenden Funktion können Sie nun sowohl den Version-Parameter als auch den Path-Parameter verwenden, um den Pfad zum Installationsprogramm zu ermitteln.
Dies führt jedoch zu einem Problem, da der Benutzer beide Parameter verwenden könnte. Außerdem werden beide Parameter als obligatorisch festgelegt, sodass der Benutzer gezwungen ist, beide zu verwenden, obwohl dies nicht gewünscht ist. Um dies zu beheben, können wir jeden Parameter in einem Parameter-Set platzieren, wie unten gezeigt.
Indem Sie jedem Parameter einen Parameter-Set-Namen zuweisen, können Sie Gruppen von Parametern zusammen kontrollieren.
Das Standard-Parameter-Set
Was passiert, wenn der Benutzer versucht, Install-Office ohne Parameter auszuführen? Dies ist nicht berücksichtigt, und es wird eine freundliche Fehlermeldung angezeigt.
Um dies zu beheben, müssen Sie einen Standardparameter innerhalb des CmdletBinding()-Bereichs definieren. Dadurch wird der Funktion mitgeteilt, welcher Parameter Satz verwendet werden soll, wenn keine expliziten Parameter verwendet wurden. Ändern Sie [CmdletBinding()] in [CmdletBinding(DefaultParameterSetName = 'ByVersion')].
Jetzt, wenn Sie Install-Office ausführen, wird nach dem Version-Parameter gefragt, da dieser Parameter Satz verwendet wird.
Pipeline-Eingabe
In den bisherigen Beispielen haben Sie Funktionen mit einem PowerShell-Parameter erstellt, der nur mit der üblichen Syntax -ParameterName Wert übergeben werden kann. Aber wie Sie bereits gelernt haben, verfügt PowerShell über eine intuitive Pipeline, mit der Sie Objekte nahtlos von einem Befehl an einen anderen übergeben können, ohne die „typische“ Syntax zu verwenden.
Bei Verwendung der Pipeline werden Befehle mit dem Pipe-Symbol | verkettet, sodass ein Benutzer die Ausgabe eines Befehls wie Get-Service an Start-Service weiterleiten kann, um den Name-Parameter an Start-Service zu übergeben.
Der „alte“ Weg mit einer Schleife
In der benutzerdefinierten Funktion, an der Sie arbeiten, installieren Sie Office und haben einen Version-Parameter. Angenommen, Sie haben eine Liste von Computernamen in einer CSV-Datei in einer Zeile und die Version von Office, die auf ihnen installiert werden muss, in der zweiten Zeile. Die CSV-Datei sieht etwa so aus:
Sie möchten die Version von Office auf jedem Computer installieren, die neben diesem Computer steht.
Zuerst müssen Sie einen ComputerName-Parameter zur Funktion hinzufügen, um für jede Iteration der Funktion einen anderen Computernamen zu übergeben. Im folgenden Beispiel habe ich Pseudocode erstellt, der den Code darstellt, der sich möglicherweise in der fiktiven Funktion befindet, und eine Write-Host-Instanz hinzugefügt, um zu sehen, wie sich die Variablen innerhalb der Funktion erweitern.
Sobald Sie den ComputerName-Parameter zur Funktion hinzugefügt haben, könnten Sie dies erreichen, indem Sie die CSV-Datei lesen und die Werte für den Computernamen und die Version an die Funktion Install-Office übergeben.
Erstellen einer Pipeline-Eingabe für Parameter
Diese Methode zum Lesen der CSV-Zeilen und Verwenden einer Schleife, um die Eigenschaften jeder Zeile an die Funktion zu übergeben, ist die „alte“ Methode, dies zu tun. In diesem Abschnitt möchten Sie die foreach-Schleife vollständig umgehen und stattdessen die Pipeline verwenden.
Die Funktion unterstützt die Pipeline nicht. Es wäre intuitiv sinnvoll anzunehmen, dass Sie jeden Computernamen und jede Version mit der Pipeline an die Funktion übergeben könnten. Im folgenden Beispiel lesen wir die CSV und übergeben sie direkt an Install-Office, aber das funktioniert nicht.
Du kannst annehmen, was du willst, aber das macht es nicht automatisch funktionierend. Wir werden zur Eingabe des Version-Parameters aufgefordert, obwohl du weißt, dass Import-Csv es als Objekteigenschaft sendet. Warum funktioniert es nicht? Weil du noch keine Pipeline-Unterstützung hinzugefügt hast.
In einer PowerShell-Funktion gibt es zwei Arten von Pipeline-Eingabe: ByValue (gesamtes Objekt) und ByPropertyName (eine einzelne Objekteigenschaft). Welche Methode denkst du ist der beste Weg, um die Ausgabe von Import-Csv mit der Eingabe von Install-Office zu verbinden?
Ganz ohne Refactoring könntest du die Methode ByPropertyName verwenden, da Import-Csv bereits die Eigenschaften Version und ComputerName zurückgibt, da sie Spalten in der CSV sind.
Die Hinzufügung von Pipeline-Unterstützung zu einer benutzerdefinierten Funktion ist viel einfacher als du denkst. Es handelt sich lediglich um ein Parameterattribut, das mit einem von zwei Schlüsselwörtern repräsentiert wird: ValueFromPipeline oder ValueFromPipelineByPropertyName.
In diesem Beispiel möchtest du die Eigenschaften ComputerName und Version, die von Import-Csv zurückgegeben werden, an die Parameter Version und ComputerName von Install-Office binden, daher verwendest du ValueFromPipelineByPropertyName.
Da du beide dieser Parameter binden möchtest, fügst du dieses Schlüsselwort beiden Parametern wie unten gezeigt hinzu und führe die Funktion erneut mit der Pipeline aus.
Das ist seltsam. Es wurde nur für die letzte Zeile in der CSV ausgeführt. Was passiert? Es wurde die Funktion nur für die letzte Zeile ausgeführt, weil Sie ein Konzept übersprungen haben, das beim Erstellen von Funktionen ohne Pipeline-Unterstützung nicht erforderlich ist.
Vergiss den Prozessblock nicht!
Wenn Sie eine Funktion erstellen müssen, die die Pipeline-Unterstützung verwendet, müssen Sie mindestens einen „eingebetteten“ Block in Ihrer Funktion namens process hinzufügen. Dieser Prozessblock gibt PowerShell an, dass die Funktion für jede Iteration ausgeführt werden soll, wenn Eingabe über die Pipeline empfangen wird. Standardmäßig wird nur die letzte ausgeführt.
Sie könnten technisch gesehen auch andere Blöcke wie begin und end hinzufügen, aber Skripter verwenden sie bei weitem nicht so oft.
Um PowerShell mitzuteilen, diese Funktion für jedes Objekt auszuführen, füge ich einen process-Block hinzu, der den darin enthaltenen Code enthält.
Jetzt sehen Sie, dass die Version– und ComputerName-Eigenschaften jedes Objekts, die von Import-Csv zurückgegeben wurden, an Install-Office übergeben und an die Parameter Version und ComputerName gebunden wurden.
Ressourcen
Um mehr darüber zu erfahren, wie Funktionen in PowerShell funktionieren, lesen Sie meinen Blogbeitrag über PowerShell-Funktionen.
I also encourage you to check my Pluralsight course entitled Building Advanced PowerShell Functions and Modules for an in-depth breakdown of everything there is to know about PowerShell functions, function parameters, and PowerShell modules.