about_Parameter_Sets
Kurze Beschreibung
Beschreibt, wie Parametersätze in erweiterten Funktionen definiert und verwendet werden.
Lange Beschreibung
PowerShell verwendet Parametersätze, mit denen Sie eine einzelne Funktion schreiben können, die unterschiedliche Aktionen für verschiedene Szenarien ausführen kann. Parametersätze ermöglichen es Ihnen, dem Benutzer unterschiedliche Parameter verfügbar zu machen. Und um unterschiedliche Informationen basierend auf den vom Benutzer angegebenen Parametern zurückzugeben. Sie können jeweils nur einen Parameter verwenden.
Parametersatzanforderungen
Die folgenden Anforderungen gelten für alle Parametersätze.
Wenn für einen Parameter kein Parametersatz angegeben wird, gehört der Parameter zu allen Parametersätzen.
Jeder Parametersatz muss über eine eindeutige Kombination von Parametern verfügen. Wenn möglich, sollte mindestens einer der eindeutigen Parameter ein obligatorischer Parameter sein.
Ein Parametersatz, der mehrere positionelle Parameter enthält, muss eindeutige Positionen für jeden Parameter definieren. Es ist nicht möglich, dass zwei positionelle Parameter dieselbe Position angeben.
Nur ein Parameter in einem Satz kann die
ValueFromPipeline
Schlüsselwort (keyword) mit einem Wert vontrue
deklarieren. Mehrere Parameter können dieValueFromPipelineByPropertyName
Schlüsselwort (keyword) mit einem Wert vontrue
.
Hinweis
Es gibt einen Grenzwert von 32 Parametersätzen.
Standardparametersätze
Wenn mehrere Parametersätze definiert sind, gibt der DefaultParameterSetName
Schlüsselwort (keyword) des CmdletBinding-Attributs den Standardparametersatz an.
PowerShell verwendet den Standardparametersatz, wenn der Parameter, der basierend auf den informationen für den Befehl bereitgestellt wird, nicht bestimmt werden kann. Weitere Informationen zum CmdletBinding-Attribut finden Sie unter about_Functions_CmdletBindingAttribute.
Deklarieren von Parametersätzen
Um einen Parametersatz zu erstellen, müssen Sie den ParameterSetName
Schlüsselwort (keyword) des Parameter-Attributs für jeden Parameter im Parametersatz angeben. Fügen Sie für Parameter, die zu mehreren Parametersätzen gehören, ein Parameter-Attribut für jeden Parametersatz hinzu.
Mit dem Parameter-Attribut können Sie den Parameter für jeden Parametersatz anders definieren. Sie können z. B. einen Parameter als obligatorisch in einem Satz und optional in einem anderen definieren. Jeder Parametersatz muss jedoch mindestens einen eindeutigen Parameter enthalten.
Parameter, die keinen zugewiesenen Parametersatznamen haben, gehören zu allen Parametersätzen.
Beispiele
Die folgende Beispielfunktion zählt die Zahlenzeilen, Zeichen und Wörter in einer Textdatei. Mithilfe von Parametern können Sie angeben, welche Werte zurückgegeben werden sollen und welche Dateien Sie messen möchten. Es sind vier Parametersätze definiert:
- Pfad
- 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
}
}
}
Jeder Parametersatz muss über einen eindeutigen Parameter oder eine eindeutige Kombination von Parametern verfügen. Die Und PathAll
Parametersätze Path
sind sehr ähnlich, aber der Parametersatz "All" ist für den PathAll
Parametersatz eindeutig. Das gleiche gilt für die LiteralPath
Und-Parameter-Sätze LiteralPathAll
. Obwohl die PathAll
Parameter und LiteralPathAll
Parameter beide über den Parameter "All " verfügen, unterscheiden sich die Parameter "Path " und "LiteralPath ".
Hier Get-Command -Syntax
sehen Sie die Syntax der einzelnen Parametersätze. Der Name des Parametersatzes wird jedoch nicht angezeigt. Das folgende Beispiel zeigt, welche Parameter in jedem Parametersatz verwendet werden können.
(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>]
Parametersätze in Aktion
Im Beispiel wird der PathAll
Parametersatz verwendet.
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
Fehler beim Verwenden von Parametern aus mehreren Sätzen
In diesem Beispiel werden eindeutige Parameter aus verschiedenen Parametersätzen verwendet.
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
Die Parameter Path und LiteralPath sind für verschiedene Parametersätze des Get-ChildItem
Cmdlets eindeutig. Wenn die Parameter im selben Cmdlet zusammen ausgeführt werden, wird ein Fehler ausgelöst. Pro Cmdlet-Aufruf kann jeweils nur ein Parametersatz verwendet werden.
So wissen Sie, welcher Parametersatz verwendet wird
Die automatische Variable $PSCmdlet
stellt die ParameterSetName-Eigenschaft bereit.
Diese Eigenschaft enthält den Namen des verwendeten Parametersatzes. Sie können diese Eigenschaft in Ihrer Funktion verwenden, um zu bestimmen, welcher Parametersatz zum Auswählen von Parametersatz-spezifischem Verhalten verwendet wird.
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