Sie sind auf Seite 1von 9

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 ausfhren
mchten, geben Sie den Funktionsnamen ein. Die Anweisungen in der
Liste werden wie bei Eingabe an der Eingabeaufforderung ausgefhrt.
hnlich wie Cmdlets knnen Funktionen ber Parameter verfgen. Bei den
Parametern kann es sich um benannte, Positions-, Options- oder
dynamische Parameter handeln. Funktionsparameter knnen in der
Befehlszeile oder in der Pipeline gelesen werden.
Funktionen knnen Werte zurckgeben, die angezeigt, Variablen
zugewiesen oder an andere Funktionen oder Cmdlets bergeben
werden knnen.
Die Anweisungsliste der Funktion kann andere Typen von
Anweisungslisten mit den Schlsselwrtern Begin, Process und End
enthalten. Diese Anweisungslisten behandeln die Eingabe aus der
Pipeline anders.
Ein Filter bildet eine besondere Art von Funktion, fr die das Filter-
Schlsselwort verwendet wird.
Funktionen knnen auch wie Cmdlets verwendet werden. Sie knnen
Funktionen, die wie ein Cmdlet verwendet werden, ohne
C#-Programmierung erstellen. Weitere Informationen finden Sie unter
"about_Functions_Advanced".
Syntax
Fr 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-Schlsselwort
- Einen Bereich (optional)
- Einen von Ihnen ausgewhlten Namen
- Eine beliebige Anzahl benannter Parameter (optional)
- Einen oder mehrere in geschweifte Klammern ({})
eingeschlossene Windows PowerShell-Befehle
Weitere Informationen zum Dynamicparam-Schlsselwort und zu
dynamischen Parametern in Funktionen finden Sie unter
"about_Functions_Advanced_Parameters".
Einfache Funktionen
Funktionen mssen nicht kompliziert sein, um ntzlich zu sein.
Mit der folgenden Funktion werden die Umgebungsvariablen
abgerufen, die nicht zum Systemkonto des aktuellen Systems gehren:
function other_env
{
get-wmiObject win32_environment |
where {$_.username -ne "<System>"}
}
Zum Ausfhren der Funktion geben Sie "other_env" ein.
Sie knnen eine Toolbox mit ntzlichen kleinen Funktionen
erstellen. Fgen Sie diese Funktionen dem Windows
PowerShell-Profil hinzu, wie unter "about_Profiles" und weiter
unten in diesem Thema beschrieben.
Funktionen mit Parametern
Sie knnen 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 knnen eine beliebige Anzahl benannter Parameter
definieren. Sie knnen einen Standardwert fr benannte
Parameter einfgen, wie weiter unten in diesem Thema beschrieben.
Sie knnen Parameter in den geschweiften Klammern mit dem
Param-Schlsselwort definieren, wie in der folgenden
Beispielsyntax angezeigt:

function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
Sie knnen auch Parameter auerhalb der geschweiften Klammern
und ohne das Param-Schlsselwort 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 ausfhren, wird einer Variable mit dem
Parameternamen der fr 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 verfgt 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 knnen Sie die $size-Variable verwenden, die
den fr den Parameter definierten Namen darstellt.
Zum Verwenden dieser Funktion geben Sie den folgenden Befehl ein:

C:\PS> function small_files -size 50
Sie knnen einen Wert fr 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 fr 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 hinzugefgt:
function extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> extension meineTextdatei
meineTextdatei.txt

Funktionen knnen 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 mchten, 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 knnen beim Ausfhren 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
Schlsselwrtern Begin, Process und End knnen Sie bestimmen, wie
eine Funktion Eingaben von der Pipeline verarbeitet. Die drei
Schlsselwrter werden in der folgenden Beispielsyntax gezeigt:
function <Name> {
begin {<Anweisungsliste>}
process {<Anweisungsliste>}
end {<Anweisungsliste>}
}
Die Begin-Anweisungsliste wird nur einmal, am Anfang der
Funktion, ausgefhrt.
Die Process-Anweisungsliste wird einmal fr jedes Objekt in der
Pipeline ausgefhrt.
Whrend der Process-Block ausgefhrt wird, wird der
automatischen Variable "$_" jedes Pipelineobjekt einzeln
zugewiesen.
Wenn die Funktion alle Objekte in der Pipeline empfangen hat,
wird die End-Anweisungsliste einmal ausgefhrt. Wenn die
Schlsselwrter Begin, Process oder End nicht verwendet werden,
werden alle Anweisungen wie eine End-Anweisungsliste behandelt.
Fr die folgende Funktion wird das Process-Schlsselwort
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-Schlsselwort werden vor smtlichen Objekten aus der
Pipeline ausgefhrt. Anweisungen mit dem End-Schlsselwort
werden nach smtlichen Objekten aus der Pipeline ausgefhrt.
Das folgende Beispiel veranschaulicht die automatische Variable
"$input" mit dem Begin-Schlsselwort und dem End-Schlsselwort.
function PipelineBeginEnd
{
begin {"Begin: Die Eingabe ist $input"} end {"End: Die
Eingabe ist $input" }
}
Wenn diese Funktion ber die Pipeline ausgefhrt 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 ausgefhrt wird, liegt der Funktion
die Eingabe von der Pipeline nicht vor. Die End-Anweisung wird
ausgefhrt, wenn der Funktion die Werte vorliegen.
Wenn die Funktion ein Process-Schlsselwort aufweist, liest die
Funktion die Daten in $input. Das folgende Beispiel enthlt
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 fr jedes Objekt einzeln
ausgefhrt. Wenn die Funktion das End-Schlsselwort 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
fr jedes Objekt in der Pipeline ausgefhrt wird. Filtern
hneln Funktionen, bei denen sich alle Anweisungen in einem
Process-Block befinden.
Fr Filter wird die folgende Syntax verwendet:
filter [<Bereich:>]<name> {<Anweisungsliste>}
Mit dem folgenden Filter werden Protokolleintrge aus der
Pipeline als vollstndige Eintrge oder als Meldungsteil des
jeweiligen Eintrags angezeigt:
filter ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message } else
{ $_ }
}
Funktionsbereich
Eine Funktion gehrt dem Bereich an, in dem sie erstellt wurde.
Wenn eine Funktion ein Teil eines Skripts ist, steht sie
Anweisungen in diesem Skript zur Verfgung. Standardmig sind
Funktionen in Skripts an der Eingabeaufforderung nicht verfgbar.
Sie knnen den Bereich einer Funktion festlegen. Im folgenden
Beispiel wird die Funktion dem globalen Bereich hinzugefgt:

function global:get-dependentsvs { get-service |
where {$_.dependentservices} }
Wenn sich eine Funktion im globalen Bereich befindet, knnen
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 verfgbar 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 mchten, 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 verfgbar.
Wenn Sie die Funktion in allen Windows PowerShell-Sitzungen
verwenden mchten, fgen Sie sie dem Windows PowerShell-Profil
hinzu. Weitere Informationen zu Profilen finden Sie unter
"about_Profiles".
Sie knnen 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 fr Funktionen
Mit dem Cmdlet "Get-Help" rufen Sie die Hilfe fr Funktionen
sowie fr Cmdlets, Anbieter und Skripts ab. Zum Abrufen von Hilfe
fr eine Funktion geben Sie Get-Help und dann den Funktionsnamen ein.
Beispielsweise geben Sie Folgendes ein, um Hilfe fr die
MyDisks-Funktion zu erhalten:
get-help MyDisks
Hilfe fr eine Funktion knnen Sie mit den beiden folgenden
Methoden erstellen:
-- Kommentarbasierte Hilfe fr Funktionen
Erstellen Sie ein Hilfethema, indem Sie in den Kommentaren
spezielle Schlsselwrter verwenden. Wenn Sie fr eine
Funktion kommentarbasierte Hilfe erstellen, mssen die
Kommentare am Anfang oder am Ende des Funktionstexts oder in
den Zeilen vor dem Funktionsschlsselwort platziert werden.
Weitere Informationen zur kommentarbasierten Hilfe finden Sie
unter "about_Comment_Based_Help".
-- XML-basierte Hilfe fr Funktionen
Sie knnen XML-basierte Hilfethemen erstellen, z. B. zu dem
Typ, der in der Regel fr 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-Schlsselwort fr den
Hilfekommentar. Weitere Informationen zum ExternalHelp-
Schlsselwort 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)