Dela via

about_Functions_Advanced_Methods

Kort beskrivning

Beskriver hur funktioner som anger attributet CmdletBinding kan använda de metoder och egenskaper som är tillgängliga för kompilerade cmdletar.

Lång beskrivning

Funktioner som anger attributet CmdletBinding kan komma åt ytterligare metoder och egenskaper via variabeln $PSCmdlet. Dessa metoder omfattar följande metoder:

  • Samma metoder för indatabearbetning som är tillgängliga för alla funktioner.
  • De ShouldProcess- och ShouldContinue metoder 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 CmdletBinding finns i about_Functions_CmdletBindingAttribute. För klassen CmdletBindingAttribute, se System.Management.Automation.Cmdlet.CmdletBindingAttribute.

Metoder för indatabearbetning

Metoderna som beskrivs i det här avsnittet kallas för indatabearbetningsmetoder. För funktioner representeras dessa tre metoder av begin, processoch end block i funktionen. PowerShell 7.3 lägger till en clean blockprocessmetod.

Du behöver inte använda något av dessa block i dina funktioner. Om du inte använder ett namngivet block placerar PowerShell koden i end-blocket för funktionen. Men om du använder något av dessa namngivna block eller definierar ett dynamicparam block måste du placera all kod i ett namngivet block.

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ångspostbearbetning.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

Not

Dessa block gäller för alla funktioner, inte bara funktioner som använder attributet CmdletBinding.

begin

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äknare som bara är tillgänglig för funktioner och skriptblock. Mer information finns i about_Automatic_Variables.

  • När funktionen anropas i början, eller utanför en pipeline, körs process-blocket en gång.
  • I en pipeline körs process-blocket en gång för varje indataobjekt som når funktionen.
  • Om pipelineindata som når funktionen är tomma process blockera inte köras.
    • Blocken begin, endoch clean körs fortfarande.

Viktig

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.

När du skapar en funktion som accepterar pipelineindata och använder CmdletBindingska process-blocket använda parametervariabeln som du definierade för pipelineindata i stället för $_ eller $PSItem. Till exempel:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

Det här blocket används för att tillhandahålla valfri engångspostbearbetning för funktionen.

clean

Det clean blocket lades till i PowerShell 7.3.

Det clean blocket är ett bekvämt sätt för användare att rensa resurser som sträcker sig över blocken begin, processoch end. Det liknar semantiskt ett finally block som omfattar alla andra namngivna block i en skriptfunktion eller en skript-cmdlet. Resursrensning tillämpas för följande scenarier:

  1. när pipelinekörningen slutförs normalt utan att felet avslutas
  2. när pipelinekörningen avbryts på grund av ett avslutande fel
  3. när pipelinen stoppas av Select-Object -First
  4. när pipelinen stoppas av Ctrl+ c eller StopProcessing()

Det rena blocket tar bort alla utdata som skrivs till dataströmmen Lyckades.

Försiktighet

Att lägga till clean-blocket är en icke-bakåtkompatibel ändring. Eftersom clean parsas som ett nyckelord hindrar det användare från att direkt anropa ett kommando med namnet clean som den första instruktionen i en scriptblock. Det är dock inte troligt att det är ett problem. Kommandot kan fortfarande anropas med hjälp av anropsoperatorn (& clean).

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ärde som returneras av metoden. Den här metoden kan bara anropas inifrån process {}-blocket för funktionen. Attributet CmdletBinding måste också deklarera att funktionen stöder ShouldProcess (som du ser 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. Det bör anropas när metoden ShouldProcess 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 metoden WriteError, som beskrivs i avsnittet Write metoder. När ett avslutande fel inträffar och funktionen inte kan fortsätta bör den anropa metoden ThrowTerminatingError. Du kan också använda throw-instruktionen 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 WriteCommandDetails finns i 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 metoden WriteDebug. 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.

Not

Om ett avslutande fel inträffar ska funktionen anropa metoden ThrowTerminatingError.

WriteObject

Med metoden WriteObject kan funktionen skicka ett objekt till nästa kommando i pipelinen. I de flesta fall är WriteObject 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 metoden WriteProgress 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 ange detaljerad information om vad funktionen gör gör du så att funktionen anropar metoden WriteVerbose 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.

Not

Du kan också visa varningsmeddelanden genom att konfigurera $WarningPreference-variabeln eller med hjälp av kommandoradsalternativen Verbose och Debug. Mer information om variabeln $WarningPreference finns i 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 parameteruppsättningen 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

  • Last updated on