Delen via

about_Functions_Advanced_Methods

  • Artikel

Korte beschrijving

Beschrijft hoe functies die het CmdletBinding kenmerk opgeven, de methoden en eigenschappen kunnen gebruiken die beschikbaar zijn voor gecompileerde cmdlets.

Lange beschrijving

Functies die het CmdletBinding kenmerk opgeven, hebben toegang tot aanvullende methoden en eigenschappen via de $PSCmdlet variabele. Deze methoden omvatten de volgende methoden:

  • Dezelfde invoerverwerkingsmethoden die beschikbaar zijn voor alle functies.
  • De ShouldProcess en ShouldContinue methoden die worden gebruikt om feedback van gebruikers te krijgen voordat een actie wordt uitgevoerd.
  • De ThrowTerminatingError methode voor het genereren van foutrecords.
  • Verschillende Write methoden die verschillende typen uitvoer retourneren.

Alle methoden en eigenschappen van de PSCmdlet-klasse zijn beschikbaar voor geavanceerde functies. Zie System.Management.Automation.PSCmdlet voor meer informatie.

Zie about_Functions_CmdletBindingAttribute voor meer informatie over het CmdletBinding kenmerk. Zie System.Management.Automation.CmdletBindingAttribute voor de klasse CmdletBindingAttribute.

Invoerverwerkingsmethoden

De methoden die in deze sectie worden beschreven, worden de invoerverwerkingsmethoden genoemd. Voor functies worden deze drie methoden vertegenwoordigd door de begin, processen end blokken van de functie. PowerShell 7.3 voegt een clean blokprocesmethode toe.

U hoeft geen van deze blokken in uw functies te gebruiken. Als u geen benoemd blok gebruikt, plaatst PowerShell de code in het end blok van de functie. Als u echter een van deze benoemde blokken gebruikt of een dynamicparam blok definieert, moet u alle code in een benoemd blok plaatsen.

In het volgende voorbeeld ziet u het overzicht van een functie die een begin blok bevat voor eenmalige verwerking, een process blok voor meerdere recordverwerking en een end blok voor eenmalige naverwerking.

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

Notitie

Deze blokken zijn van toepassing op alle functies, niet alleen op functies die gebruikmaken van het CmdletBinding kenmerk.

begin

Dit blok wordt gebruikt om optionele eenmalige voorverwerking voor de functie op te geven. De PowerShell-runtime gebruikt de code in dit blok één keer voor elk exemplaar van de functie in de pijplijn.

process

Dit blok wordt gebruikt voor record-by-recordverwerking voor de functie. U kunt een process blok gebruiken zonder de andere blokken te definiëren. Het aantal blokuitvoeringen is afhankelijk van process hoe u de functie gebruikt en welke invoer de functie ontvangt.

De automatische variabele $_ of $PSItem bevat het huidige object in de pijplijn voor gebruik in het process blok. De $input automatische variabele bevat een enumerator die alleen beschikbaar is voor functies en scriptblokken. Zie about_Automatic_Variables voor meer informatie.

  • Als u de functie aan het begin of buiten een pijplijn aanroept, wordt het process blok eenmaal uitgevoerd.
  • Binnen een pijplijn wordt het process blok eenmaal uitgevoerd voor elk invoerobject dat de functie bereikt.
  • Als de pijplijninvoer die de functie bereikt leeg is, wordt het process blok niet uitgevoerd.
    • De begin, enden clean blokken worden nog steeds uitgevoerd.

Belangrijk

Als een functieparameter is ingesteld op het accepteren van pijplijninvoer en er process geen blok is gedefinieerd, mislukt record-by-recordverwerking. In dit geval wordt uw functie slechts eenmaal uitgevoerd, ongeacht de invoer.

Wanneer u een functie maakt die pijplijninvoer accepteert en gebruikt CmdletBinding, moet het process blok de parametervariabele gebruiken die u hebt gedefinieerd voor pijplijninvoer in plaats van $_ of $PSItem. Voorbeeld:

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

Dit blok wordt gebruikt om optionele eenmalige naverwerking voor de functie te bieden.

clean

Het clean blok is toegevoegd in PowerShell 7.3.

Het clean blok is een handige manier voor gebruikers om resources op te schonen die zich over de begin, processen end blokken beslaan. Het is semantisch vergelijkbaar met een finally blok dat alle andere benoemde blokken van een scriptfunctie of een script-cmdlet omvat. Het opschonen van resources wordt afgedwongen voor de volgende scenario's:

  1. wanneer de uitvoering van de pijplijn normaal is voltooid zonder afsluitfout
  2. wanneer de uitvoering van de pijplijn wordt onderbroken vanwege een afsluitfout
  3. wanneer de pijplijn is gestopt door Select-Object -First
  4. wanneer de pijplijn wordt gestopt door Ctrl+c of StopProcessing()

Het schone blok negeert alle uitvoer die naar de geslaagde stroom is geschreven.

Let op

Het toevoegen van het clean blok is een belangrijke wijziging. Omdat clean deze wordt geparseerd als een trefwoord, voorkomt u dat gebruikers rechtstreeks een opdracht aanroepen met de naam clean als de eerste instructie in een scriptblok. Het is echter waarschijnlijk geen probleem. De opdracht kan nog steeds worden aangeroepen met behulp van de aanroepoperator (& clean).

Bevestigingsmethoden

ShouldProcess

Deze methode wordt aangeroepen om bevestiging van de gebruiker aan te vragen voordat de functie een actie uitvoert die het systeem zou wijzigen. De functie kan doorgaan op basis van de Booleaanse waarde die door de methode wordt geretourneerd. Deze methode kan alleen worden aangeroepen vanuit het Process{} blok van de functie. Het CmdletBinding kenmerk moet ook declareren dat de functie ondersteunt ShouldProcess (zoals wordt weergegeven in het vorige voorbeeld).

Zie System.Management.Automation.Cmdlet.ShouldProcess voor meer informatie over deze methode.

Zie Bevestiging aanvragen voor meer informatie over het aanvragen van bevestiging.

ShouldContinue

Deze methode wordt aangeroepen om een tweede bevestigingsbericht aan te vragen. Deze moet worden aangeroepen wanneer de ShouldProcess methode wordt geretourneerd $true. Zie System.Management.Automation.Cmdlet.ShouldContinue voor meer informatie over deze methode.

Foutmethoden

Functies kunnen twee verschillende methoden aanroepen wanneer er fouten optreden. Wanneer er een niet-afsluitfout optreedt, moet de functie de WriteError methode aanroepen, die wordt beschreven in de Write sectie methoden. Wanneer er een afsluitfout optreedt en de functie niet kan doorgaan, moet deze de ThrowTerminatingError methode aanroepen. U kunt ook de Throw instructie gebruiken voor afsluitfouten en de cmdlet Write-Error voor niet-afsluitfouten.

Zie System.Management.Automation.Cmdlet.ThrowTerminatingError voor meer informatie.

Schrijfmethoden

Een functie kan de volgende methoden aanroepen om verschillende typen uitvoer te retourneren. U ziet dat niet alle uitvoer naar de volgende opdracht in de pijplijn gaat. U kunt ook de verschillende Write cmdlets gebruiken, zoals Write-Error.

WriteCommandDetail

Zie System.Management.Automation.Cmdlet.WriteCommandDetail voor meer informatie over de WriteCommandDetails methode.

WriteDebug

Als u informatie wilt opgeven die kan worden gebruikt om problemen met een functie op te lossen, roept u de methode WriteDebug aan. De WriteDebug methode geeft foutopsporingsberichten weer voor de gebruiker. Zie System.Management.Automation.Cmdlet.WriteDebug voor meer informatie.

WriteError

Functies moeten deze methode aanroepen wanneer er niet-afsluitfouten optreden en de functie is ontworpen om de verwerking van records voort te zetten. Zie System.Management.Automation.Cmdlet.WriteError voor meer informatie.

Notitie

Als er een afsluitfout optreedt, moet de functie de methode ThrowTerminatingError aanroepen.

WriteObject

Met WriteObject de methode kan de functie een object verzenden naar de volgende opdracht in de pijplijn. In de meeste gevallen WriteObject is dit de methode die moet worden gebruikt wanneer de functie gegevens retourneert. Zie System.Management.Automation.PSCmdlet.WriteObject voor meer informatie.

WriteProgress

Voor functies met acties die lang duren voordat deze methode is voltooid, kan de functie de WriteProgress methode aanroepen, zodat voortgangsinformatie wordt weergegeven. U kunt bijvoorbeeld het percentage voltooid weergeven. Zie System.Management.Automation.PSCmdlet.WriteProgress voor meer informatie.

WriteVerbose

Als u gedetailleerde informatie wilt geven over wat de functie doet, roept u de functie de WriteVerbose methode aan om uitgebreide berichten weer te geven aan de gebruiker. Uitgebreide berichten worden standaard niet weergegeven. Zie System.Management.Automation.PSCmdlet.WriteVerbose voor meer informatie.

WriteWarning

Als u informatie wilt geven over voorwaarden die onverwachte resultaten kunnen veroorzaken, roept u de functie de Methode WriteWarning aan om waarschuwingsberichten weer te geven aan de gebruiker. Standaard worden waarschuwingsberichten weergegeven. Zie System.Management.Automation.PSCmdlet.WriteWarning voor meer informatie.

Notitie

U kunt ook waarschuwingsberichten weergeven door de $WarningPreference variabele te configureren of door de Verbose en Debug opdrachtregelopties te gebruiken. Zie about_Preference_Variables voor meer informatie over de $WarningPreference variabele.

Andere methoden en eigenschappen

Zie System.Management.Automation.PSCmdlet voor informatie over de andere methoden en eigenschappen die toegankelijk zijn via de $PSCmdlet variabele.

Met de eigenschap ParameterSetName kunt u bijvoorbeeld de parameterset zien die wordt gebruikt. Met parametersets kunt u een functie maken die verschillende taken uitvoert op basis van de parameters die worden opgegeven wanneer de functie wordt uitgevoerd.

Zie ook