THEMA
about_Functions_Advanced_Methods
KURZBESCHREIBUNG
Beschreibt, wie in Funktionen, die das CmdletBinding-Attribut
angeben, die für kompilierte Cmdlets verfügbaren Methoden und
Eigenschaften verwendet werden können.
DETAILBESCHREIBUNG
Funktionen, die das CmdletBinding-Attribut angeben, können über
die Variable "$pscmdlet" auf eine Reihe von Methoden und Eigenschaften
zugreifen. Zu diesen Methoden gehören die folgenden:
- Eingabeverarbeitungsmethoden, die von kompilierten Cmdlets
für deren Aufgaben verwendet werden.
- Die ShouldProcess-Methode und die ShouldContinue-Methode,
mit denen vor einer Aktion Benutzerfeedback abgerufen wird.
- Die ThrowTerminatingError-Methode zum Generieren von
Fehlerdatensätzen.
- Verschiedene Write-Methoden, die unterschiedliche
Ausgabetypen zurückgeben.
- Verschiedene Write-Methoden, die unterschiedliche Ausgabetypen
zurückgeben.
Erweiterten Funktionen stehen alle Methoden und Eigenschaften der
PSCmdlet-Klasse zur Verfügung. Weitere Informationen zu diesen
Methoden und Eigenschaften finden Sie unter "System.Management.Aut
omation.PSCmdlet" in der MSDN Library (Microsoft Developer
Network) unter
https://go.microsoft.com/fwlink/?LinkId=142139 (möglicherweise auf
Englisch).
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 Blöcke einschließen. Beim Ausführen
einer Funktion verwendet die Windows PowerShell-Laufzeit den Code in
diesen Blöcken. (Diese Blöcke stehen auch Funktionen zur Verfügung,
für die das CmdletBinding-Attribut nicht verwendet wird.)
Begin
Dieser Block wird verwendet, um eine optionale einmalige
Vorverarbeitung für die Funktion bereitzustellen. Die Windows
PowerShell-Laufzeit verwendet den Code in diesem Block 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. Wenn
die Funktion beispielsweise den ersten Befehl in der Pipeline
bildet, 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 SupportsShouldProcess-Parameter des Parameter-Attributs auf
$True festgelegt ist), muss zudem der Aufruf der ShouldProcess-M
ethode innerhalb des Process-Blocks ausgeführt werden.
End
Über diesen Block wird die optionale einmalige Vorverarbeitung
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, mit
der 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 im Process{}-Block der Funktion aufgerufen werden.
Zudem muss das CmdletBinding-Attribut 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" in der MSDN
Library unter "https://go.microsoft.com/fwlink/?LinkId=142142" (möglicherweise
auf Englisch).
Weitere Informationen zum Anfordern von Bestätigungen finden
Sie im Kapitel zum Anfordern von Bestätigungen in der MSDN
Library unter "https://go.microsoft.com/fwlink/?LinkID=136658" (möglicherweise
auf Englisch).
ShouldContinue
Diese Methode wird aufgerufen, um eine zweite Bestätigungsmeldung
anzufordern. Sie muss aufgerufen werden, wenn die ShouldProcess-Methode
$true zurückgibt. Weitere Informationen zu dieser Methode finden
Sie unter
"System.Management.Automation.Cmdlet.ShouldContinue" in der
MSDN Library unter "https://go.microsoft.com/fwlink/?LinkId=142143"
(möglicherweise auf Englisch).
Fehlermethoden
Bei Fehlern können Funktionen zwei verschiedene Methoden
aufrufen. Wenn ein Fehler ohne Abbruch auftritt, muss die Funktion die
WriteError-Methode aufrufen, die im Abschnitt "Write-Methoden"
beschrieben ist. Wenn ein Fehler mit Abbruch auftritt und die
Ausführung der Funktion nicht fortgesetzt werden kann, muss die
ThrowTerminatingError-Methode aufgerufen werden. Sie können auch die
Throw-Anweisung für Fehler mit Abbruch und das Cmdlet "Write-Error"
für Fehler mit Abbruch verwenden.
Weitere Informationen finden Sie unter "System.Management.Automati
on.Cmdlet.
ThrowTerminatingError" in der MSDN Library unter
"https://go.microsoft.com/fwlink/?LinkId=142144" (möglicherweise auf
Englisch).
Write-Methoden
Eine Funktion kann die folgenden Methoden aufrufen, um
unterschiedliche Ausgabetypen zurückzugeben. 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 zur WriteCommandDetails-Methode finden
Sie unter "System.Management.Automation.Cmdlet.WriteCommandDetail"
in der MSDN Library unter
"https://go.microsoft.com/fwlink/?LinkId=142155" (möglicherweise auf
Englisch).
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 WriteDebug-Methode aufgerufen werden. Damit werden dem
Benutzer Debugmeldungen angezeigt. Weitere Informationen finden Sie unter
"System.Management.Automation.Cmdlet.WriteDebug" in der MSDN Library unter
"https://go.microsoft.com/fwlink/?LinkId=142156" (möglicherweise auf
Englisch).
WriteError
Funktionen müssen diese Methode bei Fehlern ohne Abbruch
aufrufen, wenn die Funktion zum Fortsetzen der Datensatzverarbeitung
vorgesehen ist. Weitere Informationen finden Sie unter "System.Management.
Automation.Cmdlet.WriteError" in der MSDN Library unter
"https://go.microsoft.com/fwlink/?LinkId=142157" (möglicherweise auf
Englisch).
Hinweis: Bei einem Fehler mit Abbruch muss die Funktion die
ThrowTerminatingError-Methode 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 unter
"System.Management.Automation.PSCmdlet.WriteObject" in der MSDN
Library unter "https://go.microsoft.com/fwlink/?LinkId=142158"
(möglicherweise auf Englisch).
WriteProgress
Bei Funktionen, für deren Abschluss eine lange Zeit benötigt
wird, ermöglicht diese Methode der Funktion das Aufrufen der
WriteProgress-Methode, sodass Statusinformationen angezeigt
werden. Beispielsweise kann der Prozentsatz der Fertigstellung
angezeigt werden. Weitere Informationen finden Sie unter
"System.Management.Automation.PSCmdlet.WriteProgress" in der
MSDN Library unter "https://go.microsoft.com/fwlink/?LinkId=142160"
(möglicherweise auf Englisch).
WriteVerbose
Wenn Sie ausführliche Informationen zu den Aktionen der
Funktion bereitstellen möchten, muss die Funktion die
WriteVerbose-Methode aufrufen, sodass dem Benutzer ausführliche
Meldungen angezeigt werden. Standardmäßig werden keine
ausführlichen Meldungen angezeigt. Weitere Informationen finden
Sie unter "System.Management.Automation.PSCmdlet.WriteVerbose"
in der MSDN Library unter
"https://go.microsoft.com/fwlink/?LinkId=142162" (möglicherweise
auf Englisch).
WriteWarning
Wenn Sie Informationen zu Bedingungen bereitstellen möchten,
unter denen möglicherweise unerwartete Ergebnisse auftreten,
muss die Funktion die WriteWarning-Methode aufrufen, mit der
Benutzern Warnmeldungen angezeigt werden. Standardmäßig werden
Warnmeldungen angezeigt.
Weitere Informationen finden Sie unter
"System.Management.Automation.PSCmdlet.WriteWarning" in der
MSDN Library unter "https://go.microsoft.com/fwlink/?LinkId=142164"
(möglicherweise auf Englisch).
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 den anderen Methoden und Eigenschaften, auf
die über die Variable "$PSCmdlet" zugegriffen werden kann,
finden Sie unter "System.Management.Automation.PSCmdlet" in der
MSDN Library unter "https://go.microsoft.com/fwlink/?
LinkId=142139" (möglicherweise auf Englisch).
Mit der ParameterSetName-Eigenschaft können Sie beispielsweise
den derzeit verwendeten Parametersatz anzeigen. Mit
Parametersätzen können Sie eine Funktion erstellen, mit der
anhand der beim Ausführen der Funktion angegebenen Parameter
andere Aufgaben ausgeführt werden.
SIEHE AUCH
about_Functions_Advanced
about_Functions_CmdletBindingAttributes
about_Functions_Advanced_Parameters