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.
Endast en parameter i en uppsättning kan deklarera nyckelordet
ValueFromPipelinemed värdettrue. Flera parametrar kan definiera nyckelordetValueFromPipelineByPropertyNamemed värdettrue.
Kommentar
Det finns en gräns på 32 parameteruppsättningar.
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.
Exempel
I följande exempelfunktion räknas talrader, tecken och ord i en textfil. Med hjälp av parametrar kan du ange vilka värden du vill returnera och vilka filer 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 cmdletenGet-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
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för