about_Parameter_Sets
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
ValueFromPipelineparola chiave con un valore .truePiù parametri possono definire laValueFromPipelineByPropertyNameparola 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 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.
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
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per