Freigeben über

about_Functions_Advanced

Kurzbeschreibung

Führt erweiterte Funktionen ein, die eine Möglichkeit zum Erstellen von Cmdlets mithilfe von Skripts sind.

Lange Beschreibung

Ein Cmdlet ist ein einzelner Befehl, der an der Pipelinesemantik von PowerShell teilnimmt. Dazu gehören binäre Cmdlets, erweiterte PowerShell-Funktionen und CDXML-Cmdlets.

Mit erweiterten Funktionen können Sie Cmdlets erstellen, die als PowerShell-Funktion geschrieben werden. Erweiterte Funktionen erleichtern das Erstellen von Cmdlets, ohne ein binäres Cmdlet schreiben und kompilieren zu müssen. Binäre Cmdlets sind .NET-Klassen, die in einer .NET-Sprache wie C# geschrieben werden.

Erweiterte Funktionen verwenden das attribut CmdletBinding, um sie als Funktionen zu identifizieren, die wie Cmdlets funktionieren. Das attribut CmdletBinding ähnelt dem Cmdlet-Attribut, das in kompilierten Cmdlet-Klassen verwendet wird, um die Klasse als Cmdlet zu identifizieren. Weitere Informationen zu diesem Attribut finden Sie unter about_Functions_CmdletBindingAttribute.

Die Parameter der Funktion sind Variablen, die in der param()-Anweisung deklariert werden. Sie können das optionale [Parameter()]-Attribut allein oder in Kombination mit dem attribut [Alias()] oder einem der Parameterüberprüfungsattribute verwenden. Weitere Informationen zum Deklarieren von Parametern finden Sie unter about_Functions_Advanced_Parameters.

Das folgende Beispiel zeigt eine Funktion, die einen Namen akzeptiert und dann eine Begrüßung mit dem angegebenen Namen druckt. Beachten Sie außerdem, dass diese Funktion einen Namen definiert, der ein Verbpaar (Senden) und Substantiv (Gruß) wie das Verb-Nomenpaar eines kompilierten Cmdlets enthält. Funktionen sind jedoch nicht erforderlich, um einen Verbennamen zu haben.

function Send-Greeting
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Name
    )

    process
    {
        Write-Host ("Hello " + $Name + "!")
    }
}

Diese Funktion führt die Arbeit im process-Block aus, was der ProcessingRecord Methode entspricht, die in kompilierten Cmdlets verwendet wird. Der process-Block und die anderen benannten Blöcke werden in about_Functions_Advanced_Methodsbeschrieben.

Erweiterte Funktionen unterscheiden sich von kompilierten Cmdlets auf folgende Weise:

  • Die Erweiterte Funktionsparameterbindung löst keine Ausnahme aus, wenn ein Array von Zeichenfolgen an einen booleschen-Parameter gebunden ist.
  • Das attribut ValidateSet und das attribut ValidatePattern können keine benannten Parameter übergeben.
  • Erweiterte Funktionen können nicht in Transaktionen verwendet werden.

PIPELINESTOPTOKEN

Ab PowerShell 7.6-preview.4 enthält $PSCmdlet die PipelineStopToken-Eigenschaft, die den Zugriff auf ein CancellationToken an die PowerShell-Stoppereignisquelle gebunden ist. Das Token wird ausgelöst, wenn die PowerShell-Pipeline eine Anforderung zum Beenden empfängt. Verwenden Sie sie mit einer .NET-Methode, die eine CancellationToken Überladung akzeptiert, um die Methode bei Bedarf zu beenden, anstatt zu warten, bis die Methode zurückgegeben wird.

Im folgenden Beispiel ruft die Funktion HttpClient.GetStringAsyncauf, was zeitlang dauern kann, wenn das Netzwerk langsam ist oder viele Daten zurückgegeben werden.

function Invoke-CancelableWebRequest {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]
        $Url
    )

    $client = [System.Net.Http.HttpClient]::new()
    $client.GetStringAsync(
        $Url,
        $PSCmdlet.PipelineStopToken).GetAwaiter().GetResult()
}

Invoke-CancelableWebRequest -Url https://httpbin.org/delay/10
# Press ctrl+c to cancel

Siehe auch

  • Last updated on