about_Parameter_Sets
Korte beschrijving
Hierin wordt beschreven hoe u parametersets in geavanceerde functies definieert en gebruikt.
Lange beschrijving
PowerShell maakt gebruik van parametersets waarmee u één functie kunt schrijven die verschillende acties voor verschillende scenario's kan uitvoeren. Met parametersets kunt u verschillende parameters beschikbaar maken voor de gebruiker. En om verschillende informatie te retourneren op basis van de parameters die door de gebruiker zijn opgegeven. U kunt slechts één parameterset tegelijk gebruiken.
Vereisten voor parameterset
De volgende vereisten zijn van toepassing op alle parametersets.
Als er geen parameterset is opgegeven voor een parameter, behoort de parameter tot alle parametersets.
Elke parameterset moet een unieke combinatie van parameters hebben. Indien mogelijk moet ten minste één van de unieke parameters een verplichte parameter zijn.
Een parameterset die meerdere positionele parameters bevat, moet unieke posities definiëren voor elke parameter. Er kunnen geen twee positionele parameters dezelfde positie opgeven.
Slechts één parameter in een set kan het
ValueFromPipelinetrefwoord declareren met een waarde vantrue. Meerdere parameters kunnen hetValueFromPipelineByPropertyNametrefwoord definiëren met een waarde vantrue.
Notitie
Er is een limiet van 32 parametersets.
Standaardparametersets
Wanneer er meerdere parametersets zijn gedefinieerd, geeft het DefaultParameterSetName trefwoord van het kenmerk CmdletBinding de standaardparameterset op.
PowerShell maakt gebruik van de standaardparameterset wanneer de parameterset die moet worden gebruikt niet kan worden bepaald op basis van de informatie die aan de opdracht is verstrekt. Zie about_Functions_CmdletBindingAttribute voor meer informatie over het kenmerk CmdletBinding.
Parametersets declareren
Als u een parameterset wilt maken, moet u het ParameterSetName trefwoord van het parameterkenmerk opgeven voor elke parameter in de parameterset. Voor parameters die deel uitmaken van meerdere parametersets, voegt u een parameterkenmerk toe voor elke parameterset.
Met het kenmerk Parameter kunt u de parameter anders definiëren voor elke parameterset. U kunt bijvoorbeeld een parameter definiëren als verplicht in de ene set en optioneel in een andere. Elke parameterset moet echter ten minste één unieke parameter bevatten.
Parameters die geen toegewezen parametersetnaam hebben, behoren tot alle parametersets.
Voorbeelden
Met de volgende voorbeeldfunctie worden de numerieke regels, tekens en woorden in een tekstbestand geteld. Met behulp van parameters kunt u opgeven welke waarden u wilt retourneren en welke bestanden u wilt meten. Er zijn vier parametersets gedefinieerd:
- Pad
- 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
}
}
}
Elke parameterset moet een unieke parameter of een unieke combinatie van parameters hebben. De Path en PathAll parametersets zijn vergelijkbaar, maar de parameter All is uniek voor de PathAll parameterset. Hetzelfde geldt voor de LiteralPath en LiteralPathAll parametersets. Hoewel de parametersets LiteralPathAll en parametersets PathAll beide de parameter All hebben, onderscheiden de parameters Path en LiteralPath deze.
Gebruik Get-Command -Syntax toont de syntaxis van elke parameterset. De naam van de parameterset wordt echter niet weergegeven. In het volgende voorbeeld ziet u welke parameters in elke parameterset kunnen worden gebruikt.
(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>]
Parametersets in actie
In het voorbeeld wordt de PathAll parameterset gebruikt.
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
Fout bij het gebruik van parameters uit meerdere sets
In dit voorbeeld worden unieke parameters uit verschillende parametersets gebruikt.
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.
De parameters Path en LiteralPath zijn uniek voor verschillende parametersets van de Get-ChildItem cmdlet. Wanneer de parameters samen worden uitgevoerd in dezelfde cmdlet, wordt er een fout gegenereerd. Er kan slechts één parameterset tegelijk worden gebruikt per cmdlet-aanroep.
Hoe u weet welke parameterset wordt gebruikt
De automatische variabele $PSCmdlet biedt de eigenschap ParameterSetName .
Deze eigenschap bevat de naam van de parameterset die wordt gebruikt. U kunt deze eigenschap in uw functie gebruiken om te bepalen welke parameterset wordt gebruikt om het specifieke gedrag van parameterset te selecteren.
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
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor