Freigeben über

about_Functions_Advanced_Methods

  • Artikel

Kurze Beschreibung

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

Lange Beschreibung

Funktionen, die das CmdletBinding Attribut 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 ShouldProcess Methoden, ShouldContinue die verwendet werden, um Benutzerfeedback zu erhalten, bevor eine Aktion ausgeführt wird.
  • Die ThrowTerminatingError Methode zum Generieren von Fehlerdatensätzen.
  • Verschiedene Write Methoden, die unterschiedliche 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 CmdletBinding Attribut finden Sie unter about_Functions_CmdletBindingAttribute. Informationen zur CmdletBindingAttribute-Klasse finden Sie unter System.Management.Automation.Cmdlet.CmdletBindingAttribute.

Eingabeverarbeitungsmethoden

Die in diesem Abschnitt beschriebenen Methoden werden als Eingabeverarbeitungsmethoden bezeichnet. Bei Funktionen werden diese drei Methoden durch die beginprocessend Blöcke und 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 die Verarbeitung mehrerer Datensätze und einen end Block für einmalige Nachbearbeitung enthält.

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

Hinweis

Diese Blöcke gelten nicht nur für Funktionen, die das CmdletBinding Attribut 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 process Verwendung im Block. Die $input automatische Variable enthält einen Enumerator, der nur für Funktionen und Skriptblöcke 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, endund clean Blöcke werden weiterhin ausgeführt.

Wichtig

Wenn ein Funktionsparameter für die Annahme von Pipelineeingaben festgelegt ist und kein process Block 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 verwendet CmdletBinding, sollte der process Block die Parametervariable verwenden, die Sie für die Pipelineeingabe anstelle von $_ 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 für Benutzer eine praktische Möglichkeit zum Bereinigen von Ressourcen, die sich über die Blöcke begin, process und end erstrecken. Er ä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. Die Pipelineausführung wird normal und ohne zum Abbruch führenden Fehler abgeschlossen.
  2. Die Pipelineausführung wird aufgrund eines zum Abbruch führenden Fehlers unterbrochen.
  3. Die Pipeline wird durch Select-Object -First angehalten.
  4. Die Pipeline wird durch STRG+C oder StopProcessing() beendet.

Der saubere Block verwirft alle Ausgaben, die in den Erfolgsdatenstrom geschrieben wurden.

Achtung

Das Hinzufügen des clean-Blocks ist ein Breaking Change. Da clean als Schlüsselwort analysiert wird, können Benutzer nicht direkt einen Befehl namens clean als erste Anweisung in einem Skriptblock aufrufen. Es ist jedoch kein Problem. Der Befehl kann weiterhin über den Aufrufoperator (& 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 CmdletBinding Attribut muss auch deklarieren, dass die Funktion unterstützt ShouldProcess wird (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 zurückgegeben wird $true. 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 Write Abschnitt "Methoden" beschrieben wird. Wenn ein Beendigungsfehler auftritt und die Funktion nicht fortgesetzt werden kann, sollte sie die ThrowTerminatingError Methode aufrufen. Sie können die Throw Anweisung auch zum Beenden von Fehlern und zum Write-Error-Cmdlet für nicht beendete Fehler verwenden.

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

Schreibmethoden

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 Write-Error. B. .

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 Methode auf WriteDebug . 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".

Hinweis

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

WriteObject

Mit WriteObject der Methode kann die Funktion ein Objekt an den nächsten Befehl in der Pipeline senden. In den meisten Fällen ist die Methode, die verwendet werden soll, WriteObject 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, kann die Funktion die WriteProgress Methode aufrufen, 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 darüber bereitzustellen, was die Funktion tut, rufen WriteVerbose Sie die 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".

Hinweis

Sie können Warnmeldungen auch anzeigen, indem Sie die $WarningPreference Variable konfigurieren oder die Verbose Debug Befehlszeilenoptionen 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 parametersatz anzeigen, der verwendet wird. 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