Allgemeine Einführung: Funktionen

Kurzbeschreibung

Beschreibt, wie Funktionen in PowerShell erstellt und verwendet werden.

Lange Beschreibung

Eine Funktion ist eine Liste von PowerShell-Anweisungen mit einem Namen, den Sie zuweisen. Wenn Sie eine Funktion ausführen, geben Sie den Funktionsnamen ein. Die Anweisungen in der Liste werden so ausgeführt, als hätten Sie sie an der Eingabeaufforderung eingegeben.

Funktionen können so einfach sein wie:

function Get-PowerShellProcess { Get-Process PowerShell }

Eine Funktion kann auch so komplex sein wie ein Cmdlet oder ein Anwendungsprogramm.

Wie Cmdlets können Funktionen Parameter aufweisen. Die Parameter können benannt, positional, switch oder dynamische Parameter sein. Funktionsparameter können über die Befehlszeile oder aus der Pipeline gelesen werden.

Funktionen können Werte zurückgeben, die angezeigt, Variablen zugewiesen oder an andere Funktionen oder Cmdlets übergeben werden können. Sie können auch einen Rückgabewert mithilfe des schlüsselworts return angeben. Das return Schlüsselwort wirkt sich nicht auf andere Ausgaben aus, die von der Funktion zurückgegeben werden, und unterdrückt sie auch nicht. return Das Schlüsselwort beendet jedoch die Funktion in dieser Zeile. Weitere Informationen finden Sie unter about_Return.

Die Anweisungsliste der Funktion kann verschiedene Typen von Anweisungslisten mit den Schlüsselwörtern Begin, Process, und End. Diese Anweisung listet die Eingaben von der Pipeline anders auf.

Ein Filter ist eine spezielle Art von Funktion, die das Filter Schlüsselwort verwendet.

Funktionen können auch wie Cmdlets funktionieren. Sie können eine Funktion erstellen, die wie ein Cmdlet funktioniert, ohne die Programmierung zu verwenden C# . Weitere Informationen finden Sie unter about_Functions_Advanced.

Syntax

Im Folgenden finden Sie die Syntax für eine Funktion:

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:

Ein Function Schlüsselwort
Ein Bereich (optional)
Ein Name, den Sie auswählen
Beliebig viele benannte Parameter (optional)
Mindestens ein PowerShell-Befehl in geschweifte Klammern {}

Weitere Informationen über das Schlüsselwort und die Dynamicparam dynamischen 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 weisen das folgende Format auf:

function <function-name> {statements}

Mit der folgenden Funktion wird PowerShell z. B. mit der Option Als Administrator ausführen gestartet.

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, geben Sie jede Anweisung in einer separaten Zeile ein, oder verwenden Sie ein Semikolon ; , um die Anweisungen zu trennen.

Die folgende Funktion findet beispielsweise alle .jpg Dateien in den Verzeichnissen des aktuellen Benutzers, 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-Object {$_.LastWriteTime -gt $Start}
}

Sie können eine Toolbox mit nützlichen kleinen Funktionen erstellen. Fügen Sie diese Funktionen ihrem PowerShell-Profil hinzu, wie in about_Profiles und höher in diesem Thema beschrieben.

Funktionsnamen

Sie können einer Funktion einen beliebigen Namen zuweisen, aber Funktionen, die Sie für andere Personen freigeben, sollten den Benennungsregeln entsprechen, die für alle PowerShell-Befehle eingerichtet 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, für das das Cmdlet seine Aktion ausführt.

Funktionen sollten die Standardverben verwenden, die für alle PowerShell-Befehle genehmigt wurden. Diese Verben helfen uns, unsere Befehlsnamen einfach, konsistent und für Benutzer leicht verständlich zu halten.

Weitere Informationen zu den standardmäßigen PowerShell-Verben finden Sie unter Genehmigte Verben in der Microsoft-Dokumentation.

Funktionen mit Parametern

Sie können Parameter mit Funktionen verwenden, einschließlich benannter Parameter, Positionsparameter, Schalterparameter und dynamischer 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 angeben, wie weiter unten in diesem Thema beschrieben.

Sie können Parameter innerhalb der geschweiften Klammern mit dem Param-Schlüsselwort definieren, wie in der folgenden Beispielsyntax gezeigt:

function <name> {
  param ([type]$parameter1[,[type]$parameter2])
  <statement list>
}

Sie können Parameter auch außerhalb der geschweiften Klammern ohne das Param Schlüsselwort definieren, wie in der folgenden Beispielsyntax dargestellt:

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

Nachfolgend finden Sie ein Beispiel für diese alternative Syntax.

Function Add-Numbers($one, $two) {
    $one + $two
}

Während die erste Methode bevorzugt wird, gibt es keinen Unterschied zwischen diesen beiden Methoden.

Wenn Sie die Funktion ausführen, 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.

Das folgende Beispiel ist eine Funktion, die aufgerufen wird Get-SmallFiles. Diese Funktion weist einen $size Parameter auf. Die Funktion zeigt alle Dateien an, die kleiner als der Wert des $size Parameters sind, und schließt Verzeichnisse aus:

function Get-SmallFiles {
  Param($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

In der Funktion können Sie die $size Variable verwenden, bei der es sich um den für den Parameter definierten Namen handelt.

Geben Sie den folgenden Befehl ein, um diese Funktion zu verwenden:

Get-SmallFiles -Size 50

Sie können auch einen Wert für einen benannten Parameter ohne den Parameternamen eingeben. Der folgende Befehl gibt z. B. dasselbe Ergebnis wie ein Befehl, der den Parameter Size benennt:

Get-SmallFiles 50

Um einen Standardwert für einen Parameter zu definieren, geben Sie ein Gleichheitszeichen und den Wert nach dem Parameternamen ein, wie in der folgenden Variante des Beispiels Get-SmallFiles gezeigt:

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Wenn Sie einen Wert eingeben Get-SmallFiles , weist die Funktion 100 zu $size. Wenn Sie einen Wert angeben, verwendet die Funktion diesen Wert.

Optional können Sie eine kurze Hilfezeichenfolge bereitstellen, die den Standardwert Ihres Parameters beschreibt, indem Sie das PSDefaultValue-Attribut zur Beschreibung Des Parameters hinzufügen und die Hilfeeigenschaft von PSDefaultValue angeben. Um eine Hilfezeichenfolge bereitzustellen, die den Standardwert (100) des Parameters Size 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 zur PSDefaultValue-Attributklasse finden Sie unter PSDefaultValue-Attributmber.

Positionsparameter

Ein Positionsparameter ist ein Parameter ohne Parameternamen. PowerShell verwendet die Parameterwertreihenfolge, um jeden Parameterwert einem Parameter in der Funktion zuzuordnen.

Wenn Sie Positionsparameter verwenden, geben Sie nach dem Funktionsnamen einen oder mehrere Werte ein. Positionsparameterwerte werden der $args Arrayvariablen zugewiesen. Der Wert, der dem Funktionsnamen folgt, wird der ersten Position im $args Array zugewiesen. $args[0]

Die folgende Get-Extension Funktion fügt einem von Ihnen angegebenen Dateinamen die .txt Dateinamenerweiterung hinzu:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Parameter wechseln

Ein Schalter ist ein Parameter, für den kein Wert erforderlich ist. Stattdessen geben Sie den Funktionsnamen gefolgt vom Namen des Switch-Parameters ein.

Um einen Switch-Parameter zu definieren, geben Sie den Typ [switch] vor dem Parameternamen an, wie im folgenden Beispiel gezeigt:

function Switch-Item {
  param ([switch]$on)
  if ($on) { "Switch on" }
  else { "Switch off" }
}

Wenn Sie den On Schalterparameter nach dem Funktionsnamen eingeben, zeigt die Funktion "Einschalten" an. Ohne den Parameter switch wird "Ausschalten" angezeigt.

Switch-Item -on

Switch on

Switch-Item

Switch off

Sie können einem Schalter auch einen booleschen Wert zuweisen, wenn Sie die Funktion ausführen, wie im folgenden Beispiel gezeigt:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Verwenden von Splatting zur Darstellung von Befehlsparametern

Sie können Splatting verwenden, um die Parameter eines Befehls darzustellen. Dieses Feature wird 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 auflisten oder die Funktion ändern, wenn sich die Befehlsparameter ändern.

Die folgende Beispielfunktion ruft das Get-Command Cmdlet auf. Der Befehl verwendet @Args , um die Parameter von Get-Command.

function Get-MyCommand { Get-Command @Args }

Sie können alle Parameter Get-Command verwenden, wenn Sie die Get-MyCommand Funktion aufrufen. Die Parameter und Parameterwerte werden mithilfe @Argsdes Befehls an den Befehl übergeben.

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

Das @Args Feature verwendet den automatischen Parameter, der $Args nicht deklarierte Cmdlet-Parameter und Werte aus verbleibenden Argumenten darstellt.

Weitere Informationen zum Splatting finden Sie unter about_Splatting.

Verlegung von Objekten an Funktionen

Jede Funktion kann Eingaben aus der Pipeline übernehmen. Sie können steuern, wie eine Funktion Eingaben aus der Pipeline mithilfe Beginvon , Processund End Schlüsselwörtern 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.

Von Bedeutung

Wenn die Funktion einen Beginoder einen Process Block definiert, End muss sich der gesamte Code in einem der Blöcke befinden.

Die Anweisungsliste Process wird für jedes Objekt in der Pipeline einmal ausgeführt. Während der Process Block ausgeführt wird, wird jedem Pipelineobjekt die $_ automatische Variable zugewiesen, jeweils ein Pipelineobjekt.

Nachdem die Funktion alle Objekte in der Pipeline empfangen hat, wird die End Anweisungsliste einmal ausgeführt. Wenn keine BeginSchlüsselwörter , Process, oder End 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 an:

function Get-Pipeline
{
  process {"The value is: $_"}
}

Um diese Funktion zu veranschaulichen, geben Sie eine Liste von Zahlen ein, die durch Kommas getrennt sind, wie im folgenden Beispiel gezeigt:

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 an die Funktion weitergeleiteten Objekte der $input automatischen Variablen zugewiesen. Die Funktion führt Anweisungen mit dem schlüsselwort Begin aus, bevor objekte aus der Pipeline stammen. Die Funktion führt Anweisungen mit dem schlüsselwort End aus, nachdem alle Objekte von der Pipeline empfangen wurden.

Das folgende Beispiel zeigt die $input automatische Variable mit Begin und End Schlüsselwörtern.

function Get-PipelineBeginEnd
{
  begin {"Begin: The input is $input"}
  end {"End:   The input is $input" }
}

Wenn diese Funktion mithilfe der Pipeline ausgeführt wird, werden die folgenden Ergebnisse angezeigt:

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 aufweist.

Wenn die Funktion über ein Process Schlüsselwort verfügt, wird jedes Objekt $input entfernt $input und zugewiesen $_. 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 weitergeleitet wird, an die Process Anweisungsliste gesendet. Die Process Anweisungen werden für jedes Objekt( jeweils ein Objekt) ausgeführt. Die $input automatische Variable ist leer, wenn die Funktion das End Schlüsselwort erreicht.

1,2,4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Weitere Informationen finden Sie unter Verwenden von Enumeratoren

Filter

Ein Filter ist ein Funktionstyp, der für jedes Objekt in der Pipeline ausgeführt wird. Ein Filter ähnelt einer Funktion mit allen zugehörigen Anweisungen in einem Process-Block.

Die Syntax eines Filters lautet wie folgt:

filter [<scope:>]<name> {<statement list>}

Der folgende Filter akzeptiert Protokolleinträge aus der Pipeline und zeigt dann entweder 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, ist die Funktion für Anweisungen innerhalb dieses Skripts verfügbar. Standardmäßig ist eine Funktion in einem Skript an der Eingabeaufforderung nicht verfügbar.

Sie können den Bereich einer Funktion angeben. Die Funktion wird beispielsweise dem globalen Bereich im folgenden Beispiel hinzugefügt:

function global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

Wenn sich eine Funktion im globalen Bereich befindet, können Sie die Funktion in Skripts, in Funktionen und an der Befehlszeile verwenden.

Funktionen erstellen normalerweise einen Bereich. Die in einer Funktion erstellten Elemente, z. B. Variablen, sind nur im Funktionsbereich vorhanden.

Weitere Informationen zum Bereich in PowerShell finden Sie unter about_Scopes.

Suchen und Verwalten von Funktionen mithilfe der Funktion: Laufwerk

Alle Funktionen und Filter in PowerShell werden automatisch auf dem Function: Laufwerk gespeichert. Dieses Laufwerk wird vom PowerShell-Funktionsanbieter verfügbar gemacht.

Geben Sie beim Verweisen auf das Function: Laufwerk einen Doppelpunkt hinter "Function" ein, genau wie beim Verweisen auf das CD Laufwerk eines Computers.

Der folgende Befehl zeigt alle Funktionen in der aktuellen PowerShell-Sitzung an:

Get-ChildItem function:

Die Befehle in der Funktion werden als Skriptblock in der Definitionseigenschaft der Funktion gespeichert. Wenn Sie beispielsweise die Befehle in der Hilfefunktion anzeigen möchten, die im Lieferumfang von PowerShell enthalten ist, geben Sie Folgendes ein:

(Get-ChildItem function:help).Definition

Sie können auch die folgende Syntax verwenden.

$function:help

Weitere Informationen zum Function: Laufwerk finden Sie im Hilfethema zum Anbieter Function. Geben Sie Get-Help Function ein.

Erneutes Verwenden von Funktionen in neuen Sitzungen

Wenn Sie eine Funktion an der PowerShell-Eingabeaufforderung eingeben, wird die Funktion Teil der aktuellen Sitzung. Sie ist verfügbar, bis die Sitzung beendet ist.

Um Ihre Funktion in allen PowerShell-Sitzungen zu verwenden, fügen Sie die Funktion ihrem PowerShell-Profil hinzu. Weitere Informationen zu Profilen finden Sie unter about_Profiles.

Sie können Ihre Funktion auch in einer PowerShell-Skriptdatei speichern. Geben Sie die Funktion in eine Textdatei ein, und speichern Sie die Datei dann mit der .ps1 Dateinamenerweiterung.

Schreiben der Hilfe für Funktionen

Das cmdlet Get-Help ruft Hilfe für Funktionen sowie für Cmdlets, Anbieter und Skripts ab. Um Hilfe zu einer Funktion zu erhalten, geben Sie Get-Help gefolgt vom Funktionsnamen ein.

Um z. B. Hilfe für die Get-MyDisks Funktion zu erhalten, geben Sie Folgendes ein:

Get-Help Get-MyDisks

Sie können Hilfe für eine Funktion schreiben, indem Sie eine der beiden folgenden Methoden verwenden:

Kommentarbasierte Hilfe für Funktionen

Erstellen Sie ein Hilfethema, indem Sie spezielle Schlüsselwörter in den Kommentaren verwenden. Um kommentarbasierte Hilfe für eine Funktion zu 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

Erstellen Sie ein XML-basiertes Hilfethema, z. B. den Typ, der normalerweise für Cmdlets erstellt wird. Xml-basierte Hilfe ist erforderlich, wenn Sie Hilfethemen in mehrere Sprachen lokalisieren.

Wenn Sie die Funktion dem XML-basierten Hilfethema zuordnen möchten, verwenden Sie das schlüsselwort ".ExternalHelp kommentarbasierte Hilfe". Ohne dieses Schlüsselwort kann das Hilfethema der Funktion nicht gefunden werden, Get-Help 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 zur XML-basierten Hilfe finden Sie unter Schreiben der Cmdlet-Hilfe in der MSDN Library.