Om avancerade funktioner
Kort beskrivning
Beskriver hur funktioner som anger CmdletBinding
attributet kan använda de metoder och egenskaper som är tillgängliga för kompilerade cmdletar.
Lång beskrivning
Funktioner som anger CmdletBinding
attributet kan komma åt ett antal metoder och egenskaper via variabeln $PSCmdlet
. Dessa metoder omfattar följande metoder:
- Indatabearbetningsmetoder som kompilerade cmdletar använder för att utföra sitt arbete.
- Metoderna
ShouldProcess
ochShouldContinue
som används för att få användarfeedback innan en åtgärd utförs. - Metoden
ThrowTerminatingError
för att generera felposter. - Flera
Write
metoder som returnerar olika typer av utdata.
Alla metoder och egenskaper för KLASSEN PSCmdlet är tillgängliga för avancerade funktioner. Mer information finns i System.Management.Automation.PSCmdlet.
Mer information om attributet finns i CmdletBinding
about_Functions_CmdletBindingAttribute.
För klassen CmdletBindingAttribute , se System.Management.Automation.Cmdlet.CmdletBindingAttribute.
Indatabearbetningsmetoder
Metoderna som beskrivs i det här avsnittet kallas indatabearbetningsmetoder. För funktioner representeras dessa tre metoder av Begin
Process
- och End
-blocken i funktionen. Du behöver inte använda något av dessa block i dina funktioner.
Anteckning
Dessa block är också tillgängliga för funktioner som inte använder attributet CmdletBinding
.
Börja
Det här blocket används för att tillhandahålla valfri engångsförbearbetning för funktionen. PowerShell-körningen använder koden i det här blocket en gång för varje instans av funktionen i pipelinen.
Process
Det här blocket används för att tillhandahålla post-för-post-bearbetning för funktionen. Du kan använda ett Process
block utan att definiera de andra blocken. Antalet Process
blockkörningar beror på hur du använder funktionen och vilka indata funktionen tar emot.
Den automatiska variabeln $_
eller $PSItem
innehåller det aktuella objektet i pipelinen för användning i Process
blocket. Den $input
automatiska variabeln innehåller en uppräkning som bara är tillgänglig för funktioner och skriptblock.
Mer information finns i about_Automatic_Variables.
- När funktionen anropas
Process
i början, eller utanför en pipeline, körs blocket en gång. - I en pipeline
Process
körs blocket en gång för varje indataobjekt som når funktionen. - Om pipelineindata som når funktionen är tomma
Process
körs inte blocket.- Blocken
Begin
ochEnd
körs fortfarande.
- Blocken
Viktigt
Om en funktionsparameter är inställd på att acceptera pipelineindata och ett Process
block inte har definierats misslyckas bearbetningen av post för post. I det här fallet körs funktionen bara en gång, oavsett indata.
Slut
Det här blocket används för att tillhandahålla valfri efterbearbetning en gång för funktionen.
I följande exempel visas konturen för en funktion som innehåller ett Begin
block för engångsförbearbetning, ett Process
block för bearbetning av flera poster och ett End
block för engångsefterbearbetning.
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
Anteckning
Om du använder antingen ett Begin
eller End
ett block måste du definiera alla tre blocken. När du använder alla tre blocken måste all PowerShell-kod finnas i ett av blocken.
Bekräftelsemetoder
ShouldProcess
Den här metoden anropas för att begära bekräftelse från användaren innan funktionen utför en åtgärd som skulle ändra systemet. Funktionen kan fortsätta baserat på det booleska värdet som returneras av metoden. Den här metoden kan bara anropas inifrån funktionsblocket Process{}
. Attributet CmdletBinding
måste också deklarera att funktionen stöder ShouldProcess
(vilket visas i föregående exempel).
Mer information om den här metoden finns i System.Management.Automation.Cmdlet.ShouldProcess.
Mer information om hur du begär bekräftelse finns i Begära bekräftelse.
ShouldContinue
Den här metoden anropas för att begära ett andra bekräftelsemeddelande. Den ska anropas när ShouldProcess
metoden returnerar $true
. Mer information om den här metoden finns i System.Management.Automation.Cmdlet.ShouldContinue.
Felmetoder
Funktioner kan anropa två olika metoder när fel inträffar. När ett icke-avslutande fel inträffar ska funktionen anropa WriteError
metoden, som beskrivs i Write
avsnittet metoder. När ett avslutande fel inträffar och funktionen inte kan fortsätta bör den ThrowTerminatingError
anropa metoden. Du kan också använda -instruktionen Throw
för att avsluta fel och cmdleten Write-Error för icke-avslutande fel.
Mer information finns i System.Management.Automation.Cmdlet.ThrowTerminatingError.
Skrivmetoder
En funktion kan anropa följande metoder för att returnera olika typer av utdata.
Observera att inte alla utdata går till nästa kommando i pipelinen. Du kan också använda de olika Write
cmdletarna, till exempel Write-Error
.
WriteCommandDetail
Information om metoden finns i WriteCommandDetails
System.Management.Automation.Cmdlet.WriteCommandDetail.
WriteDebug
Om du vill ange information som kan användas för att felsöka en funktion gör du så att funktionen anropar WriteDebug
metoden. Metoden WriteDebug
visar felsökningsmeddelanden för användaren. Mer information finns i System.Management.Automation.Cmdlet.WriteDebug.
WriteError
Functions bör anropa den här metoden när icke-avslutande fel inträffar och funktionen är utformad för att fortsätta bearbeta poster. Mer information finns i System.Management.Automation.Cmdlet.WriteError.
Anteckning
Om ett avslutande fel inträffar ska funktionen anropa metoden ThrowTerminatingError .
WriteObject
Med WriteObject
metoden kan funktionen skicka ett objekt till nästa kommando i pipelinen. I de flesta fall WriteObject
är den metod som ska användas när funktionen returnerar data. Mer information finns i System.Management.Automation.PSCmdlet.WriteObject.
WriteProgress
För funktioner med åtgärder som tar lång tid att slutföra tillåter den här metoden att funktionen anropar WriteProgress
metoden så att förloppsinformation visas. Du kan till exempel visa procent färdigt.
Mer information finns i System.Management.Automation.PSCmdlet.WriteProgress.
WriteVerbose
Om du vill ge detaljerad information om vad funktionen gör kan du göra så att funktionen anropar WriteVerbose
metoden för att visa utförliga meddelanden för användaren. Som standard visas inte utförliga meddelanden. Mer information finns i System.Management.Automation.PSCmdlet.WriteVerbose.
WriteWarning
Om du vill ange information om villkor som kan orsaka oväntade resultat kan du göra så att funktionen anropar metoden WriteWarning för att visa varningsmeddelanden för användaren. Som standard visas varningsmeddelanden. Mer information finns i System.Management.Automation.PSCmdlet.WriteWarning.
Anteckning
Du kan också visa varningsmeddelanden genom att konfigurera variabeln $WarningPreference
eller med hjälp av kommandoradsalternativen Verbose
och Debug
. Mer information om variabeln finns i $WarningPreference
about_Preference_Variables.
Andra metoder och egenskaper
Information om andra metoder och egenskaper som kan nås via variabeln $PSCmdlet
finns i System.Management.Automation.PSCmdlet.
Med egenskapen ParameterSetName kan du till exempel se den parameteruppsättning som används. Med parameteruppsättningar kan du skapa en funktion som utför olika uppgifter baserat på de parametrar som anges när funktionen körs.
Se även
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute