about_Parameter_Sets

Cikk
04/01/2024

Rövid leírás

Ismerteti, hogyan definiálhat és használhat paraméterkészleteket speciális függvényekben.

Hosszú leírás

A PowerShell paraméterkészletekkel teszi lehetővé, hogy egyetlen függvényt írjon, amely különböző műveleteket hajthat végre különböző forgatókönyvek esetén. A paraméterkészletekkel különböző paramétereket tehet elérhetővé a felhasználó számára. És a felhasználó által megadott paraméterek alapján adja vissza a különböző információkat. Egyszerre csak egy paraméterkészletet használhat.

Paraméterkészletre vonatkozó követelmények

Az alábbi követelmények az összes paraméterkészletre vonatkoznak.

Ha egy paraméterhez nincs megadva paraméterkészlet, a paraméter az összes paraméterkészlethez tartozik.
Minden paraméterkészletnek paraméterek egyedi kombinációjával kell rendelkeznie. Ha lehetséges, az egyedi paraméterek legalább egyikének kötelező paraméternek kell lennie.
Egy több pozícióparamétert tartalmazó paraméterkészletnek minden paraméterhez egyedi pozíciókat kell meghatároznia. Egyetlen két pozícióparaméter sem tudja ugyanazt a pozíciót megadni.
A halmazban csak egy paraméter deklarálhatja a ValueFromPipeline kulcsszót a következő trueértékkel: . Több paraméter is definiálhatja a ValueFromPipelineByPropertyName kulcsszót a következő trueértékkel: .

Feljegyzés

Legfeljebb 32 paraméterkészletet lehet megadni.

Alapértelmezett paraméterkészletek

Több paraméterkészlet definiálásakor a DefaultParameterSetNameCmdletBinding attribútum kulcsszója adja meg az alapértelmezett paraméterkészletet. A PowerShell akkor használja az alapértelmezett paraméterkészletet, ha a parancshoz megadott információk alapján nem tudja meghatározni a használni kívánt paraméterkészletet. A CmdletBinding attribútummal kapcsolatos további információkért lásd: about_Functions_CmdletBindingAttribute.

Paraméterkészletek deklarálása

Paraméterkészlet létrehozásához meg kell adnia a ParameterSetNameParaméter attribútum kulcsszóját a paraméterkészlet minden paraméteréhez. Több paraméterkészlethez tartozó paraméterek esetén adjon hozzá paraméterattribútumot minden paraméterkészlethez.

A Paraméter attribútum lehetővé teszi, hogy a paramétert az egyes paraméterkészletekhez eltérően definiálja. Megadhat például egy paramétert kötelezőként az egyik készletben, a másikban pedig választhatóként. Minden paraméterkészletnek azonban tartalmaznia kell legalább egy egyedi paramétert.

Azok a paraméterek, amelyekhez nincs hozzárendelt paraméterkészlet neve, az összes paraméterkészlethez tartoznak.

Példák

Az alábbi példafüggvény megszámolja a szövegfájlban lévő számsorokat, karaktereket és szavakat. Paraméterek használatával megadhatja, hogy mely értékeket szeretné visszaadni, és mely fájlokat szeretné mérni. Négy paraméterkészlet van definiálva:

Elérési út
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
        }
    }
}

Minden paraméterkészletnek egyedi paraméterrel vagy paraméterek egyedi kombinációjával kell rendelkeznie. A Path és PathAll a paraméterkészletek nagyon hasonlóak, de a Minden paraméter egyedi a PathAll paraméterkészlethez. Ugyanez igaz a LiteralPath paraméterkészletekre is LiteralPathAll . Annak ellenére, hogy a PathAllLiteralPathAll paraméterkészletek mind a Mind paramétert, mind a Path és a LiteralPath paraméter megkülönböztetik őket.

A Használat Get-Command -Syntax az egyes paraméterkészletek szintaxisát mutatja. Ez azonban nem jeleníti meg a paraméterkészlet nevét. Az alábbi példa bemutatja, hogy mely paraméterek használhatók az egyes paraméterkészletekben.

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

Paraméterkészletek működés közben

A példa a paraméterkészletet PathAll használja.

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

Hiba több készlet paramétereinek használatakor

Ebben a példában különböző paraméterkészletekből származó egyedi paramétereket használunk.

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.

A Path és a LiteralPath paraméterek egyediek a Get-ChildItem parancsmag különböző paraméterkészleteihez. Ha a paraméterek ugyanabban a parancsmagban futnak együtt, hibaüzenet jelenik meg. Parancsmag-hívásonként egyszerre csak egy paraméterkészlet használható.

Hogyan lehet tudni, hogy melyik paraméterkészletet használja a rendszer

Az automatikus változó $PSCmdlet a ParameterSetName tulajdonságot adja meg. Ez a tulajdonság a használt paraméterkészlet nevét tartalmazza. Ez a tulajdonság a függvényben annak meghatározására használható, hogy melyik paraméterkészletet használja a paraméterkészlet-specifikus viselkedés kiválasztásához.

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