Beschreibt, wie in Funktionen, die das CmdletBinding-Attribut (about_functions_advanced_methods)
THEMAabout_Functions_Advanced_MethodsKURZBESCHREIBUNGBeschreibt, wie in Funktionen, die das CmdletBinding-Attribut angeben, die für kompilierte Cmdlets verfügbaren Methoden und Eigenschaften verwendet werden können.DETAILBESCHREIBUNGFunktionen, 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 http://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 "http://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 "http://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 "http://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 "http://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 "http://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 "http://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 "http://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 "http://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 "http://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 "http://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 "http://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 "http://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 C:\Windows>powershell get-help about_functions_advanced_param... -full
Microsoft Windows [Version 10.0.19045.3693]
Copyright (c) 2023 Microsoft Corporation.
ColorConsole [Version 3.7.1000] PowerShell 2.0-Export
