about_Parameter_Sets

Articolo
04/01/2024

Descrizione breve

Viene descritto come definire e usare i set di parametri nelle funzioni avanzate.

Descrizione lunga

PowerShell usa set di parametri per consentire di scrivere una singola funzione in grado di eseguire azioni diverse per scenari diversi. I set di parametri consentono di esporre parametri diversi all'utente. Per restituire informazioni diverse in base ai parametri specificati dall'utente. È possibile usare un solo parametro impostato alla volta.

Requisiti del set di parametri

I requisiti seguenti si applicano a tutti i set di parametri.

Se non viene specificato alcun set di parametri per un parametro, il parametro appartiene a tutti i set di parametri.
Ogni set di parametri deve avere una combinazione univoca di parametri. Se possibile, almeno uno dei parametri univoci deve essere un parametro obbligatorio.
Un set di parametri che contiene più parametri posizionali deve definire posizioni univoche per ogni parametro. Nessun parametro posizionale può specificare la stessa posizione.
Un solo parametro in un set può dichiarare la ValueFromPipeline parola chiave con un valore .true Più parametri possono definire la ValueFromPipelineByPropertyName parola chiave con un valore .true

Nota

È previsto un limite di 32 set di parametri.

Set di parametri predefiniti

Quando vengono definiti più set di parametri, la DefaultParameterSetName parola chiave dell'attributo CmdletBinding specifica il set di parametri predefinito. PowerShell usa il set di parametri predefinito quando non è in grado di determinare il set di parametri da usare in base alle informazioni fornite al comando. Per altre informazioni sull'attributo CmdletBinding , vedere about_Functions_CmdletBindingAttribute.

Dichiarazione di set di parametri

Per creare un set di parametri, è necessario specificare la ParameterSetName parola chiave dell'attributo Parameter per ogni parametro nel set di parametri. Per i parametri che appartengono a più set di parametri, aggiungere un attributo Parameter per ogni set di parametri.

L'attributo Parameter consente di definire il parametro in modo diverso per ogni set di parametri. Ad esempio, è possibile definire un parametro come obbligatorio in un set e facoltativo in un altro. Tuttavia, ogni set di parametri deve contenere almeno un parametro univoco.

I parametri che non hanno un nome del set di parametri assegnato appartengono a tutti i set di parametri.

Esempi

La funzione di esempio seguente conta le righe, i caratteri e le parole numerici in un file di testo. Usando i parametri, è possibile specificare i valori da restituire e i file da misurare. Sono definiti quattro set di parametri:

Percorso
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
        }
    }
}

Ogni set di parametri deve avere un parametro univoco o una combinazione univoca di parametri. I set di Path parametri e PathAll sono molto simili, ma il parametro All è univoco per il PathAll set di parametri. Lo stesso vale con i set di LiteralPath parametri e LiteralPathAll . Anche se i set di PathAll parametri e LiteralPathAll hanno entrambi il parametro All , i parametri Path e LiteralPath li differenziano.

L'uso Get-Command -Syntax mostra la sintassi di ogni set di parametri. Tuttavia, non mostra il nome del set di parametri. L'esempio seguente mostra quali parametri possono essere usati in ogni set di parametri.

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

Set di parametri in azione

Nell'esempio viene usato il PathAll set di parametri.

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

Errore durante l'uso di parametri da più set

In questo esempio vengono usati parametri univoci di set di parametri diversi.

Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME

Get-ChildItem : Parameter set can't be resolved using the specified named parameters.
At line:1 char:1
+ Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Get-ChildItem], ParameterBindingException
    + FullyQualifiedErrorId : AmbiguousParameterSet,Microsoft.PowerShell.Commands.GetChildItemCommand

I parametri Path e LiteralPath sono univoci per diversi set di parametri del Get-ChildItem cmdlet. Quando i parametri vengono eseguiti insieme nello stesso cmdlet, viene generato un errore. È possibile usare un solo set di parametri per ogni chiamata al cmdlet alla volta.

Come sapere quale set di parametri viene usato

La variabile $PSCmdlet automatica fornisce la proprietà ParameterSetName . Questa proprietà contiene il nome del set di parametri utilizzato. È possibile usare questa proprietà nella funzione per determinare quale set di parametri viene usato per selezionare il comportamento specifico del set di parametri.

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

Condividi tramite