about_Functions

Kurze Beschreibung

Beschreibt das Erstellen und Verwenden von Funktionen in PowerShell.

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 benannte, positionale, 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 einen Rückgabewert auch mithilfe des return Schlüsselworts angeben. Das Schlüsselwort wirkt sich nicht auf andere Ausgaben aus, die return von Ihrer Funktion zurückgegeben werden, oder unterdrückt sie. Das Schlüsselwort beendet jedoch die Funktion in dieser return 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 enthalten. Diese Anweisungslisten behandeln Eingaben aus der Pipeline unterschiedlich.

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

Funktionen können auch wie Cmdlets fungieren. Sie können eine Funktion erstellen, die genau wie ein Cmdlet funktioniert, ohne programmieren zu C# müssen. 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 von Ihnen ausgewählter Name
  • Beliebige Anzahl benannter Parameter (optional)
  • Mindestens ein PowerShell-Befehl in geschweiften Klammern {}

Weitere Informationen zum Schlüsselwort und Dynamicparam den dynamischen Parametern 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 das folgende Format:

function <function-name> {statements}

Beispielsweise startet die folgende Funktion PowerShell mit der Option Als Administrator ausführen.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

Um die Funktion zu verwenden, geben Sie 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 sucht beispielsweise alle Dateien in den Verzeichnissen des aktuellen Benutzers, die nach dem .jpg 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 ihrem PowerShell-Profil diese Funktionen hinzu, wie in about_Profiles und später in diesem Thema beschrieben.

Funktionsnamen

Sie können einer Funktion einen beliebigen Namen zuweisen. Funktionen, die Sie für andere Benutzer freigeben, sollten jedoch die Benennungsregeln befolgen, die für alle PowerShell-Befehle eingerichtet wurden.

Funktionsnamen sollten aus einem Verb-Nomen-Paar bestehen, in dem das Verb die Aktion identifiziert, die von der Funktion ausgeführt wird, und das Nomen das Element identifiziert, 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 dabei, unsere Befehlsnamen einfach, konsistent und leicht verständlich zu halten.

Weitere Informationen zu den PowerShell-Standardverben finden Sie unter Genehmigte Verben im Microsoft-Dokumentation.

Funktionen mit Parametern

Sie können Parameter mit Funktionen verwenden, einschließlich benannter Parameter, Positionsparameter, Switchparameter und dynamischer Parameter. Weitere Informationen zu dynamischen Parametern in Funktionen finden Sie unter about_Functions_Advanced_Parameters.

benannten Parametern

Sie können eine beliebige Anzahl benannter Parameter definieren. Sie können einen Standardwert für benannte Parameter einschließen, wie weiter unten in diesem Thema beschrieben.

Sie können Parameter innerhalb der geschweiften Klammern mithilfe des Param Schlüsselworts 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 gezeigt:

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

Im Folgenden finden Sie ein Beispiel für diese alternative Syntax.

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

Obwohl 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 namens Get-SmallFiles . Diese Funktion verfügt über einen $Size -Parameter. 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. das gleiche Ergebnis wie ein Befehl aus, der den Size-Parameter 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 ohne Get-SmallFiles Wert eingeben, weist die Funktion 100 $size zu. Wenn Sie einen Wert bereitstellen, verwendet die Funktion diesen Wert.

Optional können Sie eine kurze Hilfezeichenfolge angeben, die den Standardwert Ihres Parameters beschreibt, indem Sie das PSDefaultValue-Attribut zur Beschreibung Ihres Parameters hinzufügen und die Help-Eigenschaft von PSDefaultValue angeben. Um eine Hilfezeichenfolge zur Verfügung zu stellen, die den Standardwert (100) des Size-Parameters in der Funktion beschreibt, fügen Sie das Get-SmallFiles 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-Attributmitglieder.

Positionsparameter

Ein Positionsparameter ist ein Parameter ohne Parameternamen. PowerShell verwendet die Parameterwert reihenfolge, um jeden Parameterwert einem Parameter in der Funktion zu zuordnen.

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 Funktionsnamen folgt, wird der ersten Position im Array $args zugewiesen. $args[0]

Die folgende Get-Extension Funktion fügt die .txt Dateinamenerweiterung einem dateinamen hinzu, den Sie angeben:

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

Switch-Parameter

Ein Schalter ist ein Parameter, der keinen Wert erfordert. 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 switch-Parameter nach dem Funktionsnamen eingeben, zeigt die Funktion "Einschalten" an. Ohne switch-Parameter 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 zum Darstellen 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 dieses Verfahren in Funktionen, die Befehle in der Sitzung aufrufen. Sie müssen die Befehlsparameter nicht deklarieren oder aufzählen oder 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 mithilfe von an den Befehl @Args übergeben.

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

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

Weitere Informationen zum Splatting finden Sie unter about_Splatting.

Piping Objects to Functions

Jede Funktion kann Eingaben aus der Pipeline annehmen. Sie können steuern, wie eine Funktion Eingaben aus der Pipeline mithilfe der Begin Process Schlüsselwörter , 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.

Wichtig

Wenn Ihre Funktion einen Begin Process - oder End -Block definiert, muss sich der gesamte Code in diesen Blöcken befinden. Außerhalb der Blöcke wird kein Code erkannt, wenn einer der Blöcke definiert ist.

Die Process Anweisungsliste wird einmal für jedes Objekt in der Pipeline ausgeführt. Während der Block ausgeführt wird, wird jedes Pipelineobjekt der automatischen Variablen Process $_ zugewiesen, wobei jeweils ein Pipelineobjekt verwendet wird.

Nachdem die Funktion alle Objekte in der Pipeline empfangen hat, wird die End Anweisungsliste einmal ausgeführt. Wenn keine Begin Schlüsselwörter , oder verwendet Process End 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 Durch Kommas getrennte Liste von Zahlen ein, 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 Objekte, die an die Funktion übergeben werden, der automatischen $input Variablen zugewiesen. Die Funktion führt -Anweisungen mit dem Begin -Schlüsselwort aus, bevor Objekte aus der Pipeline stammen. Die Funktion führt -Anweisungen mit End dem -Schlüsselwort aus, nachdem alle Objekte von der Pipeline empfangen wurden.

Das folgende Beispiel zeigt die $input automatische Variable mit den Begin Schlüsselwörtern 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, 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 über die Werte verfügt.

Wenn die Funktion über ein Process Schlüsselwort verfügt, wird jedes Objekt in $input aus entfernt und $input $_ 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 übergeben wird, an die Process Anweisungsliste gesendet. Die Process -Anweisungen werden für jedes -Objekt ausgeführt, jeweils ein -Objekt. Die $input automatische Variable ist leer, wenn die Funktion das Schlüsselwort End 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 all ihren Anweisungen in einem Process -Block.

Die Syntax eines Filters lautet wie folgt:

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

Der folgende Filter übernimmt Protokolleinträge aus der Pipeline und zeigt dann entweder den gesamten Eintrag oder nur den Meldungsteil des Eintrags an:

filter Get-ErrorLog ([switch]$message)
{
  if ($message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Funktionsbereich

Eine Funktion ist im Bereich vorhanden, in dem sie erstellt wurde.

Wenn eine Funktion Teil eines Skripts ist, ist die Funktion für Anweisungen in diesem Skript verfügbar. Standardmäßig ist eine Funktion in einem Skript an der Eingabeaufforderung nicht verfügbar.

Sie können den Bereich einer Funktion angeben. Beispielsweise wird die Funktion im folgenden Beispiel dem globalen Bereich 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, funktionen und in 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.

Wenn Sie auf das Function: Laufwerk verweisen, geben Sie einen Doppelpunkt nach Function ein, genau wie beim Verweisen auf das C Laufwerk oder eines D 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. Geben Sie beispielsweise Folgendes ein, um die Befehle in der in PowerShell enthaltenen Hilfefunktion anzuzeigen:

(Get-ChildItem function:help).Definition

Sie können auch die folgende Syntax verwenden.

$function:help

Weitere Informationen zum Laufwerk Function: finden Sie im Hilfethema für den Funktionsanbieter. Geben Sie Get-Help Functionein.

Wiederverwendung von Funktionen in neuen Sitzungen

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

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 Ihre Funktion in eine Textdatei ein, und speichern Sie die Datei mit der .ps1 Dateierweiterung .

Schreiben von Hilfe für Funktionen

Das Cmdlet erhält Hilfe für Funktionen sowie für Get-Help Cmdlets, Anbieter und Skripts. Um Hilfe für eine Funktion zu erhalten, geben Sie Get-Help gefolgt vom Funktionsnamen ein.

Geben Sie beispielsweise Folgendes ein, um Hilfe für Get-MyDisks die Funktion zu erhalten:

Get-Help Get-MyDisks

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

  • Comment-Based 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 Ende des Funktionskörpers oder in den Zeilen vor dem Function-Schlüsselwort platziert werden. Weitere Informationen zur kommentarbasierten Hilfe finden Sie unter about_Comment_Based_Help.

  • XML-Based Hilfe für Funktionen

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

    Um die Funktion dem XML-basierten Hilfethema zuzuordnen, verwenden Sie das .ExternalHelp kommentarbasierte Hilfeschlüsselwort. Ohne dieses Schlüsselwort Get-Help kann das Hilfethema der Funktion nicht gefunden werden, 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 How to Write Cmdlet Help.

Weitere Informationen

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

about_Function_provider