THEMA
about_Functions
KURZBESCHREIBUNG
Beschreibt das Erstellen und Verwenden von Funktionen in Windows
PowerShell.
DETAILBESCHREIBUNG
Eine 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)