Delen via

8. Verklaringen

Redactionele notitie

Belangrijk

De Windows PowerShell Language Specification 3.0 is gepubliceerd in december 2012 en is gebaseerd op Windows PowerShell 3.0. Deze specificatie geeft niet de huidige status van PowerShell weer. Er is geen plan om deze documentatie bij te werken om de huidige status weer te geven. Deze documentatie wordt hier gepresenteerd voor historische naslaginformatie.

Het specificatiedocument is beschikbaar als een Microsoft Word-document in het Microsoft Downloadcentrum op: https://www.microsoft.com/download/details.aspx?id=36389 Dat Word-document hier is geconverteerd voor presentatie in Microsoft Learn. Tijdens de conversie zijn enkele redactionele wijzigingen aangebracht om opmaak voor het Docs-platform mogelijk te maken. Sommige typfouten en kleine fouten zijn gecorrigeerd.

8.1 Statementblokken en lijsten

Syntaxis:

Fooi

De ~opt~ notatie in de syntaxisdefinities geeft aan dat de lexicale entiteit optioneel is in de syntaxis.

statement-block:
    new-lines~opt~ { statement-list~opt~ new-lines~opt~ }

statement-list:
    statement
    statement-list statement

statement:
    if-statement
    label~opt~ labeled-statement
    function-statement
    flow-control-statement statement-terminator
    trap-statement
    try-statement
    data-statement
    inlinescript-statement
    parallel-statement
    sequence-statement
    pipeline statement-terminator

statement-terminator:
    ;
    new-line-character

Beschrijving:

Een -instructie geeft een soort actie op die moet worden uitgevoerd. Tenzij anders in deze clausule wordt aangegeven, worden instructies uitgevoerd in lexicale volgorde.

Met een instructieblok kan een set instructies worden gegroepeerd in één syntactische eenheid.

8.1.1 Gelabelde verklaringen

Syntaxis:

labeled-statement:
    switch-statement
    foreach-statement
    for-statement
    while-statement
    do-statement

Beschrijving:

Een herhalingsinstructie (§8.4) of een schakelinstructie (§8.6) kan eventueel direct worden voorafgegaan door één instructielabel, label. Een instructielabel wordt gebruikt als het optionele doel van een onderbreking (§8.5.1) of doorgaan (§8.5.2) instructie. Een label verandert echter niet de controlestroom.

Witruimte is niet toegestaan tussen de dubbele punt (:) en het token dat erop volgt.

Voorbeelden:

:go_here while ($j -le 100) {
    # ...
}

:labelA
for ($i = 1; $i -le 5; ++$i) {
    :labelB
    for ($j = 1; $j -le 3; ++$j) {
        :labelC
        for ($k = 1; $k -le 2; ++$k) {
            # ...
        }
    }
}

8.1.2 Declaratiewaarden

De waarde van een verklaring is de set cumulatieve waarden die naar de pijplijn worden geschreven. Als de instructie één scalaire waarde schrijft, is dat de waarde van de instructie. Als de instructie meerdere waarden schrijft, is de waarde van de instructie die set waarden die zijn opgeslagen in elementen van een niet-gekoppelde 1-dimensionale matrix, in de volgorde waarin ze zijn geschreven. Bekijk het volgende voorbeeld:

$v = for ($i = 10; $i -le 5; ++$i) { }

Er zijn geen iteraties van de lus en er wordt niets naar de pijplijn geschreven. De waarde van de stelling is $null.

$v = for ($i = 1; $i -le 5; ++$i) { }

Hoewel de lus vijf keer wordt herhaald, wordt er niets naar de pijplijn geschreven. De waarde van de uitdrukking is $null.

$v = for ($i = 1; $i -le 5; ++$i) { $i }

De lus herhaalt vijf keer en schrijft daarbij elke keer de int waarde naar de pijplijn $i. De waarde van de instructie is object[] van lengte 5.

$v = for ($i = 1; $i -le 5; ) { ++$i }

Hoewel de lus vijf keer wordt herhaald, wordt er niets naar de pijplijn geschreven. De waarde van de stelling is $null.

$v = for ($i = 1; $i -le 5; ) { (++$i) }

De lus herhaalt zich vijf keer waarbij elke waarde naar de pijplijn wordt geschreven. De waarde van de instructie is object[] van lengte 5.

$i = 1; $v = while ($i++ -lt 2) { $i }

De lus wordt eenmaal herhaald. De waarde van de verklaring is de int met waarde 2.

Hier volgen enkele andere voorbeelden:

# if $count is not currently defined then define it with int value 10
$count = if ($count -eq $null) { 10 } else { $count }

$i = 1
$v = while ($i -le 5) {
    $i                   # $i is written to the pipeline
    if ($i -band 1) {

        "odd"            # conditionally written to the pipeline

    }

    ++$i                 # not written to the pipeline

}
# $v is object[], Length 8, value 1,"odd",2,3,"odd",4,5,"odd"

8.2 Pijplijninstructies

Syntaxis:

pipeline:
    assignment-expression
    expression redirections~opt~ pipeline-tail~opt~
    command verbatim-command-argument~opt~ pipeline-tail~opt~

assignment-expression:
    expression assignment-operator statement

pipeline-tail:
    | new-lines~opt~ command
    | new-lines~opt~ command pipeline-tail

command:
    command-name command-elements~opt~
    command-invocation-operator command-module~opt~ command-name-expr command-elements~opt~

command-invocation-operator: one of
    &   .

command-module:
    primary-expression

command-name:
    generic-token
    generic-token-with-subexpr

generic-token-with-subexpr:
    No whitespace is allowed between ) and command-name.
    generic-token-with-subexpr-start statement-list~opt~ )

command-namecommand-name-expr:
    command-name

primary-expressioncommand-elements:
    command-element
    command-elements command-element

command-element:
    command-parameter
    command-argument
    redirection

command-argument:
    command-name-expr

verbatim-command-argument:
    --% verbatim-command-argument-chars

Beschrijving:

omleidingen worden besproken in §7.12; toewijzingsexpressies worden besproken in §7.11; en de opdracht-aanroep-operator punt (.) wordt besproken in §3.5.5. Raadpleeg §8.14voor een discussie over de toewijzing van argumenten aan parameters in opdracht-aanroepen.

De eerste opdracht in een pijplijn is een expressie of een opdrachtaanroep. Een aanroep van een opdracht begint doorgaans met een opdrachtnaam, wat meestal een kale identificator is. opdrachtelementen vertegenwoordigt de lijst met argumenten voor de opdracht. Een nieuwe regel of een ongescaped puntkomma beëindigt een pijplijn.

Een aanroep van een opdracht bestaat uit de naam van de opdracht, gevolgd door nul of meer argumenten. De regels voor argumenten zijn als volgt:

  • Een argument dat geen expressie is, maar dat willekeurige tekst zonder ongescapte witruimte bevat, wordt behandeld alsof het tussen dubbele aanhalingstekens staat. De letterkast wordt behouden.

  • Variabele vervanging en subexpressieuitbreiding (§2.3.5.2) vindt plaats in uitbreidbare tekenreeks-literalsen uitvouwbare hier-tekenreeks-literals.

  • Met tekst tussen aanhalingstekens kunnen voorloop-, volg- en ingesloten witruimte worden opgenomen in de waarde van het argument. [Opmerking: de aanwezigheid van witruimte in een aanhalingsargument verandert een enkel argument niet in meerdere argumenten. eindnotitie]

  • Als u haakjes rond een argument plaatst, wordt de expressie geëvalueerd met het resultaat dat wordt doorgegeven in plaats van de tekst van de oorspronkelijke expressie.

  • Als u een argument wilt doorgeven dat lijkt op een schakelparameter (§2.3.4) maar niet als zodanig is bedoeld, plaatst u dat argument tussen aanhalingstekens.

  • Wanneer u een argument opgeeft dat overeenkomt met een parameter met de typebeperking [switch] (§8.10.5), zorgt de aanwezigheid van alleen de argumentnaam ervoor dat die parameter wordt ingesteld op $true. De waarde van de parameter kan echter expliciet worden ingesteld door een achtervoegsel toe te voegen aan het argument. Bijvoorbeeld, voor een parameter met typebeperking p, stelt een argument van -p:$true p in op waar, terwijl -p:$false p op onwaar instelt.

  • Een argument van -- geeft aan dat alle argumenten die erop volgen, moeten worden doorgegeven in hun werkelijke vorm alsof er dubbele aanhalingstekens zijn geplaatst.

  • Een argument van --% geeft aan dat alle volgende argumenten moeten worden doorgegeven met minimale parsering en verwerking. Dit argument wordt de exacte parameter genoemd. Argumenten na de exacte parameter zijn geen PowerShell-expressies, zelfs niet als ze syntactisch geldige PowerShell-expressies zijn.

Als het opdrachttype Toepassing is, wordt de parameter --% niet doorgegeven aan de opdracht. De argumenten na --% worden uitgebreid met de omgevingsvariabelen (tekenreeksen omgeven door %). Bijvoorbeeld:

echoargs.exe --% "%path%" # %path% is replaced with the value $Env:path

De volgorde van de evaluatie van argumenten is niet opgegeven.

Zie §8.14voor informatie over parameterbinding. Zie §3.8voor meer informatie over naamzoekacties.

Zodra de verwerking van argumenten is voltooid, wordt de opdracht aangeroepen. Als de aangeroepen opdracht normaal wordt beëindigd (§8.5.4), keert het besturingselement terug naar het punt in het script of de functie direct na de aanroep van de opdracht. Voor een beschrijving van het gedrag bij abnormale beëindiging, zie break (§8.5.1), continue (§8.5.2), throw (§8.5.3), exit (§8.5.5), try (§8.7) en trap (§8.8).

Normaal gesproken wordt een opdracht aangeroepen met behulp van de naam, gevolgd door argumenten. De opdracht-aanroepoperator, &, kan echter worden gebruikt. Als de opdrachtnaam ongesluierde witruimte bevat, moet deze tussen aanhalingstekens worden geplaatst en met deze operator worden aangeroepen. Omdat een scriptblok geen naam heeft, moet het ook worden aangeroepen met deze operator. De volgende aanroepen van een opdrachtoproep Get-Factorial zijn bijvoorbeeld gelijkwaardig:

Get-Factorial 5
& Get-Factorial 5
& "Get-Factorial" 5

Directe en indirecte recursieve functie-aanroepen zijn toegestaan. Bijvoorbeeld

function Get-Power([int]$x, [int]$y) {
    if ($y -gt 0) { return $x * (Get-Power $x (--$y)) }
    else { return 1 }
}

Voorbeelden:

New-Object 'int[,]' 3,2
New-Object -ArgumentList 3,2 -TypeName 'int[,]'

dir E:\PowerShell\Scripts\*statement*.ps1 | ForEach-Object {$_.Length}

dir E:\PowerShell\Scripts\*.ps1 |
    Select-String -List "catch" |
    Format-Table Path, LineNumber -AutoSize

8.3 De if-verklaring

Syntaxis:

if-statement:
    if new-lines~opt~ ( new-lines~opt~ pipeline new-lines~opt~ ) statement-block
        elseif-clauses~opt~ else-clause~opt~

elseif-clauses:
    elseif-clause
    elseif-clauses elseif-clause

elseif-clause:
    new-lines~opt~ elseif new-lines~opt~ ( new-lines~opt~ pipeline new-lines~opt~ ) statement-block

else-clause:
    new-lines~opt~ else statement-block

Beschrijving:

De expressies die door de pijplijn worden beheerd, moeten het type bool hebben of impliciet naar dat type kunnen worden geconverteerd. De else-clausule is optioneel. Er kunnen nul of meer elseif-clause's zijn.

Als de pijplijn op het bovenste niveau Waar is, wordt het instructieblok uitgevoerd, en wordt de uitvoering van de instructie beëindigd. Anders, als er een elseif-clausule aanwezig is en als de pijplijn Waar is, dan wordt het instructieblok uitgevoerd en eindigt de uitvoering van de instructie. Als een else-clausule aanwezig is, wordt het instructieblok uitgevoerd.

Voorbeelden:

$grade = 92
if ($grade -ge 90) { "Grade A" }
elseif ($grade -ge 80) { "Grade B" }
elseif ($grade -ge 70) { "Grade C" }
elseif ($grade -ge 60) { "Grade D" }
else { "Grade F" }

8.4 Iteratie-instructies

8.4.1 De while-instructie

Syntaxis:

while-statement:
    while new-lines~opt~ ( new-lines~opt~ while-condition new-lines~opt~ ) statement-block

while-condition:
    new-lines~opt~ pipeline

Beschrijving:

De besturingsexpressie while-condition moet een type bool hebben of impliciet converteerbaar zijn naar dat type. De hoofdtekst van de lus, die bestaat uit instructieblok, wordt herhaaldelijk uitgevoerd totdat de controle-expressie False test. De besturingsuitdrukking wordt geëvalueerd vóór elke uitvoering van het luslichaam.

Voorbeelden:

$i = 1
while ($i -le 5) {                     # loop 5 times
    "{0,1}`t{1,2}" -f $i, ($i*$i)
    ++$i
}

8.4.2 De do-opdracht

Syntaxis:

do-statement:
    do statement-block new-lines~opt~ while new-lines~opt~ ( while-condition new-lines~opt~ )
    do statement-block new-lines~opt~ until new-lines~opt~ ( while-condition new-lines~opt~ )

while-condition:
    new-lines~opt~ pipeline

Beschrijving:

De besturingsexpressie while-condition moet een type bool hebben of impliciet converteerbaar zijn naar dat type. In de while-lus wordt de hoofdtekst van de lus, dat bestaat uit het instructieblok, herhaaldelijk uitgevoerd zolang de controle-expressie waar is. In de until-vorm wordt de lus herhaaldelijk uitgevoerd totdat de controle-expressie waar is. De controle-uitdrukking wordt geëvalueerd na elke uitvoering van het luslichaam.

Voorbeelden:

$i = 1
do {
    "{0,1}`t{1,2}" -f $i, ($i * $i)
}
while (++$i -le 5)                 # loop 5 times

$i = 1
do {
    "{0,1}`t{1,2}" -f $i, ($i * $i)
}
until (++$i -gt 5)                 # loop 5 times

8.4.3 De for-lus

Syntaxis:

for-statement:
    for new-lines~opt~ (
        new-lines~opt~ for-initializer~opt~ statement-terminator
        new-lines~opt~ for-condition~opt~ statement-terminator
        new-lines~opt~ for-iterator~opt~
        new-lines~opt~ ) statement-block

    for new-lines~opt~ (
        new-lines~opt~ for-initializer~opt~ statement-terminator
        new-lines~opt~ for-condition~opt~
        new-lines~opt~ ) statement-block

    for new-lines~opt~ (
        new-lines~opt~ for-initializer~opt~
        new-lines~opt~ ) statement-block

for-initializer:
    pipeline

for-condition:
    pipeline

for-iterator:
    pipeline

Beschrijving:

De besturingsexpressie voor voorwaarde moet een type bool hebben of impliciet kunnen worden geconverteerd naar dat type. De hoofdtekst van de lus, die bestaat uit instructieblok, wordt herhaaldelijk uitgevoerd terwijl de besturingsexpressie Waar test. De besturingsuitdrukking wordt geëvalueerd vóór elke uitvoering van het luslichaam.

Expressie voor initialisatie wordt geëvalueerd vóór de eerste evaluatie van de besturingsexpressie. Expressie voor initialisatie wordt alleen geëvalueerd voor de bijwerkingen; elke waarde die wordt geproduceerd, wordt verwijderd en wordt niet naar de pijplijn geschreven.

Expressie voor iterator wordt geëvalueerd na elke uitvoering van de inhoud van de lus. Expressie for-iterator wordt alleen geëvalueerd vanwege de bijwerkingen; elke waarde die wordt geproduceerd, wordt verwijderd en wordt niet naar de pijplijn geschreven.

Als expressie voor voorwaarde wordt weggelaten, test de controle-expressie op true.

Voorbeelden:

for ($i = 5; $i -ge 1; --$i) { # loop 5 times
    "{0,1}`t{1,2}" -f $i, ($i * $i)
}

$i = 5
for (; $i -ge 1; ) { # equivalent behavior
    "{0,1}`t{1,2}" -f $i, ($i * $i)
    --$i
}

8.4.4 De foreach-instructie

Syntaxis:

