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. Diese Methoden umfassen die folgenden Methoden:

  • Die gleichen Eingabeverarbeitungsmethoden, die für alle Funktionen verfügbar sind.
  • Die ShouldProcess Methoden 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 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. Für Funktionen werden diese drei Methoden durch die beginBlöcke , processund end 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, legt 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 die einmalige Vorverarbeitung, einen process Block für die Verarbeitung mehrerer Datensätze und einen Block für die end einmalige Nachverarbeitung enthält.

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

Hinweis

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

begin

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

process

Dieser Block wird verwendet, um die Datensatzverarbeitung 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 zur Verwendung im process 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.

  • Beim Aufrufen der Funktion am Anfang oder außerhalb einer Pipeline 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 beginBlöcke , endund clean werden weiterhin ausgeführt.

Wichtig

Wenn ein Funktionsparameter so festgelegt ist, dass er pipelineeingaben akzeptiert und kein process Block definiert ist, schlägt die Datensatzverarbeitung fehl. In diesem Fall wird Ihre Funktion unabhängig von der Eingabe nur einmal ausgeführt.

Wenn Sie eine Funktion erstellen, die Die Pipelineeingabe akzeptiert und verwendet CmdletBinding, sollte der process Block die Parametervariable verwenden, die Sie für die Pipelineeingabe definiert haben, anstelle von $_ oder $PSItem. 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 eine optionale einmalige Nachverarbeitung 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.

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 wahrscheinlich kein Problem. Der Befehl kann weiterhin mit dem Aufrufoperator (& clean) aufgerufen werden.

Bestätigungsmethoden

ShouldProcess

Diese Methode wird aufgerufen, um eine Bestätigung vom Benutzer 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{} Funktionsblocks aufgerufen werden. Das CmdletBinding Attribut muss auch deklarieren, dass die Funktion unterstützt ShouldProcess (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ückgibt $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 beendender Fehler auftritt, sollte die Funktion die WriteError -Methode aufrufen, die im Write Abschnitt methoden beschrieben wird. Wenn ein Abbruchfehler 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 das Cmdlet Write-Error für Nicht-Beenden-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 die gesamte Ausgabe an den nächsten Befehl in der Pipeline geht. 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 für eine Funktion verwendet werden können, rufen Sie die -Methode auf WriteDebug . Die WriteDebug -Methode zeigt dem Benutzer Debugmeldungen an. Weitere Informationen finden Sie unter System.Management.Automation.Cmdlet.WriteDebug.

Schreibfehler

Funktionen sollten diese Methode aufrufen, wenn Nicht-Beenden-Fehler auftreten und die Funktion so konzipiert ist, dass die Verarbeitung von Datensätzen fortgesetzt wird. Weitere Informationen finden Sie unter System.Management.Automation.Cmdlet.WriteError.

Hinweis

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

Writeobject

Die WriteObject -Methode ermöglicht es der Funktion, ein Objekt an den nächsten Befehl in der Pipeline zu 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, deren Abschluss sehr lange dauert, ermöglicht diese Methode der Funktion das Aufrufen der WriteProgress -Methode, sodass Statusinformationen angezeigt werden. Sie können beispielsweise den abgeschlossenen Prozentsatz anzeigen. Weitere Informationen finden Sie unter System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Um detaillierte Informationen zur Funktionsweise der Funktion bereitzustellen, rufen WriteVerbose Sie die -Methode auf, um ausführliche Meldungen für den Benutzer anzuzeigen. Standardmäßig werden ausführliche Meldungen 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. Standardmäßig werden Warnmeldungen 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 Befehlszeilenoptionen 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. Mit Parametersätzen können Sie eine Funktion erstellen, die verschiedene Aufgaben basierend auf den Parametern ausführt, die beim Ausführen der Funktion angegeben werden.

Weitere Informationen