about_Functions_Advanced_Methods

  • Artikel

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 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.
  • Metoderna ShouldProcess och ShouldContinue 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.

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- och processend -blocken 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 funktionsblocket end . 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 efterbearbetning en gång.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

Kommentar

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 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, endoch clean körs fortfarande.

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.

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

Blocket clean lades till i PowerShell 7.3.

Blocket clean ä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()

Varning

clean Att lägga till 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 ett skriptblock. 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 funktionsblocket Process{} . 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. 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 anropa ThrowTerminatingError 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.

Kommentar

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, gör funktionen anropa 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.

Kommentar

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 finns i $PSCmdletSystem.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