foreach-statement:
    foreach new-lines~opt~ foreach-parameter~opt~ new-lines~opt~
        ( new-lines~opt~ variable new-lines~opt~ *in* new-lines~opt~ pipeline
        new-lines~opt~ ) statement-block

foreach-parameter:
    -parallel

Beschrijving:

Het luslichaam, dat bestaat uit instructieblok, wordt uitgevoerd voor elke door de variabele variabele aangeduide element in de verzameling die is aangewezen door pijplijn. Het bereik van variabele is niet beperkt tot de foreach-instructie. Als zodanig behoudt het de eindwaarde nadat de lus gereed is. Als pijplijn een scalaire waarde aanwijst (met uitzondering van de waarde $null) in plaats van een verzameling, wordt die scalaire waarde beschouwd als een verzameling van één element. Als pijplijn de waarde $nullaanwijst, wordt pijplijn beschouwd als een verzameling nulelementen.

Als de foreach-parameter-parallel is opgegeven, is het gedrag implementatieafhankelijk.

De foreach-parameter‑parallel is alleen toegestaan in een werkstroom (§8.10.2).

Elke foreach-instructie heeft een eigen enumerator, $foreach (§2.3.2.2, §4.5.16), die alleen bestaat terwijl die lus wordt uitgevoerd.

De objecten die door de pijplijn worden geproduceerd, worden verzameld voordat het instructieblok wordt uitgevoerd. Echter, met de cmdlet ForEach-Object wordt het instructieblok uitgevoerd op elk object terwijl het wordt geproduceerd.

Voorbeelden:

$a = 10, 53, 16, -43
foreach ($e in $a) {
    ...
}
$e # the int value -43

foreach ($e in -5..5) {
    ...
}

foreach ($t in [byte], [int], [long]) {
    $t::MaxValue # get static property
}

foreach ($f in Get-ChildItem *.txt) {
    ...
}

$h1 = @{ FirstName = "James"; LastName = "Anderson"; IDNum = 123 }
foreach ($e in $h1.Keys) {
    "Key is " + $e + ", Value is " + $h1[$e]
}

8.5 Stroombesturingsinstructies

Syntaxis:

flow-control-statement:
    break label-expression~opt~
    continue label-expression~opt~
    throw pipeline~opt~
    return pipeline~opt~
    exit pipeline~opt~

label-expression:
    simple-name
    unary-expression

Beschrijving:

Een instructie voor stroombeheer zorgt voor een onvoorwaardelijke overdracht van controle naar een andere locatie.

8.5.1 De onderbrekingsinstructie

Beschrijving:

Een onderbrekingsinstructie met een labelexpressie wordt een gelabelde onderbrekingsinstructiegenoemd. Een onderbrekingsinstructie zonder een labelexpressie wordt een niet-gelabelde onderbrekingsinstructiegenoemd.

Buiten een trapinstructie beëindigt een niet-gelabelde onderbrekingsinstructie rechtstreeks binnen een iteratie-instructie (§8.4) de uitvoering van de kleinste omsluitende iteratie-instructie. Een niet-gelabelde onderbrekingsinstructie rechtstreeks binnen een schakelinstructie (§8.6) beëindigt patroonkoppeling voor de switchvoorwaarde. Zie (§8.8) voor meer informatie over het gebruik van onderbrekingen binnen een trapinstructie.

Een iteratie-instructie of een switchinstructie kan eventueel direct voorafgegaan worden door één instructielabel (§8.1.1). Een dergelijk instructielabel kan worden gebruikt als doelwit van een gelabelde break-instructie. In dat geval beëindigt die instructie de uitvoering van de doelgerichte omhullende iteratie-instructie.

Een gelabelde break hoeft niet te worden opgelost in een lokale scope; de zoektocht naar een overeenkomend label kan door de aanroepstack heen gaan, zelfs over grenzen van scripts en functieoproepen heen. Als er geen overeenkomend label wordt gevonden, wordt de huidige aanroep van de opdracht beëindigd.

De naam van het label dat is aangewezen door label-expressie hoeft geen constante waarde te hebben.

Als labelexpressie een unaire expressieis, wordt deze geconverteerd naar een tekenreeks.

Voorbeelden:

$i = 1
while ($true) { # infinite loop
    if ($i * $i -gt 100) {
        break # break out of current while loop
    }
    ++$i
}

$lab = "go_here"
:go_here
for ($i = 1; ; ++$i) {
    if ($i * $i -gt 50) {
        break $lab # use a string value as target
    }
}

:labelA
for ($i = 1; $i -le 2; $i++) {

    :labelB
    for ($j = 1; $j -le 2; $j++) {

        :labelC
        for ($k = 1; $k -le 3; $k++) {
            if (...) { break labelA }
        }
    }
}

8.5.2 De continue-verklaring

Beschrijving:

Een continue-instructie met een labelexpressie wordt een gelabelde continue instructie genoemd. Een continue instructie zonder een labelexpressie wordt een niet-gelabelde continue instructiegenoemd.

Het gebruik van continue vanuit een trapinstructie wordt besproken in §8.8.

Een niet-gelabelde continue instructie binnen een lus beëindigt de uitvoering van de huidige lus en draagt de controle over naar de afsluitende accolade van de kleinste omsluitende iteratie-instructie (§8.4). Een niet-gelabelde continue instructie binnen een switch beëindigt de uitvoering van de huidige switch iteratie en draagt de controle over naar de kleinste omsluitende switch's switchvoorwaarde (§8.6).

Een iteratie-instructie of een switch instructie (§8.6) kan eventueel direct worden voorafgegaan door één instructielabel (§8.1.1). Zo'n instructielabel kan dienen als het doel van een ingesloten, gelabelde continue instructie. In dat geval beëindigt deze instructie de uitvoering van de huidige lus of switch iteratie en neemt de controle over naar de daaropvolgende beoogde iteratie of switch instructielabel.

Een gemarkeerd label continue hoeft niet te worden opgelost binnen een lokale scope; het zoeken naar een overeenkomend label kan continue de aanroepende stack oplopen, zelfs script- en functie-oproepgrenzen overschrijden. Als er geen overeenkomend label wordt gevonden, wordt de huidige aanroep van de opdracht beëindigd.

De naam van het label dat is aangewezen door label-expressie hoeft geen constante waarde te hebben.

Als labelexpressie een unaire expressieis, wordt deze geconverteerd naar een tekenreeks.

Voorbeelden:

$i = 1
while (...) {
    ...
    if (...) {
        continue # start next iteration of current loop
    }
    ...
}

$lab = "go_here"
:go_here
for (...; ...; ...) {
    if (...) {
        continue $lab # start next iteration of labeled loop
    }
}

:labelA
for ($i = 1; $i -le 2; $i++) {

    :labelB
    for ($j = 1; $j -le 2; $j++) {

        :labelC
        for ($k = 1; $k -le 3; $k++) {
            if (...) { continue labelB }
        }
    }
}

8.5.3 De throw-opdracht

Beschrijving:

Een uitzondering is een manier om een foutvoorwaarde op systeem- of toepassingsniveau te verwerken. De throw-instructie roept een uitzondering op. (Zie §8.7 voor een bespreking van de afhandeling van uitzonderingen.)

Als de -pipeline wordt weggelaten en de throw-instructie zich niet in een catch-clausebevindt, is het gedrag afhankelijk van de implementatie. Als pijplijn aanwezig is en de throw-instructie zich in een catch-clausulebevindt, wordt de uitzondering die is opgevangen door die catch-clausule opnieuw gegooid nadat een finally-clausule die is gekoppeld aan de catch-clausule wordt uitgevoerd.

Als pijplijn aanwezig is, is het type van de gegenereerde uitzondering door de implementatie gedefinieerd.

Wanneer er een uitzondering wordt opgeworpen, wordt de controle overgebracht naar de eerste catch-clausule in een omsluitend try-blok dat de uitzondering kan verwerken. De locatie waar de uitzondering in eerste instantie wordt gegenereerd, wordt het throw pointgenoemd. Zodra er een uitzondering is opgetreden, worden de stappen die beschreven staan in §8.7 herhaaldelijk gevolgd totdat een catch-blok dat overeenkomt met de uitzondering wordt gevonden of er geen wordt gevonden.

Voorbeelden:

throw
throw 100
throw "No such record in file"

