Informationen zu erweiterten Funktionenmethoden
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 eine Reihe von Methoden und Eigenschaften zugreifen. Diese Methoden umfassen die folgenden Methoden:
- Eingabeverarbeitungsmethoden, die kompilierte Cmdlets verwenden, um ihre Arbeit zu erledigen.
- Die
ShouldProcess
Methoden undShouldContinue
, 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 Begin
Blöcke , Process
und End
der Funktion dargestellt. Sie müssen keine dieser Blöcke in Ihren Funktionen verwenden.
Hinweis
Diese Blöcke sind auch für Funktionen verfügbar, die das CmdletBinding
Attribut nicht verwenden.
Starten
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.
Prozess
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
Begin
Blöcke undEnd
werden weiterhin ausgeführt.
- Die
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.
Ende
Dieser Block wird verwendet, um eine optionale einmalige Nachverarbeitung für die Funktion bereitzustellen.
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
Wenn Sie entweder einen Begin
Oder-Block End
verwenden, müssen Sie alle drei Blöcke definieren. Wenn Sie alle drei Blöcke verwenden, muss sich der gesamte PowerShell-Code in einem der Blöcke befinden.
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 Nachrichten 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. Mithilfe von 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
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute