Delen via

about_Functions_Advanced_Methods

Korte beschrijving

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

Lange beschrijving

Functies die het kenmerk CmdletBinding 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.PSCmdletvoor meer informatie.

Zie CmdletBindingvoor meer informatie over het kenmerk . Zie voor de klasse CmdletBindingAttributeSystem.Management.Automation.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 met een begin blok 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 kenmerk CmdletBinding.

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 process blokuitvoeringen is afhankelijk van 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 scriptblokkeringen. Zie about_Automatic_Variablesvoor 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 een process blok niet is gedefinieerd, mislukt de verwerking van records per record. In dit geval wordt uw functie slechts eenmaal uitgevoerd, ongeacht de invoer.

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

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 wordt gestopt door Select-Object -First
  4. wanneer de pijplijn wordt gestopt door Ctrl+c- of StopProcessing()

Het schone blok verwijdert alle uitvoer die naar de geslaagde stream is geschreven.

Voorzichtigheid

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 kenmerk CmdletBinding moet ook aangeven dat de functie ondersteuning biedt voor ShouldProcess (zoals weergegeven in het vorige voorbeeld).

Zie System.Management.Automation.Cmdlet.ShouldProcessvoor meer informatie over deze methode.

Zie Bevestiging aanvragenvoor 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 $trueretourneert. Zie System.Management.Automation.Cmdlet.ShouldContinuevoor 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 sectie Write methoden. Wanneer er een afsluitfout optreedt en de functie niet kan worden voortgezet, moet de ThrowTerminatingError methode worden aangeroepen. U kunt ook de throw instructie gebruiken voor afsluitfouten en de write-error cmdlet voor niet-afsluitfouten.

Zie System.Management.Automation.Cmdlet.ThrowTerminatingErrorvoor 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 WriteCommandDetailsvoor meer informatie over de methode .

WriteDebug

Als u informatie wilt opgeven die kan worden gebruikt om problemen met een functie op te lossen, roept u de functie de WriteDebug methode aan. De methode WriteDebug geeft foutopsporingsberichten weer aan de gebruiker. Zie System.Management.Automation.Cmdlet.WriteDebugvoor 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.WriteErrorvoor meer informatie.

Notitie

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

WriteObject

Met de methode WriteObject kan de functie een object verzenden naar de volgende opdracht in de pijplijn. In de meeste gevallen is WriteObject de methode die moet worden gebruikt wanneer de functie gegevens retourneert. Zie System.Management.Automation.PSCmdlet.WriteObjectvoor 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.WriteProgressvoor 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.WriteVerbosevoor 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.WriteWarningvoor meer informatie.

Notitie

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

Andere methoden en eigenschappen

Zie $PSCmdletvoor informatie over de andere methoden en eigenschappen die toegankelijk zijn via de 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

  • Last updated on