about_Parameter_Sets
Krótki opis
Opisuje sposób definiowania i używania zestawów parametrów w funkcjach zaawansowanych.
Długi opis
Program PowerShell używa zestawów parametrów, aby umożliwić pisanie pojedynczej funkcji, która może wykonywać różne akcje w różnych scenariuszach. Zestawy parametrów umożliwiają uwidocznienie różnych parametrów użytkownikowi. Aby zwrócić różne informacje na podstawie parametrów określonych przez użytkownika. Jednocześnie można użyć tylko jednego zestawu parametrów.
Wymagania dotyczące zestawu parametrów
Następujące wymagania dotyczą wszystkich zestawów parametrów.
Jeśli dla parametru nie określono żadnego zestawu parametrów, parametr należy do wszystkich zestawów parametrów.
Każdy zestaw parametrów musi mieć unikatową kombinację parametrów. Jeśli to możliwe, co najmniej jeden z unikatowych parametrów powinien być obowiązkowym parametrem.
Zestaw parametrów zawierający wiele parametrów pozycyjnych musi definiować unikatowe pozycje dla każdego parametru. Żadne dwa parametry pozycyjne nie mogą określać tej samej pozycji.
Tylko jeden parametr w zestawie może zadeklarować
ValueFromPipelinesłowo kluczowe o wartościtrue. Wiele parametrów może definiowaćValueFromPipelineByPropertyNamesłowo kluczowe z wartościątrue.
Uwaga
Istnieje limit 32 zestawów parametrów.
Domyślne zestawy parametrów
Gdy zdefiniowano wiele zestawów parametrów, słowo DefaultParameterSetName kluczowe atrybutu CmdletBinding określa domyślny zestaw parametrów.
Program PowerShell używa domyślnego zestawu parametrów, gdy nie może określić, który parametr ma być używany na podstawie informacji dostarczonych do polecenia. Aby uzyskać więcej informacji na temat atrybutu CmdletBinding, zobacz about_Functions_CmdletBindingAttribute.
Deklarowanie zestawów parametrów
Aby utworzyć zestaw parametrów, należy określić ParameterSetName słowo kluczowe atrybutu Parametr dla każdego parametru w zestawie parametrów. W przypadku parametrów należących do wielu zestawów parametrów dodaj atrybut Parametr dla każdego zestawu parametrów.
Atrybut Parametr umożliwia definiowanie parametru inaczej dla każdego zestawu parametrów. Można na przykład zdefiniować parametr jako obowiązkowy w jednym zestawie i opcjonalnie w innym. Jednak każdy zestaw parametrów musi zawierać co najmniej jeden unikatowy parametr.
Parametry, które nie mają przypisanej nazwy zestawu parametrów, należą do wszystkich zestawów parametrów.
Przykłady
Poniższa przykładowa funkcja zlicza wiersze liczbowe, znaki i wyrazy w pliku tekstowym. Za pomocą parametrów można określić, które wartości mają zostać zwrócone, oraz pliki, które chcesz zmierzyć. Zdefiniowano cztery zestawy parametrów:
- Ścieżka
- PathAll
- LiterałPath
- LiterałPathAll
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
}
}
}
Każdy zestaw parametrów musi mieć unikatowy parametr lub unikatową kombinację parametrów. Path Zestawy parametrów i PathAll są bardzo podobne, ale parametr All jest unikatowy dla zestawu parametrówPathAll. To samo dotyczy zestawów parametrów LiteralPath i LiteralPathAll . Mimo że PathAll zestawy parametrów i LiteralPathAll mają parametr All , parametry Path i LiteralPath je rozróżniają.
Użycie Get-Command -Syntax pokazuje składnię każdego zestawu parametrów. Nie wyświetla jednak nazwy zestawu parametrów. W poniższym przykładzie pokazano, które parametry mogą być używane w każdym zestawie parametrów.
(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>]
Zestawy parametrów w akcji
W przykładzie użyto zestawu parametrów 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
Błąd podczas używania parametrów z wielu zestawów
W tym przykładzie używane są unikatowe parametry z różnych zestawów parametrów.
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.
Parametry Path i LiteralPath są unikatowe dla różnych zestawów parametrów Get-ChildItem polecenia cmdlet. Gdy parametry są uruchamiane razem w tym samym poleceniu cmdlet, zgłaszany jest błąd. Jednocześnie można użyć tylko jednego zestawu parametrów na wywołanie polecenia cmdlet.
Jak dowiedzieć się, który zestaw parametrów jest używany
Zmienna $PSCmdlet automatyczna udostępnia właściwość ParameterSetName .
Ta właściwość zawiera nazwę używanego zestawu parametrów. Za pomocą tej właściwości w funkcji można określić, który zestaw parametrów jest używany do wybierania zachowania specyficznego dla zestawu parametrów.
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
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla