Beschreibt das Erstellen und Verwenden von Funktionen in Windows (about_functions)
THEMAabout_FunctionsKURZBESCHREIBUNGBeschreibt das Erstellen und Verwenden von Funktionen in Windows PowerShell.DETAILBESCHREIBUNGEine Funktion besteht aus einer Liste von Anweisungen, der Sie einen Namen zugewiesen haben. Wenn Sie eine Funktion ausführen möchten, geben Sie den Funktionsnamen ein. Die Anweisungen in der Liste werden wie bei Eingabe an der Eingabeaufforderung ausgeführt. Ähnlich wie Cmdlets können Funktionen über Parameter verfügen. Bei den Parametern kann es sich um benannte, Positions-, Options- oder dynamische Parameter handeln. Funktionsparameter können in der Befehlszeile oder in der Pipeline gelesen werden. Funktionen können Werte zurückgeben, die angezeigt, Variablen zugewiesen oder an andere Funktionen oder Cmdlets übergeben werden können. Die Anweisungsliste der Funktion kann andere Typen von Anweisungslisten mit den Schlüsselwörtern Begin, Process und End enthalten. Diese Anweisungslisten behandeln die Eingabe aus der Pipeline anders. Ein Filter bildet eine besondere Art von Funktion, für die das Filter- Schlüsselwort verwendet wird. Funktionen können auch wie Cmdlets verwendet werden. Sie können Funktionen, die wie ein Cmdlet verwendet werden, ohne C#-Programmierung erstellen. Weitere Informationen finden Sie unter "about_Functions_Advanced". Syntax Für Funktionen wird die folgende Syntax verwendet: function [<Bereich:>]<name> [([type]$parameter1[,[type]$parameter2])] { param([type]$parameter1 [,[type]$parameter2]) dynamicparam {<Anweisungsliste>} begin {<Anweisungsliste>} process {<Anweisungsliste>} end {<Anweisungsliste>} } Eine Funktion besteht aus den folgenden Elementen: - Ein Function-Schlüsselwort - Einen Bereich (optional) - Einen von Ihnen ausgewählten Namen - Eine beliebige Anzahl benannter Parameter (optional) - Einen oder mehrere in geschweifte Klammern ({}) eingeschlossene Windows PowerShell-Befehle Weitere Informationen zum Dynamicparam-Schlüsselwort und zu dynamischen Parametern in Funktionen finden Sie unter "about_Functions_Advanced_Parameters". Einfache Funktionen Funktionen müssen nicht kompliziert sein, um nützlich zu sein. Mit der folgenden Funktion werden die Umgebungsvariablen abgerufen, die nicht zum Systemkonto des aktuellen Systems gehören: function other_env { get-wmiObject win32_environment | where {$_.username -ne "<System>"} } Zum Ausführen der Funktion geben Sie "other_env" ein. Sie können eine Toolbox mit nützlichen kleinen Funktionen erstellen. Fügen Sie diese Funktionen dem Windows PowerShell-Profil hinzu, wie unter "about_Profiles" und weiter unten in diesem Thema beschrieben. Funktionen mit Parametern Sie können Parameter mit Funktionen verwenden, u. a. benannte Parameter, Positionsparameter, Schalterparameter und dynamische Parameter. Weitere Informationen zu dynamischen Parametern in Funktionen finden Sie unter "about_Functions_Advanced_Parameters". Benannte Parameter Sie können eine beliebige Anzahl benannter Parameter definieren. Sie können einen Standardwert für benannte Parameter einfügen, wie weiter unten in diesem Thema beschrieben. Sie können Parameter in den geschweiften Klammern mit dem Param-Schlüsselwort definieren, wie in der folgenden Beispielsyntax angezeigt: function <name> { param ([type]$parameter1[,[type]$parameter2]) <statement list> } Sie können auch Parameter außerhalb der geschweiften Klammern und ohne das Param-Schlüsselwort definieren, wie in der folgenden Beispielsyntax gezeigt wird: function <Name> [([type]$parameter1[,[type]$parameter2])] { <Anweisungsliste> } Zwischen beiden Methoden besteht kein Unterschied. Verwenden Sie die Methode, die Sie vorziehen. Wenn Sie die Funktion ausführen, wird einer Variable mit dem Parameternamen der für einen Parameter angegebene Wert zugewiesen. Der Wert dieser Variable kann in der Funktion verwendet werden. Das folgende Beispiel stellt die Funktion "Small_files" dar. Diese Funktion verfügt über einen $size-Parameter. Mit der Funktion werden alle Dateien angezeigt, die kleiner als der Wert des $size-Parameters sind, zudem werden Verzeichnisse ausgeschlossen: function small_files { param ($size) Get-ChildItem c:\ | where { $_.length -lt $size -and !$_.PSIsContainer} } In der Funktion können Sie die $size-Variable verwenden, die den für den Parameter definierten Namen darstellt. Zum Verwenden dieser Funktion geben Sie den folgenden Befehl ein: C:\PS> function small_files -size 50 Sie können einen Wert für einen benannten Parameter auch ohne den Parameternamen eingeben. Der folgende Befehl ergibt z. B. das gleiche Ergebnis wie ein Befehl, in dem der Size-Parameter genannt wird: C:\PS> function small_files 50 Um einen Standardwert für einen Parameter zu definieren, geben Sie nach dem Parameternamen ein Gleichheitszeichen und den Wert ein, wie in der folgenden Variante des Small_files-Beispiels gezeigt: function small_files ($size = 100) { Get-ChildItem c:\ | where { $_.length -lt $size -and !$_.PSIsContainer} } Wenn Sie "small_files" ohne Wert eingeben, wird $size von der Funktion der Wert 100 zugewiesen. Wenn Sie einen Wert geben, wird dieser von der Funktion verwendet. Positionsparameter Als Positionsparameter werden Parameter ohne Parameternamen bezeichnet. In Windows PowerShell wird mit dem Parameterwertbefehl jedem Parameterwert in der Funktion ein Parameter zugeordnet. Wenn Sie Positionsparameter verwenden, geben Sie nach dem Funktionsnamen einen oder mehrere Werte ein. Die Positionsparame- terwerte werden der Arrayvariablen "$args" zugewiesen. Der Wert nach dem Funktionsnamen wird der ersten Position im $args-Array zugewiesen, d. h. "$args [0]". Mit der folgenden Extension-Funktion wird die Dateinamenerwei- terung ".txt" einem von Ihnen angegebenen Dateinamen hinzugefügt: function extension { $name = $args[0] + ".txt" $name } C:\PS> extension meineTextdatei meineTextdatei.txt Funktionen können mehrere Positionsparameter annehmen. Im folgenden Beispiel werden alle mit dem Funktionsnamen eingegebenen Werte angezeigt. function repeat { foreach ($arg in $args) { "Die Eingabe ist $arg" } } C:\PS>repeat eins Die Eingabe ist eins C:\PS> repeat eins zwei drei Die Eingabe ist eins Die Eingabe ist zwei Die Eingabe ist drei Diese Funktion kann mit einer beliebigen Anzahl von Werten verwendet werden. Die Funktion weist jeden Wert einer Position im $args-Array zu. Schalterparameter Als Schalter wird ein Parameter bezeichnet, der keinen Wert erfordert. Stattdessen geben Sie den Funktionsnamen und danach den Namen des Schalterparameters ein. Wenn Sie einen Schalterparameter definieren möchten, geben Sie den Typ [switch] vor dem Parameternamen an, wie im folgenden Beispiel gezeigt: function switchBeispiel { param ([switch]$on) if ($on) { "Schalter ein" } else { "Schalter aus" } } Wenn Sie den On-Schalterparameter nach dem Funktionsnamen eingeben, wird von der Funktion "Schalter ein" angezeigt. Ohne den Schalterparameter wird "Schalter aus" angezeigt. C:\PS> SwitchBeispiel -on Schalter ein C:\PS> SwitchBeispiel Schalter aus Sie können beim Ausführen der Funktion einem Schalter auch einen booleschen Wert zuweisen, wie im folgenden Beispiel gezeigt: C:\PS> SwitchBeispiel -on:$true Schalter ein C:\PS> SwitchBeispiel -on:$false Schalter aus Übergeben von Objekten über die Pipeline an Funktionen Jede Funktion kann Eingaben von der Pipeline akzeptieren. Mit den Schlüsselwörtern Begin, Process und End können Sie bestimmen, wie eine Funktion Eingaben von der Pipeline verarbeitet. Die drei Schlüsselwörter werden in der folgenden Beispielsyntax gezeigt: function <Name> { begin {<Anweisungsliste>} process {<Anweisungsliste>} end {<Anweisungsliste>} } Die Begin-Anweisungsliste wird nur einmal, am Anfang der Funktion, ausgeführt. Die Process-Anweisungsliste wird einmal für jedes Objekt in der Pipeline ausgeführt. Während der Process-Block ausgeführt wird, wird der automatischen Variable "$_" jedes Pipelineobjekt einzeln zugewiesen. Wenn die Funktion alle Objekte in der Pipeline empfangen hat, wird die End-Anweisungsliste einmal ausgeführt. Wenn die Schlüsselwörter Begin, Process oder End nicht verwendet werden, werden alle Anweisungen wie eine End-Anweisungsliste behandelt. Für die folgende Funktion wird das Process-Schlüsselwort verwendet. Die Funktion zeigt Beispiele aus der Pipeline an: function pipelineFunktion { process {"Der Wert ist: $_"} } Zur Veranschaulichung dieser Funktion geben Sie ein mit Kommas erstelltes Array von Zahlen ein, wie im folgenden Beispiel gezeigt: C:\PS> 1,2,4 | pipelineFunktion Der Wert ist: 1 Der Wert ist: 2 Der Wert ist: 4 Wenn Sie eine Funktion in einer Pipeline verwenden, werden die über die Pipeline an die Funktion übergebenen Objekte der automatischen Variablen "$input" zugewiesen. Anweisungen mit dem Begin-Schlüsselwort werden vor sämtlichen Objekten aus der Pipeline ausgeführt. Anweisungen mit dem End-Schlüsselwort werden nach sämtlichen Objekten aus der Pipeline ausgeführt. Das folgende Beispiel veranschaulicht die automatische Variable "$input" mit dem Begin-Schlüsselwort und dem End-Schlüsselwort. function PipelineBeginEnd { begin {"Begin: Die Eingabe ist $input"} end {"End: Die Eingabe ist $input" } } Wenn diese Funktion über die Pipeline ausgeführt wird, werden die folgenden Ergebnisse angezeigt: C:\PS> 1,2,4 | PipelineBeginEnd Begin: Die Eingabe ist End: Die Eingabe ist 1 2 4 Wenn die Begin-Anweisung ausgeführt wird, liegt der Funktion die Eingabe von der Pipeline nicht vor. Die End-Anweisung wird ausgeführt, wenn der Funktion die Werte vorliegen. Wenn die Funktion ein Process-Schlüsselwort aufweist, liest die Funktion die Daten in $input. Das folgende Beispiel enthält eine Process-Anweisungsliste: function PipelineEingabe { process {"Verarbeiten: $_ " } end {"End: Die Eingabe ist: $input" } } In diesem Beispiel wird jedes Objekt, das über die Pipeline an die Funktion übergeben wird, an die Process-Anweisungsliste gesendet. Der Process-Anweisung wird für jedes Objekt einzeln ausgeführt. Wenn die Funktion das End-Schlüsselwort erreicht, ist die automatische Variable "$input" leer. C:\PS> 1,2,4 | PipelineEingabe Verarbeiten: 1 Verarbeiten: 2 Verarbeiten: 4 End: Die Eingabe ist: Filter Als Filter wird ein bestimmter Typ von Funktion bezeichnet, der für jedes Objekt in der Pipeline ausgeführt wird. Filtern ähneln Funktionen, bei denen sich alle Anweisungen in einem Process-Block befinden. Für Filter wird die folgende Syntax verwendet: filter [<Bereich:>]<name> {<Anweisungsliste>} Mit dem folgenden Filter werden Protokolleinträge aus der Pipeline als vollständige Einträge oder als Meldungsteil des jeweiligen Eintrags angezeigt: filter ErrorLog ([switch]$message) { if ($message) { out-host -inputobject $_.Message } else { $_ } } Funktionsbereich Eine Funktion gehört dem Bereich an, in dem sie erstellt wurde. Wenn eine Funktion ein Teil eines Skripts ist, steht sie Anweisungen in diesem Skript zur Verfügung. Standardmäßig sind Funktionen in Skripts an der Eingabeaufforderung nicht verfügbar. Sie können den Bereich einer Funktion festlegen. Im folgenden Beispiel wird die Funktion dem globalen Bereich hinzugefügt: function global:get-dependentsvs { get-service | where {$_.dependentservices} } Wenn sich eine Funktion im globalen Bereich befindet, können Sie sie in Skripts, in Funktionen und in der Befehlszeile verwenden. Von Funktionen wird in der Regel ein Bereich erstellt. Die in einer Funktion erstellten Elemente, z. B. Variablen, sind nur im Bereich der Funktion vorhanden. Weitere Informationen zu Bereichen in Windows PowerShell finden Sie unter "about_Scope". Suchen und Verwalten von Funktionen mit dem Laufwerk "Function:" - Alle Funktionen und Filter in Windows PowerShell werden automatisch auf dem Laufwerk "Function:" gespeichert. Dieses Laufwerk wird vom Windows PowerShell-Funktionsanbieter verfügbar gemacht. Bei Verweisen auf das Laufwerk "Function:" geben Sie wie beim Verweisen auf das Laufwerk "C" oder "D" eines Computers nach "Function" einen Doppelpunkt ein. Mit dem folgenden Befehl werden alle Funktionen in der aktuellen Sitzung von Windows PowerShell angezeigt: C:\PS> dir function: Die Befehle in der Funktion werden als Skriptblock in der Definitionseigenschaft der Funktion gespeichert. Wenn Sie beispielsweise die Befehle in der Hilfefunktion von Windows PowerShell anzeigen möchten, geben Sie Folgendes ein: (dir function:help).definition Weitere Informationen über das Laufwerk "Function:" finden Sie unter "Function". Wiederverwenden von Funktionen in neuen Sitzungen Wenn Sie an der Windows PowerShell-Eingabeaufforderung eine Funktion eingeben, wird die Funktion Teil der aktuellen Sitzung. Sie ist bis zum Sitzungsende verfügbar. Wenn Sie die Funktion in allen Windows PowerShell-Sitzungen verwenden möchten, fügen Sie sie dem Windows PowerShell-Profil hinzu. Weitere Informationen zu Profilen finden Sie unter "about_Profiles". Sie können die Funktion auch in einer Windows PowerShell-Skript- datei speichern. Geben Sie die Funktion in einer Textdatei ein, und speichern Sie die Datei dann mit der Dateinamenerweiterung ".ps1". Erstellen von Hilfe für Funktionen Mit dem Cmdlet "Get-Help" rufen Sie die Hilfe für Funktionen sowie für Cmdlets, Anbieter und Skripts ab. Zum Abrufen von Hilfe für eine Funktion geben Sie Get-Help und dann den Funktionsnamen ein. Beispielsweise geben Sie Folgendes ein, um Hilfe für die MyDisks-Funktion zu erhalten: get-help MyDisks Hilfe für eine Funktion können Sie mit den beiden folgenden Methoden erstellen: -- Kommentarbasierte Hilfe für Funktionen Erstellen Sie ein Hilfethema, indem Sie in den Kommentaren spezielle Schlüsselwörter verwenden. Wenn Sie für eine Funktion kommentarbasierte Hilfe erstellen, müssen die Kommentare am Anfang oder am Ende des Funktionstexts oder in den Zeilen vor dem Funktionsschlüsselwort platziert werden. Weitere Informationen zur kommentarbasierten Hilfe finden Sie unter "about_Comment_Based_Help". -- XML-basierte Hilfe für Funktionen Sie können XML-basierte Hilfethemen erstellen, z. B. zu dem Typ, der in der Regel für Cmdlets erstellt wird. XML-basierte Hilfe muss erstellt werden, wenn Sie Hilfethemen in mehrere Sprachen lokalisieren. Um ein XML-basiertes Hilfethema der Funktion zuzuordnen, verwenden Sie das .ExternalHelp-Schlüsselwort für den Hilfekommentar. Weitere Informationen zum ExternalHelp- Schlüsselwort finden Sie unter "about_Comment_Based_Help". Weitere Informationen zur XML-basierten Hilfe finden Sie auf MSDN im Thema zum Verfassen von Cmdlet-Hilfe. SIEHE AUCH about_Automatic_Variables about_Comment_Based_Help about_Functions_Advanced about_Functions_CmdletBindingAttributes about_Parameters about_Profiles about_Scopes about_Script_Blocks Funktion (Anbieter) C:\Windows>powershell get-help about_functions_advanced -full
Microsoft Windows [Version 10.0.19045.3693]
Copyright (c) 2023 Microsoft Corporation.
ColorConsole [Version 3.7.1000] PowerShell 2.0-Export
