about_Functions
Letzte Aktualisierung: Mai 2014
Betrifft: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
THEMA
about_Functions
KURZE BESCHREIBUNG
Erläutert das Erstellen und Verwenden von Funktionen in Windows PowerShell®.
LANGE BESCHREIBUNG
Eine Funktion ist eine Liste von Windows PowerShell-Anweisungen, die einen Namen trägt, den Sie zuweisen. Wenn Sie eine Funktion ausführen, geben Sie den Namen der Funktion ein. Die Anweisungen in der Liste werden so ausgeführt, als hätten Sie sie an der Eingabeaufforderung eingegeben.
Funktionen können einfach sein:
function Get-PowerShellProcess {Get-Process PowerShell}
oder so komplex wie ein Cmdlet oder ein Anwendungsprogramm.
Wie Cmdlets können Funktionen über Parameter verfügen. Es gibt benannte Parameter, Positionsparameter, Switch-Parameter oder dynamische Parameter. Funktionsparameter können aus der Befehlszeile oder der Pipeline gelesen werden.
Funktionen können Werte zurückgeben, die angezeigt, Variablen zugewiesen oder anderen Funktionen oder Cmdlets übergeben werden können.
Die Anweisungsliste der Funktion kann verschiedene Typen von Anweisungslisten mit den Schlüsselwörtern „Begin“, „Process“ und „End“ enthalten. Diese Anweisungslisten behandeln die Eingabe aus der Pipeline unterschiedlich.
Ein Filter ist eine besondere Art von Funktion, die das Schlüsselwort „Filter“ verwendet.
Funktionen können auch wie Cmdlets funktionieren. Sie können ohne C#-Programmierung eine Funktion erstellen, die genau wie ein Cmdlet funktioniert. Weitere Informationen finden Sie unter „about_Functions_Advanced“ (https://go.microsoft.com/fwlink/?LinkID=144511).
Syntax
Die Syntax für eine Funktion lautet:
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
Eine Funktion enthält die folgenden Elemente:
- A Function keyword
- A scope (optional)
- A name that you select
- Any number of named parameters (optional)
- One or more Windows PowerShell commands enclosed in braces ({})
Weitere Informationen über das Dynamicparam-Schlüsselwort und dynamische Parameter in Funktionen finden Sie unter „about_Functions_Advanced_Parameters“.
Einfache Funktionen
Funktionen müssen nicht kompliziert sein, um nützlich zu sein. Die einfachsten Funktionen haben folgendes Format:
function <function-name> {statements}
Die folgende Funktion beispielsweise startet Windows PowerShell mit der Option „Als Administrator ausführen“.
function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}
Um die Funktion zu verwenden, geben Sie Folgendes ein: Start-PSAdmin
Um der Funktion Anweisungen hinzuzufügen, verwenden Sie ein Semikolon (;), um die Anweisungen zu trennen, oder geben Sie jede Anweisung in einer eigenen Zeile ein.
Die folgende Funktion findet z. B. in den Verzeichnissen des aktuellen Benutzers alle JPG-Dateien, die nach dem Startdatum geändert wurden.
function Get-NewPix
{
$start = Get-Date -Month 1 -Day 1 -Year 2010
$allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
$allpix | where {$_.LastWriteTime -gt $Start}
}
Sie können eine Toolbox mit nützlichen kleinen Funktionen erstellen. Fügen Sie diese Funktionen Ihrem Windows PowerShell-Profil hinzu, wie in „about_Profiles“ und später in diesem Thema beschrieben.
Funktionsnamen
Sie können einer Funktion jeden beliebigen Namen zuweisen, doch Funktionen, die Sie mit anderen gemeinsam nutzen, sollten Benennungsregeln entsprechen, die für alle Windows PowerShell-Befehle festgelegt wurden.
Funktionsnamen sollten aus einem Verb-Substantiv-Paar bestehen, in dem das Verb die Aktion identifiziert, die die Funktion ausführt, und das Substantiv das Element, an dem das Cmdlet die Aktion ausführt.
Funktionen sollten die Standardverben verwenden, die für alle Windows PowerShell-Befehle genehmigt sind. Diese Verben helfen Ihnen, Befehlsnamen einfach, konsistent und für Benutzer leichtverständlich zu halten.
Weitere Informationen zu den Standardverben von Windows PowerShell finden Sie bei MSDN unter https://go.microsoft.com/fwlink/?LinkID=160773 in „Cmdlet-Verben“.
FUNKTIONEN MIT PARAMETERN
Sie können Parameter einschließlich benannter Parameter, Positionsparameter, Switch-Parameter und dynamischer Parameter mit Funktionen verwenden. Weitere Informationen zu dynamischen Parametern in Funktionen finden Sie unter „about_Functions_Advanced_Parameters“ (https://go.microsoft.com/fwlink/?LinkID=135173).
Benannte Parameter
Sie können eine beliebige Anzahl von benannten Parametern definieren. Sie können einen Standardwert für die benannten Parameter einbeziehen, wie weiter unten in diesem Thema beschrieben.
Sie können Parameter innerhalb der geschweiften Klammern, mit dem Schlüsselwort „Param“ definieren, wie in der folgenden Beispielsyntax dargestellt:
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
Sie können auch Parameter außerhalb der geschweiften Klammern ohne das Schlüsselwort „Param“ definieren, wie in der folgenden Beispielsyntax dargestellt:
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
Es gibt keinen Unterschied zwischen diesen beiden Methoden. Verwenden Sie die Methode, die Sie bevorzugen.
Beim Ausführen der Funktion wird der Wert, den Sie für einen Parameter angeben, einer Variablen zugewiesen, die den Parameternamen enthält. Der Wert dieser Variablen kann in der Funktion verwendet werden.
Im folgenden Beispiel wird eine Funktion namens „Get-SmallFiles“ aufgerufen. Diese Funktion hat einen $size-Parameter. Die Funktion zeigt alle Dateien an, die kleiner als der Wert des Parameters „$size“ sind, und schließt Verzeichnisse aus:
function Get-SmallFiles {
param ($size)
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
In der Funktion können Sie die $size-Variable verwenden, die den Namen für den Parameter definiert.
Um diese Funktion zu verwenden, geben Sie den folgenden Befehl ein:
C:\PS> function Get-SmallFiles –Size 50
Sie können auch einen Wert für einen benannten Parameter ohne den Parameternamen eingeben. Beispielsweise gibt der folgende Befehl das gleiche Ergebnis zurück wie ein Befehl, der den Size-Parameter benennt:
C:\PS> function Get-SmallFiles 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 Variation des Get-SmallFiles-Beispiels gezeigt:
function Get-SmallFiles ($size = 100) {
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
Wenn Sie „Get-SmallFiles“ ohne Wert eingeben, weist die Funktion „$size“ den Wert 100 zu. Wenn Sie einen Wert angeben, verwendet die Funktion diesen Wert.
Optional können Sie eine kurze Hilfezeichenfolge bereitstellen, die den Standardwert des Parameters angibt, indem Sie das PSDefaultValue-Attribut der Beschreibung des Parameters hinzufügen und die Help-Eigenschaft von „PSDefaultValue“ angeben. Um eine Hilfezeichenfolge bereitzustellen, die den Standardwert (100) des Size-Parameters in der Get-SmallFiles-Funktion beschreibt, fügen Sie das PSDefaultValue-Attribut hinzu, wie im folgenden Beispiel gezeigt.
function Get-SmallFiles {
param (
[PSDefaultValue(Help = '100')]
$size = 100
)
Weitere Informationen über die Attributklasse „PSDefaultValue“ finden Sie bei MSDN unter „PSDefaultValue-Attributelemente“. (https://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute\_members(v=vs.85).aspx)
Positionsparameter
Ein Positionsparameter ist ein Parameter ohne Parameternamen. Windows PowerShell nutzt die Reihenfolge der Parameterwerte, um jeden Parameterwert mit einem Parameter in der Funktion zu verknüpfen.
Wenn Sie Positionsparameter verwenden, geben Sie einen oder mehrere Werte nach dem Funktionsnamen ein. Positionsparameterwerte werden der $args-Arrayvariablen zugewiesen. Der Wert, der auf den Namen der Funktion folgt, wird der ersten Position im Array „$args“ zugewiesen, „$args [0]“.
Die folgende Get-Extension-Funktion fügt einem von Ihnen angegebenen Dateinamen die Dateinamenerweiterung „.txt“ hinzu:
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> Get-Extension myTextFile
myTextFile.txt
SWITCH-PARAMETER
Ein Switch ist ein Parameter, der keinen Wert benötigt. Stattdessen geben Sie den Funktionsnamen ein, gefolgt vom Namen des Switch-Parameters.
Um einen Switch-Parameter zu definieren, geben Sie „[switch]“ vor dem Parameternamen ein, wie im folgenden Beispiel gezeigt:
function Switch-Item {
param ([switch]$on)
if ($on) { "Switch on" }
else { "Switch off" }
}
Bei Eingabe des Switch-Parameters „On“ nach dem Funktionsnamen zeigt die Funktion „Switch on“ an. Ohne Switch-Parameter wird „Switch off“ angezeigt.
C:\PS> Switch-Item -on
Switch on
C:\PS> Switch-Item
Switch off
Sie können einem Switch auch beim Ausführen der Funktion einen booleschen Wert zuweisen, wie im folgenden Beispiel gezeigt:
C:\PS> Switch-Item -on:$true
Switch on
C:\PS> Switch-Item -on:$false
Switch off
Verwendung von Splatting zur Darstellung der Befehlsparameter
Mit Splatting können Sie die Parameter für einen Befehl darstellen. Dieses Feature wurde in Windows PowerShell 3.0 eingeführt.
Verwenden Sie diese Technik in Funktionen, die Befehle in der Sitzung aufrufen. Sie müssen die Befehlsparameter nicht deklarieren oder aufzählen, bzw. die Funktion ändern, wenn sich Befehlsparameter ändern.
Die folgende Beispielfunktion ruft das Get-Command-Cmdlet auf. Der Befehl verwendet „@Args“, um die Parameter von „Get-Command“ darzustellen.
function Get-MyCommand { Get-Command @Args }
Sie können alle Parameter von Get-Command verwenden, wenn Sie die Get-MyCommand-Funktion aufrufen. Die Parameter und Parameterwerte werden mit „@Args“ dem Befehl übergeben.
PS C:\>Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Get-ChildItem Microsoft.PowerShell.Management
Das Feature „@Args“ verwendet den automatischen $Args-Parameter, der nicht deklarierte Cmdletparameter und Werte übriger Argumente darstellt.
Weitere Informationen zu Splatting finden Sie unter „about_Splatting“ (https://go.microsoft.com/fwlink/?LinkId=262720).
Weiterreichen von Objekten an Funktionen
Jede Funktion kann Eingaben aus der Pipeline nutzen. Sie können steuern, wie eine Funktion Eingaben aus der Pipeline mit den Schlüsselwörtern „Begin“, „Process“ und „End“ verarbeitet. Die folgende Beispielsyntax zeigt die drei Schlüsselwörter:
function <name> {
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
Die Begin-Anweisungsliste wird nur einmal am Anfang der Funktion ausgeführt.
Die Prozess-Anweisungsliste wird einmal für jedes Objekt in der Pipeline ausgeführt. Bei der Ausführung des Process-Blocks wird jedes Pipelineobjekt der automatischen Variablen „$_“ zugewiesen, und zwar jeweils ein einzelnes Pipelineobjekt.
Nachdem die Funktion alle Objekte in der Pipeline empfangen hat, wird die End-Anweisungsliste einmal ausgeführt. Wenn keine Begin-, Process- oder End-Schlüsselwörter verwendet werden, werden alle Anweisungen wie eine End-Anweisungsliste behandelt.
Die folgende Funktion verwendet das Process-Schlüsselwort. Die Funktion zeigt Beispiele aus der Pipeline:
function Get-Pipeline
{
process {"The value is: $_"}
}
Um diese Funktion zu demonstrieren, geben Sie eine Liste durch Kommas getrennter Zahlen ein, wie im folgenden Beispiel gezeigt:
C:\PS> 1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
Wenn Sie eine Funktion in einer Pipeline verwenden, werden die Objekte, die über die Pipeline der Funktion übergeben werden, der automatischen $input-Variablen zugewiesen. Die Funktion führt Anweisungen mit dem Begin-Schlüsselwort aus, bevor Objekte aus der Pipeline kommen. Die Funktion führt Anweisungen mit dem End-Schlüsselwort aus, nachdem sie alle Objekte aus der Pipeline empfangen hat.
Das folgende Beispiel zeigt die automatische $input-Variable mit den Schlüsselwörtern „Begin“ und „End“.
function Get-PipelineBeginEnd
{
begin {"Begin: The input is $input"}
end {"End: The input is $input" }
}
Wenn diese Funktion mithilfe der Pipeline ausgeführt wird, zeigt sie folgende Ergebnisse an:
C:\PS> 1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
Wenn die Begin-Anweisung ausgeführt wird, verfügt die Funktion nicht über die Eingabe aus der Pipeline. Die End-Anweisung wird ausgeführt, nachdem die Funktion die Werte bekommen hat.
Wenn die Funktion über ein Process-Schlüsselwort verfügt, liest die Funktion die Daten in „$input“ ein. Das folgende Beispiel enthält eine Process-Anweisungsliste:
function Get-PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
In diesem Beispiel wird jedes Objekt, das an die Funktion weitergereicht wird, an die Process-Anweisungsliste gesendet. Die Process-Anweisungen werden für jedes Objekt ausgeführt, und zwar jeweils für ein einzelnes Objekt. Die automatische Variable „$input“ ist leer, wenn die Funktion das End-Schlüsselwort erreicht.
C:\PS> 1,2,4 | Get-PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
Filter
Ein Filter ist ein Funktionstyp, der für jedes Objekt in der Pipeline ausgeführt wird. Ein Filter ähnelt einer Funktion mit allen ihren Anweisungen in einem Process-Block.
Die Syntax eines Filters lautet folgendermaßen:
filter [<scope:>]<name> {<statement list>}
Der folgende Filter entnimmt Protokolleinträge der Pipeline und zeigt dann den gesamten Eintrag oder nur den Nachrichtenteil des Eintrags an:
filter Get-ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message }
else { $_ }
}
Funktionsbereich
Eine Funktion ist in dem Bereich vorhanden, in dem sie erstellt wurde.
Wenn eine Funktion Teil eines Skripts ist, steht die Funktion Anweisungen innerhalb dieses Skripts zur Verfügung. Standardmäßig steht eine Funktion in einem Skript nicht an der Eingabeaufforderung zur Verfügung.
Sie können den Bereich einer Funktion angeben. Die Funktion wird im folgenden Beispiel dem globalen Bereich hinzugefügt:
function global:Get-DependentSvs { Get-Service |
where {$_.DependentServices} }
Wenn eine Funktion im globalen Bereich gültig ist, können Sie die Funktion in Skripts, Funktionen und in der Befehlszeile verwenden.
Funktionen erstellen normalerweise einen Bereich. Die Elemente, die in einer Funktion erstellt werden, z. B. Variablen, sind nur im Funktionsbereich vorhanden.
Weitere Informationen über den Bereich in Windows PowerShell finden Sie unter „about_Scopes“ (https://go.microsoft.com/fwlink/?LinkID=113260).
Suchen und Verwalten von Funktionen mit „Function: drive“
Alle Funktionen und Filter in Windows PowerShell werden automatisch in „Function: drive“ gespeichert. Dieses Laufwerk wird durch den Windows PowerShell-Function-Anbieter verfügbar gemacht.
Wenn Sie auf „Function: drive“ verweisen, geben Sie einen Doppelpunkt nach „Function“ ein, als würden Sie sich auf das C- oder D-Laufwerk eines Computers beziehen.
Der folgende Befehl zeigt alle Funktionen in der aktuellen Sitzung von Windows PowerShell an:
Get-ChildItem function:
Die Befehle in der Funktion werden als Skriptblock in der Definitionseigenschaft der Funktion gespeichert. Um beispielsweise die Befehle in der Help-Funktion anzuzeigen, die in Windows PowerShell enthalten ist, geben Sie ein:
(Get-ChildItem function:help).Definition
Weitere Informationen zu „Function: drive“ finden Sie im Hilfethema zum Function-Anbieter. Geben Sie „Get-Help Function“ ein, oder zeigen Sie das Thema in der TechNet-Bibliothek unter https://go.microsoft.com/fwlink/?LinkID=113436 an.
Wiederverwenden von Funktionen in neue Sitzungen
Wenn Sie eine Funktion an der Eingabeaufforderung von Windows PowerShell eingeben, wird die Funktion ein Teil der aktuellen Sitzung. Sie ist verfügbar, bis die Sitzung endet.
Um Ihre Funktion in allen Windows PowerShell-Sitzungen zu verwenden, fügen Sie die Funktion Ihrem Windows PowerShell-Profil hinzu. Weitere Informationen zu Profilen finden Sie unter „about_Profiles“ (https://go.microsoft.com/fwlink/?LinkID=113729).
Sie können Ihre Funktion auch in einer Windows PowerShell-Skriptdatei speichern. Geben Sie die Funktion in eine Textdatei ein, und speichern Sie die Datei mit der Dateinamenerweiterung „.ps1“.
Schreiben von Hilfe für Funktionen
Das Get-Help-Cmdlet ruft die Hilfe für Funktionen sowie für Cmdlets, Anbieter und Skripts ab. Um Hilfe für eine Funktion abzurufen, geben Sie „Get-Help“ gefolgt vom Funktionsnamen ein.
Wenn Sie z. B. Hilfe zur Funktion „Get-MyDisks“ benötigen, geben Sie Folgendes ein:
Get-Help Get-MyDisks
Sie können die Hilfe für eine Funktion mithilfe einer der beiden folgenden Methoden schreiben:
Kommentarbasierte Hilfe für Funktionen
Erstellen Sie ein Hilfethema durch Verwendung spezieller Schlüsselwörter in den Kommentaren. Um kommentarbasierte Hilfe für eine Funktion zu erstellen, müssen die Kommentare am Anfang oder Ende des Funktionstexts oder in den Zeilen platziert werden, die dem Funktionsschlüsselwort vorausgehen. Weitere Informationen zu kommentarbasierter Hilfe finden Sie unter „about_Comment_Based_Help“.
XML-basierte Hilfe für Funktionen
Erstellen Sie ein XML-basiertes Hilfethema, wie der Typ, der in der Regel für Cmdlets erstellt wird. XML-basierte Hilfe ist erforderlich, wenn Sie Hilfethemen in mehreren Sprachen lokalisieren.
Um die Funktion dem XML-basierten Hilfethema zuzuordnen, verwenden Sie das .ExternalHelp-Schlüsselwort für kommentarbasierte Hilfe. Ohne dieses Schlüsselwort kann „Get-Help“ das Hilfethema für die Funktion nicht finden, und Aufrufe von „Get-Help“ für die Funktion geben nur automatisch generierte Hilfe zurück.
Weitere Informationen zum ExternalHelp-Schlüsselwort finden Sie unter „about_Comment_Based_Help“. Weitere Informationen über die XML-basierte Hilfe finden Sie bei MSDN unter „Schreiben von Cmdlet-Hilfe“.
SIEHE AUCH
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute
about_Functions_OutputTypeAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Funktion (Anbieter)