Freigeben über

about_Functions_Advanced_Methods

Kurzbeschreibung

Beschreibt, wie Funktionen, die das attribut CmdletBinding angeben, die Methoden und Eigenschaften verwenden können, die für kompilierte Cmdlets verfügbar sind.

Lange Beschreibung

Funktionen, die das attribut CmdletBinding angeben, können über die $PSCmdlet Variable auf zusätzliche Methoden und Eigenschaften zugreifen. Zu diesen Methoden gehören die folgenden Methoden:

  • Die gleichen Eingabeverarbeitungsmethoden, die für alle Funktionen verfügbar sind.
  • Die Methoden ShouldProcess und ShouldContinue, die verwendet werden, um Benutzerfeedback zu erhalten, bevor eine Aktion ausgeführt wird.
  • Die ThrowTerminatingError Methode zum Generieren von Fehlerdatensätzen.
  • Mehrere Write Methoden, die verschiedene Ausgabetypen zurückgeben.

Alle Methoden und Eigenschaften der PSCmdlet Klasse sind für erweiterte Funktionen verfügbar. Weitere Informationen finden Sie unter System.Management.Automation.PSCmdlet.

Weitere Informationen zum attribut CmdletBinding finden Sie unter about_Functions_CmdletBindingAttribute. Informationen zur CmdletBindingAttribute Klasse finden Sie unter System.Management.Automation.CmdletBindingAttribute.

Eingabeverarbeitungsmethoden

Die in diesem Abschnitt beschriebenen Methoden werden als Eingabeverarbeitungsmethoden bezeichnet. Bei Funktionen werden diese drei Methoden durch die begin, processund end Blöcke der Funktion dargestellt. PowerShell 7.3 fügt eine clean Blockprozessmethode hinzu.

Sie müssen keine dieser Blöcke in Ihren Funktionen verwenden. Wenn Sie keinen benannten Block verwenden, fügt PowerShell den Code in den end Block der Funktion ein. Wenn Sie jedoch einen dieser benannten Blöcke verwenden oder einen dynamicparam-Block definieren, müssen Sie den gesamten Code in einen benannten Block einfügen.

Das folgende Beispiel zeigt die Gliederung einer Funktion, die einen begin-Block für einmalige Vorverarbeitung, einen process-Block für mehrere Datensatzverarbeitung und einen end-Block für einmalige Nachbearbeitung enthält.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

Anmerkung

Diese Blöcke gelten nicht nur für Funktionen, die das attribut CmdletBinding verwenden.

begin

Dieser Block wird verwendet, um optionale einmalige Vorverarbeitung für die Funktion bereitzustellen. Die PowerShell-Laufzeit verwendet den Code in diesem Block einmal für jede Instanz der Funktion in der Pipeline.

process

Dieser Block wird verwendet, um die Datensatz-nach-Datensatz-Verarbeitung für die Funktion bereitzustellen. Sie können einen process-Block verwenden, ohne die anderen Blöcke zu definieren. Die Anzahl der process Blockausführungen hängt davon ab, wie Sie die Funktion verwenden und welche Eingabe die Funktion empfängt.

Die automatische Variable $_ oder $PSItem enthält das aktuelle Objekt in der Pipeline für die Verwendung im process-Block. Die $input automatische Variable enthält einen Enumerator, der nur für Funktionen und Scriptblocks verfügbar ist. Weitere Informationen finden Sie unter about_Automatic_Variables.

  • Wenn Sie die Funktion am Anfang oder außerhalb einer Pipeline aufrufen, wird der process-Block einmal ausgeführt.
  • Innerhalb einer Pipeline wird der process-Block einmal für jedes Eingabeobjekt ausgeführt, das die Funktion erreicht.
  • Wenn die Pipelineeingabe, die die Funktion erreicht, leer ist, wird der process Block nicht ausgeführt.
    • Die begin- und end- und clean-Blöcke werden weiterhin ausgeführt.

Wichtig

Wenn ein Funktionsparameter so festgelegt ist, dass Pipelineeingaben akzeptiert werden, und ein process Block nicht definiert ist, schlägt die Datensatz-nach-Datensatz-Verarbeitung fehl. In diesem Fall wird Ihre Funktion nur einmal ausgeführt, unabhängig von der Eingabe.

Wenn Sie eine Funktion erstellen, die Pipelineeingaben akzeptiert und CmdletBindingverwendet, sollte der process-Block die Parametervariable verwenden, die Sie für die Pipelineeingabe definiert haben, anstatt $_ oder $PSItem. Zum Beispiel:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

Dieser Block wird verwendet, um optionale einmalige Nachbearbeitung für die Funktion bereitzustellen.

clean

Der clean-Block wurde in PowerShell 7.3 hinzugefügt.

Der clean-Block ist eine bequeme Möglichkeit, um Ressourcen zu bereinigen, die sich über die begin, processund end-Blöcke erstrecken. Es ähnelt semantisch einem finally-Block, der alle anderen benannten Blöcke einer Skriptfunktion oder eines Skript-Cmdlets abdeckt. Die Ressourcenbereinigung wird für die folgenden Szenarien erzwungen:

  1. wenn die Pipelineausführung normal abgeschlossen ist, ohne den Fehler zu beenden
  2. wenn die Pipelineausführung aufgrund eines Beendigungsfehlers unterbrochen wird
  3. wenn die Pipeline von Select-Object -First angehalten wird
  4. wenn die Pipeline durch STRG+c- oder StopProcessing() beendet wird

Der clean-Block verwirft alle Ausgaben, die in den Success Stream geschrieben wurden.

Vorsicht

Das Hinzufügen des clean Blocks ist eine bahnbrechende Änderung. Da clean als Schlüsselwort analysiert wird, wird verhindert, dass Benutzer direkt einen Befehl aufrufen, der als erste Anweisung in einem Scriptblock bezeichnet clean wird. Es ist jedoch kein Problem. Der Befehl kann weiterhin über den Anrufoperator (& clean) aufgerufen werden.

Bestätigungsmethoden

ShouldProcess

Diese Methode wird aufgerufen, um eine Bestätigung des Benutzers anzufordern, bevor die Funktion eine Aktion ausführt, die das System ändern würde. Die Funktion kann basierend auf dem booleschen Wert fortgesetzt werden, der von der Methode zurückgegeben wird. Diese Methode kann nur innerhalb des process {} Blocks der Funktion aufgerufen werden. Das attribut CmdletBinding muss auch deklarieren, dass die Funktion ShouldProcess unterstützt (wie im vorherigen Beispiel gezeigt).

Weitere Informationen zu dieser Methode finden Sie unter System.Management.Automation.Cmdlet.ShouldProcess.

Weitere Informationen zum Anfordern einer Bestätigung finden Sie unter Anfordern einer Bestätigung.

ShouldContinue

Diese Methode wird aufgerufen, um eine zweite Bestätigungsmeldung anzufordern. Sie sollte aufgerufen werden, wenn die ShouldProcess-Methode $truezurückgibt. Weitere Informationen zu dieser Methode finden Sie unter System.Management.Automation.Cmdlet.ShouldContinue.

Fehlermethoden

Funktionen können zwei verschiedene Methoden aufrufen, wenn Fehler auftreten. Wenn ein nicht beendeter Fehler auftritt, sollte die Funktion die WriteError Methode aufrufen, die im Abschnitt Write Methoden beschrieben wird. Wenn ein Beendigungsfehler auftritt und die Funktion nicht fortgesetzt werden kann, sollte sie die ThrowTerminatingError-Methode aufrufen. Sie können auch die throw-Anweisung zum Beenden von Fehlern und zum Cmdlet Write-Error für nicht beendete Fehler verwenden.

Weitere Informationen finden Sie unter System.Management.Automation.Cmdlet.ThrowTerminatingError.

Write-Methoden

Eine Funktion kann die folgenden Methoden aufrufen, um verschiedene Ausgabetypen zurückzugeben. Beachten Sie, dass nicht alle Ausgaben an den nächsten Befehl in der Pipeline gehen. Sie können auch die verschiedenen Write Cmdlets verwenden, z. B. Write-Error.

WriteCommandDetail

Informationen zur WriteCommandDetails-Methode finden Sie unter System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Um Informationen bereitzustellen, die zur Problembehandlung einer Funktion verwendet werden können, rufen Sie die WriteDebug-Methode auf. Die WriteDebug-Methode zeigt Debugmeldungen für den Benutzer an. Weitere Informationen finden Sie unter System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Funktionen sollten diese Methode aufrufen, wenn nicht beendete Fehler auftreten, und die Funktion soll die Verarbeitung von Datensätzen fortsetzen. Weitere Informationen finden Sie unter System.Management.Automation.Cmdlet.WriteError.

Anmerkung

Wenn ein Beendigungsfehler auftritt, sollte die Funktion die ThrowTerminatingError-Methode aufrufen.

WriteObject

Mit der WriteObject-Methode kann die Funktion ein Objekt an den nächsten Befehl in der Pipeline senden. In den meisten Fällen ist WriteObject die Methode, die verwendet werden soll, wenn die Funktion Daten zurückgibt. Weitere Informationen finden Sie unter System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

Bei Funktionen mit Aktionen, die lange zeitlang abgeschlossen werden, ermöglicht diese Methode der Funktion das Aufrufen der WriteProgress Methode, sodass Statusinformationen angezeigt werden. Sie können z. B. den Prozentabschluss anzeigen. Weitere Informationen finden Sie unter System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Um detaillierte Informationen über die Funktion bereitzustellen, rufen Sie die WriteVerbose-Methode auf, um ausführliche Nachrichten für den Benutzer anzuzeigen. Ausführliche Nachrichten werden standardmäßig nicht angezeigt. Weitere Informationen finden Sie unter System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Um Informationen zu Bedingungen bereitzustellen, die zu unerwarteten Ergebnissen führen können, rufen Sie die WriteWarning-Methode auf, um dem Benutzer Warnmeldungen anzuzeigen. Warnmeldungen werden standardmäßig angezeigt. Weitere Informationen finden Sie unter System.Management.Automation.PSCmdlet.WriteWarning.

Anmerkung

Sie können Warnmeldungen auch anzeigen, indem Sie die $WarningPreference Variable konfigurieren oder die Befehlszeilenoptionen Verbose und Debug verwenden. Weitere Informationen zur $WarningPreference Variablen finden Sie unter about_Preference_Variables.

Andere Methoden und Eigenschaften

Informationen zu den anderen Methoden und Eigenschaften, auf die über die $PSCmdlet Variable zugegriffen werden kann, finden Sie unter System.Management.Automation.PSCmdlet.

Mit der ParameterSetName--Eigenschaft können Sie beispielsweise den verwendeten Parametersatz anzeigen. Parametersätze ermöglichen es Ihnen, eine Funktion zu erstellen, die verschiedene Aufgaben basierend auf den Parametern ausführt, die angegeben werden, wenn die Funktion ausgeführt wird.

Siehe auch

  • Last updated on