about_Parameter_Sets

Kort beskrivning

Beskriver hur du definierar och använder parameteruppsättningar i avancerade funktioner.

Lång beskrivning

PowerShell använder parameteruppsättningar så att du kan skriva en enda funktion som kan utföra olika åtgärder för olika scenarier. Med parameteruppsättningar kan du exponera olika parametrar för användaren. Och för att returnera annan information baserat på de parametrar som angetts av användaren. Du kan bara använda en parameteruppsättning i taget.

Krav för parameteruppsättning

Följande krav gäller för alla parameteruppsättningar.

• Om ingen parameteruppsättning har angetts för en parameter tillhör parametern alla parameteruppsättningar.

• Varje parameteruppsättning måste ha en unik kombination av parametrar. Om möjligt bör minst en av de unika parametrarna vara en obligatorisk parameter.

• En parameteruppsättning som innehåller flera positionsparametrar måste definiera unika positioner för varje parameter. Inga två positionsparametrar kan ange samma position.

Standardparameteruppsättningar

När flera parameteruppsättningar definieras anger nyckelordet DefaultParameterSetName för attributet CmdletBinding standardparameteruppsättningen. PowerShell använder standardparameteruppsättningen när den inte kan fastställa vilken parameteruppsättning som ska användas baserat på den information som tillhandahålls till kommandot. Mer information om attributet CmdletBinding finns i about_Functions_CmdletBindingAttribute.

Deklarera parameteruppsättningar

Om du vill skapa en parameteruppsättning måste du ange nyckelordet ParameterSetName för parameterattributet för varje parameter i parameteruppsättningen. För parametrar som tillhör flera parameteruppsättningar lägger du till ett parameterattribut för varje parameteruppsättning.

Med parameterattributet kan du definiera parametern på olika sätt för varje parameteruppsättning. Du kan till exempel definiera en parameter som obligatorisk i en uppsättning och valfri i en annan. Varje parameteruppsättning måste dock innehålla minst en unik parameter.

Parametrar som inte har ett tilldelat parameteruppsättningsnamn tillhör alla parameteruppsättningar.

Namn på reserverad parameteruppsättning

PowerShell reserverar parameteruppsättningens namn __AllParameterSets för särskild hantering.

__AllParameterSets är namnet på standardparameteruppsättningen när ett explicit standardnamn inte används.

ParameterSetName Att ange parameterattributet till __AllParameterSets motsvarar att inte tilldela en ParameterSetName. I båda fallen tillhör parametern alla parameteruppsättningar.

Examples

I följande exempelfunktion räknas talrader, tecken och ord i en textfil. Med hjälp av parametrar kan du ange de värden som du vill returnera och de filer som du vill mäta. Det finns fyra definierade parameteruppsättningar:

• Sökväg
• 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
        }
    }
}

Varje parameteruppsättning måste ha en unik parameter eller en unik kombination av parametrar. Parameteruppsättningarna Path och PathAll är mycket lika, men parametern Alla är unik för parameteruppsättningen PathAll . Detsamma gäller för parameteruppsättningarna LiteralPath och LiteralPathAll . Även om parameteruppsättningarna PathAll och LiteralPathAll båda har parametern Alla skiljer parametrarna Path och LiteralPath åt dem.

Använd Get-Command -Syntax visar syntaxen för varje parameteruppsättning. Den visar dock inte namnet på parameteruppsättningen. I följande exempel visas vilka parametrar som kan användas i varje parameteruppsättning.

(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>]

Parameteruppsättningar i praktiken

I exemplet används parameteruppsättningen PathAll .

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

Fel vid användning av parametrar från flera uppsättningar

I det här exemplet används unika parametrar från olika parameteruppsättningar.

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.

Parametrarna Path och LiteralPath är unika för olika parameteruppsättningar i cmdleten.Get-ChildItem När parametrarna körs tillsammans i samma cmdlet utlöses ett fel. Endast en parameteruppsättning kan användas per cmdlet-anrop i taget.

Så här vet du vilken parameteruppsättning som används

Den automatiska variabeln $PSCmdlet innehåller egenskapen ParameterSetName . Den här egenskapen innehåller namnet på parameteruppsättningen som används. Du kan använda den här egenskapen i funktionen för att avgöra vilken parameteruppsättning som används för att välja parameteruppsättningsspecifikt beteende.

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