Als pijplijn wordt weggelaten en de throw-instructie niet afkomstig is van een catch-clausule, wordt de tekst "ScriptHalted" naar de pijplijn geschreven en wordt het type uitzondering System.Management.Automation.RuntimeException.

Als pijplijn aanwezig is, wordt de gegenereerde uitzondering verpakt in een object van het type System.Management.Automation.RuntimeException, dat informatie over de uitzondering bevat als een System.Management.Automation.ErrorRecord-object (toegankelijk via $_).

Voorbeeld 1: throw 123 resulteert in een uitzondering van het type RuntimeException. Vanuit het catch-blok bevat $_.TargetObject het object dat binnenin verpakt is, in dit geval een System.Int32 met de waarde 123.

Voorbeeld 2: throw "xxx" resulteert in een uitzondering van het type RuntimeException. Vanuit het catch-blok bevat $_.TargetObject het object dat erin zit, in dit geval een System.String met de waarde "xxx".

Voorbeeld 3: throw 10,20 resulteert in een uitzondering van het type RuntimeException. Vanuit het catch-blok bevat $_.TargetObject het object dat erin is gewikkeld, in dit geval een System.Object[], een ongelimiteerde array van twee elementen met de System.Int32`-waarden 10 en 20.

8.5.4 De return-instructie

Beschrijving:

De return-instructie schrijft naar de pijplijn de waarde(s) die zijn aangewezen door pijplijn, indien van toepassing, en retourneert het besturingselement naar de aanroeper van de functie of het script. Een functie of script kan nul of meer return instructies hebben.

Als de uitvoering de sluit-accolade van een functie bereikt, wordt een impliciete return zonder pijplijn aangenomen.

De return-verklaring is een beetje "syntactische suiker" die programmeurs in staat stelt zichzelf uit te drukken zoals in andere talen. De waarde die echter door een functie of script wordt geretourneerd, omvat alle waarden die door die functie of dat script naar de pijplijn worden geschreven, plus de waarde(n) die zijn opgegeven door de pijplijn . Als er slechts een scalaire waarde naar de pijplijn wordt geschreven, is het bijbehorende type het type van de geretourneerde waarde; anders is het retourtype een niet-gekoppelde 1-dimensionale matrix met alle waarden die naar de pijplijn zijn geschreven.

Voorbeelden:

function Get-Factorial ($v) {
    if ($v -eq 1) {
        return 1 # return is not optional
    }

    return $v * (Get-Factorial ($v - 1)) # return is optional
}

De beller naar Get-Factorial krijgt een intterug.

function Test {
    "text1" # "text1" is written to the pipeline
    # ...
    "text2" # "text2" is written to the pipeline
    # ...
    return 123 # 123 is written to the pipeline
}

De aanroeper van Test krijgt een ongelimiteerde 1-dimensionale array van drie elementen terug.

8.5.5 De afsluitinstructie

Beschrijving:

De afsluitinstructie beëindigt het huidige script en geeft de controle en een exitcode terug aan de hostomgeving of het aanroepende script. Als pijplijn wordt opgegeven, wordt de waarde die deze aanwijst, zo nodig geconverteerd naar int. Als er geen dergelijke conversie bestaat of als pijplijn wordt weggelaten, wordt de int-waarde nul geretourneerd.

Voorbeelden:

exit $count # terminate the script with some accumulated count

8.6 De schakelinstructie

Syntaxis:

switch-statement:
    switch new-lines~opt~ switch-parameters~opt~ switch-condition switch-body

switch-parameters:
    switch-parameter
    switch-parameters switch-parameter

switch-parameter:
    -Regex
    -Wildcard
    -Exact
    -CaseSensitive
    -Parallel

switch-condition:
    ( new-lines~opt~ pipeline new-lines~opt~ )
    -File new-lines~opt~ switch-filename

switch-filename:
    command-argument
    primary-expression

switch-body:
    new-lines~opt~ { new-lines~opt~ switch-clauses }

switch-clauses:
    switch-clause
    switch-clauses switch-clause

switch-clause:
    switch-clause-condition statement-block statement-terimators~opt~

switch-clause-condition:
    command-argument
    primary-expression

Beschrijving:

Als switchvoorwaarde één waarde aanwijst, wordt het besturingselement doorgegeven aan een of meer overeenkomende patrooninstructieblokken. Als er geen patronen overeenkomen, kan er een aantal standaardacties worden uitgevoerd.

Een switch moet een of meer switchcomponents bevatten, elk beginnend met een patroon (een niet-standaardswitchcomponent) of het trefwoord default (een standaardswitchcomponent). Een switch moet nul of één default-switchclausule bevatten en nul of meer niet-standaard switchclausules. Switch-clausules kunnen in elke volgorde worden geschreven.

Meerdere patronen kunnen dezelfde waarde hebben. Een patroon hoeft niet letterlijk te zijn en een switch kan patronen met verschillende typen hebben.

Als de waarde van switch-voorwaarde overeenkomt met een patroonwaarde, wordt het instructieblok van dat patroon uitgevoerd. Als meerdere patroonwaarden overeenkomen met de waarde van switchvoorwaarde, wordt het instructieblok van elk overeenkomend patroon uitgevoerd in lexicale volgorde, tenzij een van deze instructieblokeen break instructie bevat (§8.5.1).

Als de waarde van switchvoorwaarde niet overeenkomt met een patroonwaarde en er een default switchcomponent bestaat, wordt het instructieblok uitgevoerd; anders wordt de patroonkoppeling voor die switchvoorwaarde beëindigd.

Schakelaars kunnen worden genest, waarbij elke schakelaar een eigen set schakeluitspraken heeft. In dergelijke gevallen behoort een switch-clause tot de binnenste switch die actueel in het bereik is.

Bij binnenkomst van elk instructieblokwordt $_ automatisch de waarde toegewezen van de switchvoorwaarde die ervoor zorgt dat de controle naar dat instructieblokgaat. $_ is ook beschikbaar in de switch-clause-condition van dat instructieblok.

Het vergelijken van niet-tekstuele objecten wordt uitgevoerd door te testen op gelijkheid (§7.8.1).

Als de vergelijking tekenreeksen omvat, is de vergelijking standaard niet hoofdlettergevoelig. De aanwezigheid van de schakelparameter-CaseSensitive maakt de vergelijking hoofdlettergevoelig.

Een patroon kan jokertekens bevatten (§3.15), in welk geval jokertekenreeksvergelijkingen worden uitgevoerd, maar alleen als de schakelparameter-Wildcard aanwezig is. De vergelijking is standaard ongevoelig voor hoofdlettergebruik.

Een patroon kan een reguliere expressie bevatten (§3.16), in welk geval tekenreeksvergelijkingen voor reguliere expressies worden uitgevoerd, maar alleen als de switchparameter-Regex aanwezig is. De vergelijking is standaard ongevoelig voor hoofdlettergebruik. Als -Regex aanwezig is en een patroon overeenkomt, wordt $Matches in de switch-clausestatement-block voor dat patroon gedefinieerd.

Een switchparameter kan worden afgekort; elk afzonderlijk voorloopgedeelte van een parameter kan worden gebruikt. Bijvoorbeeld: ‑Regex, ‑Rege, ‑Reg, ‑Reen ‑R zijn gelijkwaardig.

Als conflicterende switchparameters worden opgegeven, heeft de laatste in lexicale volgorde voorrang. De aanwezigheid van ‑Exact schakelt -Regex en -Wildcarduit; het heeft echter geen invloed op ‑Case.

Als de switchparameter‑Parallel is opgegeven, wordt het gedrag bepaald door de implementatie.

De schakelparameter‑Parallel is alleen toegestaan in een werkstroom (§8.10.2).

Als een patroon een scriptblokexpressieis, wordt dat blok geëvalueerd en wordt het resultaat indien nodig geconverteerd naar bool. Als het resultaat de waarde $trueheeft, wordt het bijbehorende -instructieblok uitgevoerd; zo niet, dan niet.

Als switchvoorwaarde meerdere waarden aanwijst, wordt de schakeloptie toegepast op elke waarde in lexicale volgorde met behulp van de hierboven beschreven regels voor een switchvoorwaarde die één waarde aanwijst. Elke schakelinstructie heeft een eigen enumerator, $switch (§2.3.2.2, §4.5.16), die alleen bestaat terwijl die schakeloptie wordt uitgevoerd.

Een switch-instructie kan een label hebben en kan gelabelde en ongelabelde break (§8.5.1) en continue (§8.5.2) instructies bevatten.

Als schakelvoorwaarde is -Fileswitch-bestandsnaam, in plaats van de waarden in een expressie te herhalen, herhaalt de schakelaar de waarden in het bestand dat wordt aangeduid door switch-bestandsnaam. Het bestand wordt regel voor regel gelezen waarbij elke regel een waarde omvat. Regeleindtekens worden niet opgenomen in de waarden.

Voorbeelden:

$s = "ABC def`nghi`tjkl`fmno @#$"
$charCount = 0; $pageCount = 0; $lineCount = 0; $otherCount = 0
for ($i = 0; $i -lt $s.Length; ++$i) {
    ++$charCount
    switch ($s[$i]) {
        "`n" { ++$lineCount }
        "`f" { ++$pageCount }
        "`t" { }
        " " { }
        default { ++$otherCount }
    }
}

switch -Wildcard ("abc") {
    a* { "a*, $_" }
    ?B? { "?B? , $_" }
    default { "default, $_" }
}

switch -Regex -CaseSensitive ("abc") {
    ^a* { "a*" }
    ^A* { "A*" }
}

switch (0, 1, 19, 20, 21) {
    { $_ -lt 20 } { "-lt 20" }
    { $_ -band 1 } { "Odd" }
    { $_ -eq 19 } { "-eq 19" }
    default { "default" }
}

8.7 De instructie try/finally

Syntaxis:

try-statement:
    try statement-block catch-clauses
    try statement-block finally-clause
    try statement-block catch-clauses finally-clause

catch-clauses:
    catch-clause
    catch-clauses catch-clause

catch-clause:
    new-lines~opt~ catch catch-type-list~opt~
    statement-block

catch-type-list:
    new-lines~opt~ type-literal
    catch-type-list new-lines~opt~ , new-lines~opt~

type-literalfinally-clause:
    new-lines~opt~ finally statement-block

Beschrijving:

De try-instructie biedt een mechanisme voor het vangen van uitzonderingen die optreden tijdens het uitvoeren van een blok. De instructie try biedt ook de mogelijkheid om een codeblok op te geven dat altijd wordt uitgevoerd wanneer het besturingselement de instructie Try verlaat. Het proces van het indienen van een uitzondering via de instructie throw wordt beschreven in §8.5.3.

Een try block is het instructieblok gekoppeld aan de try-instructie. Een catch-blok is het instructieblok geassocieerd met een catch clausule. Een ten slotte-blok is het instructieblok dat is gekoppeld aan een finally-clausule.

Een catch-clause zonder een catch-typelijst wordt een algemene catch-clausegenoemd.

Elke catch-clausule is een exceptiehandleren een catch-clausule waarvan catch-type-list het type van de opgeworpen uitzondering bevat, is een overeenkomende catch-clausule. Een algemene catch-clausule komt overeen met alle uitzonderingstypen.

Hoewel catch-clausules en finally-clausule optioneel zijn, moet er ten minste één van hen aanwezig zijn.

De verwerking van een opgetreden uitzondering bestaat uit het herhaaldelijk doorlopen van de volgende stappen totdat een catch-blok dat overeenkomt met de uitzondering wordt gevonden.

  • In het huidige bereik wordt elke try-instructie die het werppunt omsluit, onderzocht. Voor elke try-instructie S, beginnend met de binnenste try-instructie en eindigend met de buitenste try-instructie, worden de volgende stappen geëvalueerd:

    • Als het try blok van S het gooipunt omsluit en als S een of meer catch-componenten heeft, worden de catch-componenten in lexicale volgorde onderzocht om een geschikte handler voor de uitzondering te vinden. De eerste catch-clause die het uitzonderingstype of een basistype van het uitzonderingstype specificeert, komt overeen. Een algemeen catch-blok wordt beschouwd als passend bij elk uitzonderingstype. Als er een overeenkomende catch-clausule gevonden is, wordt de uitzonderingsverwerking voltooid door de controle over te dragen aan het blok van die catch-clausule. Binnen een overeenkomende catch-component bevat de variabele $_ een beschrijving van de huidige uitzondering.

    • Als het try-blok of een catch-blok van S het throw-punt omsluit en S een finally-blok heeft, wordt de besturing overgedragen aan het finally-blok. Als het finally blok een andere uitzondering genereert, wordt de verwerking van de huidige uitzondering beëindigd. Anders wordt de verwerking van de huidige uitzondering voortgezet wanneer het besturingselement het einde van het finally blok bereikt.

  • Als een uitzonderingshandler zich niet in het huidige bereik bevindt, worden de bovenstaande stappen herhaald voor het omsluitende bereik met een worpunt dat overeenkomt met de instructie waaruit het huidige bereik is aangeroepen.

  • Als de uitzonderingsverwerking uiteindelijk alle bereiken beëindigt, wat aangeeft dat er geen handler bestaat voor de uitzondering, is het gedrag niet gespecificeerd.

Om onbereikbare catch-componenten in een try-blok te voorkomen, geeft een catch-component mogelijk geen uitzonderingstype op dat gelijk is aan of is afgeleid van een type dat is opgegeven in een eerdere catch-component binnen datzelfde try-blok.

De instructies van een finally blok worden altijd uitgevoerd wanneer het besturingselement een try instructie verlaat. Dit is waar of de controleoverdracht plaatsvindt als gevolg van normale uitvoering, als gevolg van het uitvoeren van een break, continueof return instructie, of als gevolg van een uitzondering die uit de try-instructie wordt gegenereerd.

Als er een uitzondering wordt gegenereerd tijdens het uitvoeren van een finally-blok, wordt de uitzondering doorgegeven naar de volgende omsluitende try-instructie. Als er een andere uitzondering werd verwerkt, gaat die uitzondering verloren. Het proces voor het genereren van een uitzondering wordt verder besproken in de beschrijving van de throw-instructie.

try instructies kunnen naast trap instructies bestaan; zie §8.8 voor meer informatie.

Voorbeelden:

$a = New-Object 'int[]' 10
$i = 20 # out-of-bounds subscript

while ($true) {
    try {
        $a[$i] = 10
        "Assignment completed without error"
        break
    }

    catch [IndexOutOfRangeException] {
        "Handling out-of-bounds index, >$_<`n"
        $i = 5
    }

    catch {
        "Caught unexpected exception"
    }

    finally {
        # ...
    }
}

Elke uitzondering die wordt geworpen, wordt als een System.Management.Automation.RuntimeExceptionuitgevoerd. Als er typespecifieke catch-clauses in het try blok staan, wordt de property InnerException van de uitzondering gecontroleerd om een overeenkomst te vinden, zoals met het bovengenoemde type System.IndexOutOfRangeException.

8.8 De trapinstructie

Syntaxis:

trap-statement:
    *trap* new-lines~opt~ type-literal~opt~ new-lines~opt~ statement-block

Beschrijving:

Een trap instructie met en zonder type-letterlijke is vergelijkbaar met een catch blok (§8,7) met en zonder catch-type-list, behalve dat een trap instructie slechts één type tegelijk kan vangen.

Meerdere trap-instructies kunnen worden gedefinieerd in dezelfde instructiebloken de volgorde van de definitie is niet relevant. Als twee trap instructies met dezelfde type-letterlijke in dezelfde scope zijn gedefinieerd, wordt de lexicaal eerste instructie gebruikt om een uitzondering van het overeenkomende type te verwerken.

In tegenstelling tot een catch blok komt een trap-instructie exact overeen met een uitzonderingstype; er geen afgeleide typekoppeling wordt uitgevoerd.

Wanneer er een uitzondering optreedt, als er geen overeenkomende trap-instructie aanwezig is in het huidige bereik, wordt een overeenkomende trap-instructie gezocht in het omringende bereik, waarbij mogelijk wordt gekeken in het script, de functie of het filter dat oproept, en daarna in de oproeper, enzovoort. Als de zoekactie uiteindelijk alle bereiken beëindigt en daarmee aangeeft dat er geen handler bestaat voor de uitzondering, is de uitkomst niet gespecificeerd.

Het instructielichaam van een trap instructie wordt alleen uitgevoerd om de bijbehorende uitzondering te verwerken; anders wordt er overheen gegaan.

Als het instructieblok van een normaal verloopt, wordt standaard een foutobject naar de foutstroom geschreven, wordt de uitzondering als afgehandeld beschouwd en gaat de uitvoering door met de instructie direct na de instructie in het bereik van de -instructie die de uitzondering zichtbaar maakte. De oorzaak van de uitzondering kan zich in een opdracht bevinden die wordt aangeroepen door de opdracht met de instructie trap.

Als de laatste instructie in de instructietekst van een trap de continue-instructie is (§8.5.2), wordt het schrijven van het foutobject naar de foutstroom onderdrukt en wordt de uitvoering voortgezet met de instructie direct na degene in het bereik met de trapinstructie die de uitzondering zichtbaar maakte. Als de laatste instructie die in het trap van een wordt uitgevoerd, break (§8.5.1) is, wordt het schrijven van het foutobject naar de foutstroom onderdrukt en wordt de uitzondering opnieuw gegooid.

Binnen een trap instructie bevat de variabele $_ een beschrijving van de huidige fout.

Houd rekening met het geval waarin een uitzondering die vanuit een try blok wordt gegenereerd, geen overeenkomend catch blok heeft, maar er een overeenkomende trap-instructie bestaat op een hoger blokniveau. Nadat de eindklausule van het try-blok is uitgevoerd, krijgt de trap-instructie controle, zelfs als een bovenliggende scope een overeenkomend catch-blok heeft. Als een trap instructie is gedefinieerd binnen het try blok zelf en dat try blok een overeenkomend catch blok heeft, krijgt de trap instructie controle.

Voorbeelden:

In het volgende voorbeeld wordt het foutobject geschreven en wordt de uitvoering voortgezet met de instructie direct na de instructie die de onderbreking heeft veroorzaakt; dat wil zeggen: 'Done' wordt naar de pijplijn geschreven.

$j = 0; $v = 10/$j; "Done"
trap { $j = 2 }

In het volgende voorbeeld wordt het schrijven van het foutobject onderdrukt en gaat de uitvoering verder met de instructie direct na degene die de val veroorzaakte. Met andere woorden, 'Gereed' wordt naar de pijplijn geschreven.

$j = 0; $v = 10/$j; "Done"
trap { $j = 2; continue }

In het volgende voorbeeld wordt het schrijven van het foutobject onderdrukt en wordt de uitzondering opnieuw gegooid.

$j = 0; $v = 10/$j; "Done"
trap { $j = 2; break }

In het volgende voorbeeld bevinden de trap- en uitzondering-genererende instructies zich in dezelfde scope. Nadat de uitzondering is opgevangen en verwerkt, wordt de uitvoering hervat met het schrijven van 1 naar de pijplijn.

&{trap{}; throw '\...'; 1}

In het volgende voorbeeld bevinden de val- en uitzonderingsgenererende instructies zich in verschillende scopes. Nadat de uitzondering is opgevangen en verwerkt, wordt de uitvoering hervat met het schrijven van 2 (niet 1) naar de pijplijn.

trap{} &{throw '\...'; 1}; 2

8.9 De gegevensverklaring

Syntaxis:

data-statement:
    data new-lines~opt~ data-name data-commands-allowed~opt~ statement-block

data-name:
    simple-name

data-commands-allowed:
    new-lines~opt~ -SupportedCommand data-commands-list

data-commands-list:
    new-lines~opt~ data-command
    data-commands-list , new-lines~opt~ data-command

data-command:
    command-name-expr

Beschrijving:

Een gegevensinstructie maakt een gegevenssectie, waardoor de gegevens van die sectie gescheiden blijven van de code. Deze scheiding ondersteunt faciliteiten zoals afzonderlijke tekenreeksresourcebestanden voor tekst, zoals foutberichten en Help-tekenreeksen. Het helpt ook internationalisering te ondersteunen door tekenreeksen die in verschillende talen worden vertaald gemakkelijker te isoleren, te lokaliseren en te verwerken.

Een script of functie kan nul of meer gegevenssecties bevatten.

Het instructieblok van een gegevenssectie is beperkt tot alleen de volgende PowerShell-functies:

  • Alle operators behalve -match
  • De if-verklaring
  • De volgende automatische variabelen: $PSCulture, $PSUICulture, $true, $falseen $null.
  • Opmerkingen
  • Pijpleidingen
  • Uitspraken gescheiden door puntkomma's (;)
  • Letterlijke tekens
  • Oproepen van de cmdlet ConvertFrom-StringData
  • Alle andere cmdlets die worden geïdentificeerd via de SupportedCommand parameter

Als de ConvertFrom-StringData cmdlet wordt gebruikt, kunnen de sleutel-/waardeparen worden uitgedrukt met elke vorm van letterlijke tekenreeks. uitbreidbare letterlijke tekenreekss en uitbreidbare letterlijke tekenreekss mogen echter geen variabelevervangingen of uitbreidingen van subexpressies bevatten.

Voorbeelden:

De parameter SupportedCommand geeft aan dat de opgegeven cmdlets of functies alleen gegevens genereren. De volgende gegevenssectie bevat bijvoorbeeld een door de gebruiker geschreven cmdlet, ConvertTo-Xml, waarmee gegevens in een XML-bestand worden opgemaakt:

data -SupportedCommand ConvertTo-Xml {
    Format-Xml -Strings string1, string2, string3
}

Bekijk het volgende voorbeeld, waarin de gegevenssectie een ConvertFrom-StringData opdracht bevat waarmee de tekenreeksen worden geconverteerd naar een hash-tabel, waarvan de waarde is toegewezen aan $messages.

$messages = data {
    ConvertFrom-StringData -StringData @'
    Greeting = Hello
    Yes = yes
    No = no
'@
}

De sleutels en waarden van de hash-tabel worden geopend met respectievelijk $messages.Greeting, $messages.Yesen $messages.No.

Dit kan nu worden opgeslagen als een Engelstalige resource. Duits- en Spaanstalige resources kunnen worden gemaakt in afzonderlijke bestanden, met de volgende gegevenssecties:

$messages = data {
    ConvertFrom-StringData -StringData @"
    Greeting = Guten Tag
    Yes = ja
    No = nein
"@
}

$messagesS = data {
    ConvertFrom-StringData -StringData @"
    Greeting = Buenos días
    Yes = sí
    No = no
"@
}

Als gegevensnaam aanwezig is, geeft het de naam van de variabele aan (zonder gebruik van een voorloop-$) waarin de waarde van de dataopdracht moet worden opgeslagen. Met name is $name = data { ... } gelijk aan data name { ... }.

8.10 Functiedefinities

Syntaxis:

function-statement:
    function new-lines~opt~ function-name function-parameter-declaration~opt~ { script-block }
    filter new-lines~opt~ function-name function-parameter-declaration~opt~ { script-block }
    workflow new-lines~opt~ function-name function-parameter-declaration~opt~ { script-block }

function-name:
    command-argument

command-argument:
    command-name-expr

function-parameter-declaration:
    new-lines~opt~ ( parameter-list new-lines~opt~ )

parameter-list:
    script-parameter
    parameter-list new-lines~opt~ , script-parameter

script-parameter:
    new-lines~opt~ attribute-list~opt~ new-lines~opt~ variable script-parameter-default~opt~

script-block:
    param-block~opt~ statement-terminators~opt~ script-block-body~opt~

param-block:
    new-lines~opt~ attribute-list~opt~ new-lines~opt~ param new-lines~opt~
        ( parameter-list~opt~ new-lines~opt~ )

parameter-list:
    script-parameter
    parameter-list new-lines~opt~ , script-parameter

script-parameter-default:
    new-lines~opt~ = new-lines~opt~ expression

script-block-body:
    named-block-list
    statement-list

named-block-list:
    named-block
    named-block-list named-block

named-block:
    block-name statement-block statement-terminators~opt~

block-name: one of
    dynamicparam   begin   process   end

Beschrijving:

Een functiedefinitie geeft de naam op van de functie, het filter of de werkstroom die wordt gedefinieerd en de namen van de parameters, indien van toepassing. Het bevat ook nul of meer instructies die worden uitgevoerd om het doel van die functie te bereiken.

Elke functie is een exemplaar van de klasse System.Management.Automation.FunctionInfo.

8.10.1 Filterfuncties

Terwijl een gewone functie eenmaal in een pijplijn wordt uitgevoerd en de invoerverzameling via $inputopent, is een filter een speciaal soort functie die eenmaal wordt uitgevoerd voor elk object in de invoerverzameling. Het object dat momenteel wordt verwerkt, is beschikbaar via de variabele $_.

Een filter zonder benoemde blokken (§8.10.7) is gelijk aan een functie met een procesblok, maar zonder begin- of eindblok.

Houd rekening met de volgende filterfunctiedefinitie en aanroepen:

filter Get-Square2 { # make the function a filter
    $_ * $_ # access current object from the collection
}

-3..3 | Get-Square2 # collection has 7 elements
6, 10, -3 | Get-Square2 # collection has 3 elements

Elk filter is een exemplaar van de klasse System.Management.Automation.FilterInfo (§4.5.11).

8.10.2 Werkstroomfuncties

Een werkstroomfunctie is net als een gewone functie met door de implementatie gedefinieerde semantiek. Een werkstroomfunctie wordt vertaald naar een reeks Windows Workflow Foundation-activiteiten en uitgevoerd in de Windows Workflow Foundation-engine.

8.10.3 Argumentverwerking

Houd rekening met de volgende definitie voor een functie met de naam Get-Power:

function Get-Power ([long]$Base, [int]$Exponent) {
    $result = 1
    for ($i = 1; $i -le $Exponent; ++$i) {
        $result *= $Base
    }
    return $result
}

Deze functie heeft twee parameters, $Base en $Exponent. Het bevat ook een set instructies die, voor niet-negatieve exponentwaarden, $Base^$Exponent^ berekent en het resultaat retourneert aan Get-Power's beller.

Wanneer een script, functie of filter wordt uitgevoerd, wordt elke parameter geïnitialiseerd met de bijbehorende waarde van het argument. Als er geen corresponderend argument is en er een standaardwaarde (§8.10.4) wordt opgegeven, wordt die waarde gebruikt; anders wordt de waarde $null gebruikt. Als zodanig is elke parameter een nieuwe variabele, net zoals wanneer deze is geïnitialiseerd door de toewijzing aan het begin van het scriptblok.

Als een scriptparameter een typebeperking bevat (zoals [long] en [int] hierboven), wordt de waarde van het bijbehorende argument indien nodig geconverteerd naar dat type; anders wordt er geen conversie uitgevoerd.

Wanneer een script, functie of filter wordt uitgevoerd, wordt variabele $args hierin gedefinieerd als een niet-gekoppelde 1-dimensionale matrix, die alle argumenten bevat die niet afhankelijk zijn van naam of positie, in lexicale volgorde.

Houd rekening met de volgende functiedefinitie en aanroepen:

function F ($a, $b, $c, $d) { ... }

F -b 3 -d 5 2 4       # $a is 2, $b is 3, $c is 4, $d is 5, $args Length 0
F -a 2 -d 3 4 5       # $a is 2, $b is 4, $c is 5, $d is 3, $args Length 0
F 2 3 4 5 -c 7 -a 1   # $a is 1, $b is 2, $c is 7, $d is 3, $args Length 2

Zie §8.14voor meer informatie over parameterbinding.

8.10.4 Parameterinitialisaties

De declaratie van een parameter p kan een initialiser bevatten. In dat geval wordt de waarde van die initialiser gebruikt om p te initialiseren, op voorwaarde dat p niet gebonden is aan argumenten in de aanroep.

Houd rekening met de volgende functiedefinitie en aanroepen:

function Find-Str ([string]$Str, [int]$StartPos = 0) { ... }

Find-Str "abcabc" # 2nd argument omitted, 0 used for $StartPos
Find-Str "abcabc" 2 # 2nd argument present, so it is used for $StartPos

8.10.5 De typerestrictie [switch]

Wanneer een schakelparameter wordt doorgegeven, moet de bijbehorende parameter in de opdracht worden beperkt door de typeswitch. Typeschakelaar heeft twee waarden, Waar en Onwaar.

Houd rekening met de volgende functiedefinitie en aanroepen:

function Process ([switch]$Trace, $P1, $P2) { ... }

Process 10 20                # $Trace is False, $P1 is 10, $P2 is 20
Process 10 -Trace 20         # $Trace is True, $P1 is 10, $P2 is 20
Process 10 20 -Trace         # $Trace is True, $P1 is 10, $P2 is 20
Process 10 20 -Trace:$false  # $Trace is False, $P1 is 10, $P2 is 20
Process 10 20 -Trace:$true   # $Trace is True, $P1 is 10, $P2 is 20

8.10.6 Pijplijnen en functies

Wanneer een script, functie of filter wordt gebruikt in een pijplijn, wordt een verzameling waarden aan dat script of die functie geleverd. Het script, de functie of het filter krijgt toegang tot die verzameling via de enumerator $input (§2.3.2.2, §4.5.16), die is gedefinieerd voor de vermelding van dat script, de functie of het filter.

Houd rekening met de volgende functiedefinitie en aanroepen:

function Get-Square1 {
    foreach ($i in $input) {   # iterate over the collection
        $i * $i
    }
}

-3..3 | Get-Square1            # collection has 7 elements
6, 10, -3 | Get-Square1        # collection has 3 elements

8.10.7 Benoemde blokken

De instructies binnen een scriptblok kunnen deel uitmaken van één groot, niet-benoemd blok of kunnen worden gedistribueerd naar een of meer benoemde blokken. Benoemde blokken maken aangepaste verwerking van verzamelingen mogelijk die afkomstig zijn van pijplijnen; benoemde blokken kunnen in elke volgorde worden gedefinieerd.

De instructies in een begin-blok (dat wil zeggen, een blok dat is gemarkeerd met het trefwoord begin) worden eenmaal uitgevoerd voordat het eerste pijplijnobject wordt verstrekt.

De instructies in een procesblok (bijvoorbeeld één die is gemarkeerd met het trefwoordproces) worden uitgevoerd voor elk pijplijnobject dat wordt geleverd. ($_ biedt toegang tot het huidige object dat wordt verwerkt vanuit de invoerverzameling die afkomstig is van de pijplijn.) Dit betekent dat als een verzameling nulelementen via de pijplijn wordt verzonden, het procesblok helemaal niet wordt uitgevoerd. Als het script of de functie echter buiten een pijplijncontext wordt aangeroepen, wordt dit blok precies één keer uitgevoerd en wordt $_ ingesteld op $null, omdat er geen huidig verzamelingsobject is.

De instructies in een eindblok (bijvoorbeeld één gemarkeerd met het trefwoordeinde) worden eenmaal uitgevoerd nadat het laatste pijplijnobject is geleverd.

8.10.8 dynamicparam block

De subsecties van §8.10 hebben tot nu toe betrekking op statische parameters, die zijn gedefinieerd als onderdeel van de broncode. Het is ook mogelijk om dynamische parameters te definiëren via een dynamicparam-blok, een andere vorm van benoemd blok (§8.10.7), gemarkeerd door het trefwoord dynamicparam. Veel van deze systemen zijn implementatie-gedefinieerd.

Dynamische parameters zijn parameters van een cmdlet, functie, filter of script die alleen beschikbaar zijn onder bepaalde voorwaarden. Een dergelijk geval is de -coderingsparameter van de Set-Item-cmdlet.

Gebruik in het instructieblokeen if-instructie om de voorwaarden op te geven waaronder de parameter beschikbaar is in de functie. Gebruik de cmdlet New-Object om een object van een door de implementatie gedefinieerd type te maken dat de parameter vertegenwoordigt en geef de naam op. Gebruik ook New-Object om een object van een ander door de implementatie gedefinieerd type te maken om de door de implementatie gedefinieerde kenmerken van de parameter weer te geven.

In het volgende voorbeeld ziet u een functie met standaardparameters met de naam Name en Path en een optionele dynamische parameter met de naam DP1. De parameter DP1 bevindt zich in de PSet1-parameterset en heeft een type Int32. De parameter DP1 is alleen beschikbaar in de voorbeeldfunctie wanneer de waarde van de parameter Path 'HKLM:' bevat, waarmee wordt aangegeven dat deze wordt gebruikt in het registerstation HKEY_LOCAL_MACHINE.

function Sample {
    param ([string]$Name, [string]$Path)
    dynamicparam {
        if ($Path -match "*HKLM*:") {
            $dynParam1 = New-Object System.Management.Automation.RuntimeDefinedParameter("dp1", [int32], $attributeCollection)

            $attributes = New-Object System.Management.Automation.ParameterAttribute
            $attributes.ParameterSetName = 'pset1'
            $attributes.Mandatory = $false

            $attributeCollection = New-Object -Type System.Collections.ObjectModel.Collection``1[System.Attribute]
            $attributeCollection.Add($attributes)

            $paramDictionary = New-Object System.Management.Automation.RuntimeDefinedParameterDictionary
            $paramDictionary.Add("dp1", $dynParam1)
            return $paramDictionary
        }
    }
}

Het type dat wordt gebruikt om een object te maken dat een dynamische parameter vertegenwoordigt, is System.Management.Automation.RuntimeDefinedParameter.

Het type dat wordt gebruikt om een object te maken dat de kenmerken van de parameter vertegenwoordigt, is System.Management.Automation.ParameterAttribute.

De door de implementatie gedefinieerde kenmerken van de parameter omvatten Verplichte, Positieen ValueFromPipeline.

8.10.9 paramblok

Een paramblok biedt een alternatieve manier om parameters te declareren. De volgende sets parameterdeclaraties zijn bijvoorbeeld gelijkwaardig:

function FindStr1 ([string]$Str, [int]$StartPos = 0) { ... }
function FindStr2 {
    param ([string]$Str, [int]$StartPos = 0) ...
}

Met een paramblok kunt u een kenmerklijst op het paramblok plaatsen, maar een functieparameterdeclaratie laat dat niet toe.

Een script heeft mogelijk een paramblok, maar geen functieparameterdeclaratie. Een functie- of filterdefinitie kan een functieparameterdeclaratie hebben of een paramblok-, maar niet beide.

Bekijk het volgende voorbeeld:

param ( [Parameter(Mandatory = $true, ValueFromPipeline=$true)]
        [string[]] $ComputerName )

De ene parameter, $ComputerName, heeft het type string[], deze is vereist en neemt invoer uit de pijplijn.

Zie §12.3.7 voor een bespreking van het kenmerk Parameter en voor meer voorbeelden.

8.11 De parallelle statement

Syntaxis:

parallel-statement:
    *parallel* statement-block

De parallelle instructie bevat nul of meer instructies die op een manier die door de implementatie is gedefinieerd worden uitgevoerd.

Een parallelle instructie is alleen toegestaan in een werkstroom (§8.10.2).

8.12 De reeksinstructie

Syntaxis:

sequence-statement:
    *sequence* statement-block

De reeksinstructie bevat nul of meer instructies die op een door de implementatie gedefinieerde manier worden geëxecuteerd.

Een sequentie-instructie is alleen toegestaan in een werkstroom (§8.10.2).

8.13 De inlinescript-instructie

Syntaxis:

inlinescript-statement:
    inlinescript statement-block

De inlinescript-instructie bevat nul of meer instructies die op een door de implementatie bepaalde manier worden uitgevoerd.

Een inlinescript-instructie is alleen toegestaan in een werkstroom (§8.10.2).

8.14 Parameterbinding

Wanneer een script, functie, filter of cmdlet wordt aangeroepen, kan elk argument worden gebonden aan de bijbehorende parameter op positie, waarbij de eerste parameter positie nul heeft.

Bekijk het volgende definitiefragment voor een functie met de naam Get-Poweren de aanroepen ernaar:

function Get-Power ([long]$Base, [int]$Exponent) { ... }

Get-Power 5 3       # argument 5 is bound to parameter $Base in position 0
                    # argument 3 is bound to parameter $Exponent in position 1
                    # no conversion is needed, and the result is 5 to the power 3

Get-Power 4.7 3.2   # double argument 4.7 is rounded to int 5, double argument
                    # 3.2 is rounded to int 3, and result is 5 to the power 3

Get-Power 5         # $Exponent has value $null, which is converted to int 0

Get-Power           # both parameters have value $null, which is converted to int 0

Wanneer een script, functie, filter of cmdlet wordt aangeroepen, kan een argument worden gebonden aan de bijbehorende parameter op naam. Dit wordt gedaan met behulp van een parameter met argument, een argument dat de naam van de parameter is met een voorloopstreepje (-), gevolgd door de bijbehorende waarde voor dat argument. De gebruikte parameternaam kan elke hoofdletterongevoelige spelling hebben en kan elk voorvoegsel gebruiken dat op unieke wijze de bijbehorende parameter aanwijst. Vermijd bij het kiezen van parameternamen de namen van de algemene parameters.

Bekijk de volgende aanroepen voor functie Get-Power:

Get-Power -Base 5 -Exponent 3   # -Base designates $Base, so 5 is
                                # bound to that, -Exponent designates
                                # $Exponent, so 3 is bound to that

Get-Power -Exp 3 -Bas 5         # $Base takes on 5 and $Exponent takes on 3

Get-Power -E 3 -B 5             # $Base takes on 5 and $Exponent takes on 3

Aanroepen naar de volgende functie daarentegen

function Get-Hypot ([double]$Side1, [double]$Side2) {
    return [Math]::Sqrt($Side1 * $Side1 + $Side2 * $Side2)
}

moet parameters -Side1 en -Side2gebruiken, omdat er geen voorvoegsel is dat de parameter uniek aanwijst.

Dezelfde parameternaam kan niet meerdere keren worden gebruikt met of zonder andere gekoppelde argumentwaarden.

Parameters kunnen kenmerken hebben (§12). Zie de secties in §12.3voor informatie over de afzonderlijke kenmerken. Zie §12.3.7 voor meer informatie over parametersets.

Een script, functie, filter of cmdlet kan argumenten ontvangen via de opdrachtregel voor aanroepen, van de pijplijn of van beide. Hier volgen de stappen voor het oplossen van parameterbinding:

  1. Bind eerst alle benoemde parameters en ga dan verder
  2. Eerst positionele parameters binden, dan
  3. Binden van de pijplijn door waarde (§12.3.7) met een exacte match,
  4. Waarde via de pijplijn binden (§12.3.7) met conversie
  5. Binden van de pijplijn op naam (§12.3.7) met exacte overeenkomst, vervolgens
  6. Binden door naam vanaf de pijplijn (§12.3.7) met conversie

Verschillende van deze stappen omvatten conversie, zoals beschreven in §6. De set conversies die in binding worden gebruikt, is echter niet precies hetzelfde als die in taalconversies. In het bijzonder

  • Hoewel de waarde $null kan worden gegoten naar bool, kan $null niet worden gebonden aan bool.
  • Wanneer de waarde $null wordt doorgegeven aan een switchparameter voor een cmdlet, wordt deze behandeld alsof $true is doorgegeven. Wanneer de parameter wordt doorgegeven aan een switchparameter voor een functie, wordt deze echter behandeld alsof $false is doorgegeven.
  • Parameters van het type bool of schakeloptie kunnen alleen worden gebonden aan numerieke of boolargumenten.
  • Als het parametertype geen verzameling is, maar het argument een soort verzameling is, wordt er geen conversie uitgevoerd, tenzij het parametertype object of PsObject is. (Het belangrijkste punt van deze beperking is om het converteren van een verzameling naar een tekenreeksparameter niet toe te laten.) Anders worden de gebruikelijke conversies geprobeerd.

Als het parametertype IList of ICollection<T>is, worden alleen de conversies via constructor, op_Implicit en op_Explicit geprobeerd. Als er geen dergelijke conversies bestaan, wordt een speciale conversie gebruikt voor parameters van het type verzameling, waaronder IList, ICollection<T>en matrices.

Positionele parameters worden liever gebonden zonder typeconversie, indien mogelijk. Bijvoorbeeld

function Test {
    [CmdletBinding(DefaultParameterSetName = "SetB")]
    param([Parameter(Position = 0, ParameterSetName = "SetA")]
        [decimal]$Dec,
        [Parameter(Position = 0, ParameterSetName = "SetB")]
        [int]$In
    )
    $PSCmdlet.ParameterSetName
}

Test 42d   # outputs "SetA"
Test 42    # outputs "SetB"
  • Last updated on