about_Functions_Advanced_Methods

Letzte Aktualisierung: Mai 2014

Betrifft: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

THEMA

about_Functions_Advanced_Methods

KURZE BESCHREIBUNG

Beschreibt, wie in Funktionen, die das Attribut CmdletBinding angeben, die für kompilierte Cmdlets verfügbaren Methoden und Eigenschaften verwendet werden können.

LANGE BESCHREIBUNG

Funktionen, die das Attribut CmdletBinding angeben, können über die Variable $pscmdlet auf eine Reihe von Methoden und Eigenschaften zugreifen. Dazu gehören die folgenden Methoden:

– Eingabeverarbeitungsmethoden, die von kompilierten Cmdlets für deren Aufgaben verwendet werden.

– Die Methoden ShouldProcess und ShouldContinue, mit denen vor einer Aktion Benutzerfeedback abgerufen wird.

– Die Methode ThrowTerminatingError zum Generieren von Fehlerdatensätzen.

– Verschiedene Write-Methoden, die unterschiedliche Ausgabetypen zurückgeben.

Erweiterten Funktionen stehen alle Methoden und Eigenschaften der Klasse PSCmdlet zur Verfügung. Weitere Informationen zu diesen Methoden und Eigenschaften finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.PSCmdlet" (https://go.microsoft.com/fwlink/?LinkId=142139).

EINGABEVERARBEITUNGSMETHODEN

Die in diesem Abschnitt beschriebenen Methoden werden als Eingabeverarbeitungsmethoden bezeichnet. In Funktionen entsprechen diese drei Methoden den Funktionsblöcken Begin, Process und End. Jede Funktion muss einen oder mehrere dieser Blöcke enthalten. Beim Ausführen einer Funktion verwendet die Windows PowerShell®-Laufzeitversion den Code dieser Blöcke. (Diese Blöcke stehen auch Funktionen zur Verfügung, in denen das Attribut CmdletBinding nicht verwendet wird.)

Begin

Über diesen Block wird eine optionale einmalige Vorverarbeitung für die Funktion bereitgestellt. Die Windows PowerShell-Laufzeitversion verwendet den Code dieses Blocks einmal für jede Instanz der Funktion in der Pipeline.

Process

Über diesen Block wird die datensatzweise Verarbeitung für die Funktion bereitgestellt. Dieser Block kann je nach Eingabe für die Funktion beliebig oft oder gar nicht verwendet werden. Bildet die Funktion beispielsweise den ersten Befehl in der Pipeline, so wird der Process-Block einmal verwendet. Wenn die Funktion nicht den ersten Befehl in der Pipeline bildet, wird der Process-Block einmal für jede Eingabe verwendet, die die Funktion von der Pipeline empfängt. Wenn keine Pipelineeingabe vorhanden ist, wird der Process-Block nicht verwendet.

Dieser Block muss definiert werden, wenn ein Funktionsparameter zum Akzeptieren der Pipelineeingabe festgelegt wird. Wenn dieser Block nicht definiert ist und der Parameter Eingaben von der Pipeline akzeptiert, werden über die Pipeline keine Werte an die Funktion übergeben.

Wenn die Funktion Bestätigungsanforderungen unterstützt (wenn der Parameter SupportsShouldProcess des Attributs Parameter auf $True festgelegt ist), muss zudem der Aufruf der Methode ShouldProcess innerhalb des Process-Blocks ausgeführt werden.

End

Über diesen Block wird eine optionale einmalige Nachverarbeitung für die Funktion bereitgestellt.

Im folgenden Beispiel wird die Gliederung in einer Funktion mit einem Begin-Block für die einmalige Vorverarbeitung, einem Process-Block für die Verarbeitung mehrerer Datensätze und einem End-Block für die einmalige Nachverarbeitung veranschaulicht.

          Function Test-ScriptCmdlet
          {
            [CmdletBinding(SupportsShouldProcess=$True)] 
            Param ($Parameter1)
            Begin{}
            Process{}
            End{}
          }

BESTÄTIGUNGSMETHODEN

ShouldProcess

Diese Methode wird aufgerufen, um eine Bestätigung des Benutzers anzufordern, bevor von der Funktion eine Aktion ausgeführt wird, durch die das System geändert wird. Die Funktion kann anhand des von der Methode zurückgegebenen booleschen Werts weiter ausgeführt werden. Diese Methode kann nur aus dem Process{}-Block der Funktion aufgerufen werden. Zudem muss das Attribut CmdletBinding deklarieren, dass die Funktion ShouldProcess unterstützt (wie im vorherigen Beispiel gezeigt).

Weitere Informationen zu dieser Methode finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.Cmdlet.ShouldProcess" (https://go.microsoft.com/fwlink/?LinkId=142142).

Weitere Informationen zum Anfordern von Bestätigungen finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "Requesting Confirmation" (https://go.microsoft.com/fwlink/?LinkID=136658).

ShouldContinue

Diese Methode wird zur Anforderung einer zweiten Bestätigungsmeldung aufgerufen. Sie sollte aufgerufen werden, wenn die Methode ShouldProcess $true zurückgibt. Weitere Informationen zu dieser Methode finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.Cmdlet.ShouldContinue" (https://go.microsoft.com/fwlink/?LinkId=142143).

FEHLERMETHODEN

Bei Fehlern können Funktionen zwei verschiedene Methoden aufrufen. Bei einem nicht terminierenden Fehler muss die Funktion die im Abschnitt "Write-Methoden" beschriebene Methode WriteError aufrufen. Bei einem Terminierungsfehler, bei dem die Ausführung der Funktion nicht fortgesetzt werden kann, muss die Methode ThrowTerminatingError aufgerufen werden. Für Terminierungsfehler können Sie auch die Throw-Anweisung und für nicht terminierende Fehler das Cmdlet Write-Error verwenden.

Weitere Informationen finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.Cmdlet.ThrowTerminatingError" (https://go.microsoft.com/fwlink/?LinkId=142144).

WRITE-METHODEN

Eine Funktion kann zur Rückgabe unterschiedlicher Ausgabetypen folgende Methoden aufrufen. Nicht alle Ausgaben werden an den nächsten Befehl in der Pipeline gesendet. Sie können auch verschiedene Write-Cmdlets verwenden, z. B. Write-Error.

WriteCommandDetail

Weitere Informationen zu dieser Methode finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.Cmdlet.WriteCommandDetail" (https://go.microsoft.com/fwlink/?LinkId=142155).

WriteDebug

Wenn Sie Informationen bereitstellen möchten, die für die Problembehandlung für eine Funktion verwendet werden können, muss von der Funktion die Methode WriteDebug aufgerufen werden. Damit werden dem Benutzer Debugmeldungen angezeigt. Weitere Informationen finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.Cmdlet.WriteDebug" (https://go.microsoft.com/fwlink/?LinkId=142156).

WriteError

Funktionen müssen diese Methode bei nicht terminierenden Fehlern aufrufen, wenn die Funktion zum Fortsetzen der Datensatzverarbeitung vorgesehen ist. Weitere Informationen finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.Cmdlet.WriteError" (https://go.microsoft.com/fwlink/?LinkId=142157).

Hinweis:

Bei einem Terminierungsfehler muss die Funktion die Methode ThrowTerminatingError aufrufen.

WriteObject

Diese Methode ermöglicht es der Funktion, ein Objekt an den nächsten Befehl in der Pipeline zu senden. In den meisten Fällen muss diese Methode verwendet werden, wenn die Funktion Daten zurückgibt. Weitere Informationen finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.PSCmdlet.WriteObject" (https://go.microsoft.com/fwlink/?LinkId=142158).

WriteProgress

Bei Funktionen, deren Ausführung sehr lange dauert, ermöglicht diese Methode der Funktion das Aufrufen der Methode WriteProgress, sodass Statusinformationen angezeigt werden. Beispielsweise kann der Prozentsatz der Fertigstellung angezeigt werden. Weitere Informationen finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.PSCmdlet.WriteProgress" (https://go.microsoft.com/fwlink/?LinkId=142160).

WriteVerbose

Wenn Sie ausführliche Informationen zu den Aktionen der Funktion bereitstellen möchten, muss die Funktion die Methode WriteVerbose aufrufen, sodass dem Benutzer ausführliche Meldungen angezeigt werden. Standardmäßig werden keine ausführlichen Meldungen angezeigt. Weitere Informationen finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.PSCmdlet.WriteVerbose" (https://go.microsoft.com/fwlink/?LinkId=142162).

WriteWarning

Wenn Sie Informationen zu Bedingungen bereitstellen möchten, unter denen möglicherweise unerwartete Ergebnisse auftreten, muss die Funktion die Methode WriteWarning aufrufen, mit der Benutzern Warnmeldungen angezeigt werden. Warnmeldungen werden standardmäßig angezeigt. Weitere Informationen finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.PSCmdlet.WriteWarning" (https://go.microsoft.com/fwlink/?LinkId=142164).

Hinweis:

Sie können auch Warnmeldungen anzeigen, indem Sie die Variable "WarningPreference" konfigurieren oder die Befehlszeilenoptionen "Verbose" und "Debug" verwenden.

WEITERE METHODEN UND EIGENSCHAFTEN

Informationen zu weiteren Methoden und Eigenschaften, auf die über die Variable "$PSCmdlet" zugegriffen werden kann, finden Sie in der Microsoft Developer Network (MSDN)-Bibliothek unter "System.Management.Automation.PSCmdlet" (https://go.microsoft.com/fwlink/?LinkId=142139).

Mit der Eigenschaft ParameterSetName können Sie beispielsweise den derzeit verwendeten Parametersatz anzeigen. Mit Parametersätzen können Sie eine Funktion erstellen, die je nach den bei der Funktionsausführung angegebenen Parametern unterschiedliche Aufgaben ausführt.

SIEHE AUCH

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute