Delen via

about_Parameter_Sets

  • Artikel

Korte beschrijving

Hierin wordt beschreven hoe u parametersets in geavanceerde functies definieert en gebruikt.

Lange beschrijving

PowerShell maakt gebruik van parametersets waarmee u één functie kunt schrijven die verschillende acties voor verschillende scenario's kan uitvoeren. Met parametersets kunt u verschillende parameters beschikbaar maken voor de gebruiker. En om verschillende informatie te retourneren op basis van de parameters die door de gebruiker zijn opgegeven. U kunt slechts één parameterset tegelijk gebruiken.

Vereisten voor parameterset

De volgende vereisten zijn van toepassing op alle parametersets.

  • Als er geen parameterset is opgegeven voor een parameter, behoort de parameter tot alle parametersets.

  • Elke parameterset moet een unieke combinatie van parameters hebben. Indien mogelijk moet ten minste één van de unieke parameters een verplichte parameter zijn.

  • Een parameterset die meerdere positionele parameters bevat, moet unieke posities definiëren voor elke parameter. Er kunnen geen twee positionele parameters dezelfde positie opgeven.

  • Slechts één parameter in een set kan het ValueFromPipeline trefwoord declareren met een waarde van true. Meerdere parameters kunnen het ValueFromPipelineByPropertyName trefwoord definiëren met een waarde van true.

Notitie

Er is een limiet van 32 parametersets.

Standaardparametersets

Wanneer er meerdere parametersets zijn gedefinieerd, geeft het DefaultParameterSetName trefwoord van het kenmerk CmdletBinding de standaardparameterset op. PowerShell maakt gebruik van de standaardparameterset wanneer de parameterset die moet worden gebruikt niet kan worden bepaald op basis van de informatie die aan de opdracht is verstrekt. Zie about_Functions_CmdletBindingAttribute voor meer informatie over het kenmerk CmdletBinding.

Parametersets declareren

Als u een parameterset wilt maken, moet u het ParameterSetName trefwoord van het parameterkenmerk opgeven voor elke parameter in de parameterset. Voor parameters die deel uitmaken van meerdere parametersets, voegt u een parameterkenmerk toe voor elke parameterset.

Met het kenmerk Parameter kunt u de parameter anders definiëren voor elke parameterset. U kunt bijvoorbeeld een parameter definiëren als verplicht in de ene set en optioneel in een andere. Elke parameterset moet echter ten minste één unieke parameter bevatten.

Parameters die geen toegewezen parametersetnaam hebben, behoren tot alle parametersets.

Voorbeelden

Met de volgende voorbeeldfunctie worden de numerieke regels, tekens en woorden in een tekstbestand geteld. Met behulp van parameters kunt u opgeven welke waarden u wilt retourneren en welke bestanden u wilt meten. Er zijn vier parametersets gedefinieerd:

  • Pad
  • PathAll
  • LiteralPath
  • LiteralPathAll
function Measure-Lines {
    [CmdletBinding(DefaultParameterSetName = 'Path')]
    param (
        [Parameter(Mandatory, ParameterSetName = 'Path', Position = 0)]
        [Parameter(Mandatory, ParameterSetName = 'PathAll', Position = 0)]
        [string[]]$Path,

        [Parameter(Mandatory, ParameterSetName = 'LiteralPathAll', ValueFromPipeline)]
        [Parameter(Mandatory, ParameterSetName = 'LiteralPath', ValueFromPipeline)]
        [string[]]$LiteralPath,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Lines,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Words,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'LiteralPath')]
        [switch]$Characters,

        [Parameter(Mandatory, ParameterSetName = 'PathAll')]
        [Parameter(Mandatory, ParameterSetName = 'LiteralPathAll')]
        [switch]$All,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'PathAll')]
        [switch]$Recurse
    )

    begin {
        if ($All) {
            $Lines = $Words = $Characters = $true
        }
        elseif (($Words -eq $false) -and ($Characters -eq $false)) {
            $Lines  = $true
        }
    }
    process {
        if ($Path) {
            $Files = Get-ChildItem -Path $Path -Recurse:$Recurse -File
        }
        else {
            $Files = Get-ChildItem -LiteralPath $LiteralPath -File
        }
        foreach ($file in $Files) {
            $result = [ordered]@{ }
            $result.Add('File', $file.fullname)

            $content = Get-Content -LiteralPath $file.fullname

            if ($Lines) { $result.Add('Lines', $content.Length) }

            if ($Words) {
                $wc = 0
                foreach ($line in $content) { $wc += $line.split(' ').Length }
                $result.Add('Words', $wc)
            }

            if ($Characters) {
                $cc = 0
                foreach ($line in $content) { $cc += $line.Length }
                $result.Add('Characters', $cc)
            }

            New-Object -TypeName psobject -Property $result
        }
    }
}

Elke parameterset moet een unieke parameter of een unieke combinatie van parameters hebben. De Path en PathAll parametersets zijn vergelijkbaar, maar de parameter All is uniek voor de PathAll parameterset. Hetzelfde geldt voor de LiteralPath en LiteralPathAll parametersets. Hoewel de parametersets LiteralPathAll en parametersets PathAll beide de parameter All hebben, onderscheiden de parameters Path en LiteralPath deze.

Gebruik Get-Command -Syntax toont de syntaxis van elke parameterset. De naam van de parameterset wordt echter niet weergegeven. In het volgende voorbeeld ziet u welke parameters in elke parameterset kunnen worden gebruikt.

(Get-Command Measure-Lines).ParameterSets |
  Select-Object -Property @{n='ParameterSetName';e={$_.name}},
    @{n='Parameters';e={$_.ToString()}}

ParameterSetName Parameters
---------------- ----------
Path             [-Path] <string[]> [-Lines] [-Words] [-Characters] [-Recurse] [<CommonParameters>]
PathAll          [-Path] <string[]> -All [-Recurse] [<CommonParameters>]
LiteralPath      -LiteralPath <string[]> [-Lines] [-Words] [-Characters] [<CommonParameters>]
LiteralPathAll   -LiteralPath <string[]> -All [<CommonParameters>]

Parametersets in actie

In het voorbeeld wordt de PathAll parameterset gebruikt.

Measure-Lines test* -All

File                       Lines Words Characters
----                       ----- ----- ----------
C:\temp\test\test.help.txt    31   562       2059
C:\temp\test\test.md          30  1527       3224
C:\temp\test\test.ps1          3     3         79
C:\temp\test\test[1].txt      31   562       2059

Fout bij het gebruik van parameters uit meerdere sets

In dit voorbeeld worden unieke parameters uit verschillende parametersets gebruikt.

Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME

Get-ChildItem: Parameter set cannot be resolved using the specified named
parameters. One or more parameters issued cannot be used together or an
insufficient number of parameters were provided.

De parameters Path en LiteralPath zijn uniek voor verschillende parametersets van de Get-ChildItem cmdlet. Wanneer de parameters samen worden uitgevoerd in dezelfde cmdlet, wordt er een fout gegenereerd. Er kan slechts één parameterset tegelijk worden gebruikt per cmdlet-aanroep.

Hoe u weet welke parameterset wordt gebruikt

De automatische variabele $PSCmdlet biedt de eigenschap ParameterSetName . Deze eigenschap bevat de naam van de parameterset die wordt gebruikt. U kunt deze eigenschap in uw functie gebruiken om te bepalen welke parameterset wordt gebruikt om het specifieke gedrag van parameterset te selecteren.

function Get-ParameterSetName {

    [CmdletBinding(DefaultParameterSetName = 'Set1')]
    param (
        [Parameter(ParameterSetName = 'Set1', Position = 0)]
        $Var1,

        [Parameter(ParameterSetName = 'Set2', Position = 0)]
        $Var2,

        [Parameter(ParameterSetName = 'Set1', Position = 1)]
        [Parameter(ParameterSetName = 'Set2', Position = 1)]
        $Var3,

        [Parameter(Position = 2)]
        $Var4
    )

    "Using Parameter set named '$($PSCmdlet.ParameterSetName)'"

    switch ($PSCmdlet.ParameterSetName) {
        'Set1' {
            "`$Var1 = $Var1"
            "`$Var3 = $Var3"
            "`$Var4 = $Var4"
            break
        }
        'Set2' {
            "`$Var2 = $Var2"
            "`$Var3 = $Var3"
            "`$Var4 = $Var4"
            break
        }
    }
}

PS> Get-ParameterSetName 1 2 3

Using Parameter set named 'Set1'
$Var1 = 1
$Var3 = 2
$Var4 = 3

PS> Get-ParameterSetName -Var2 1 2 3

Using Parameter set named 'Set2'
$Var2 = 1
$Var3 = 2
$Var4 = 3