about_Parameter_Sets
Краткое описание
Описание определения и использования наборов параметров в расширенных функциях.
Подробное описание
PowerShell использует наборы параметров для записи одной функции, которая может выполнять различные действия для разных сценариев. Наборы параметров позволяют предоставлять пользователям различные параметры. Чтобы вернуть разные сведения на основе параметров, указанных пользователем. Одновременно можно использовать только один набор параметров.
Требования к набору параметров
Следующие требования применяются ко всем наборам параметров.
Если для параметра не задан ни один набор параметров, этот параметр входит во все наборы параметров.
Каждый набор параметров должен иметь уникальное сочетание параметров. Если это возможно, хотя бы один из уникальных параметров должен быть обязательным параметром.
Набор параметров, содержащий несколько позиционных параметров, должен определять уникальные позиции для каждого параметра. Никакие два позиционных параметра не могут указывать одну и ту же позицию.
Только один параметр в наборе может объявлять
ValueFromPipelineключевое слово со значениемtrue. Несколько параметров могут определятьValueFromPipelineByPropertyNameключевое слово со значениемtrue.
Примечание.
Существует ограничение в 32 набора параметров.
Наборы параметров по умолчанию
При определении DefaultParameterSetName нескольких наборов параметров ключевое слово атрибута CmdletBinding указывает набор параметров по умолчанию.
PowerShell использует набор параметров по умолчанию, если он не может определить набор параметров, используемый на основе сведений, предоставленных команде. Дополнительные сведения об атрибуте КомандлетBinding см . в about_Functions_CmdletBindingAttribute.
Объявление наборов параметров
Чтобы создать набор параметров, необходимо указать ParameterSetName ключевое слово атрибута Параметра для каждого параметра в наборе параметров. Для параметров, принадлежащих нескольким наборам параметров, добавьте атрибут параметра для каждого набора параметров.
Атрибут параметра позволяет определять параметр по-разному для каждого набора параметров. Например, можно определить параметр как обязательный в одном наборе и необязательном в другом. Однако каждый набор параметров должен содержать по крайней мере один уникальный параметр.
Параметры, у которых нет имени набора параметров, относятся ко всем наборам параметров.
Примеры
В следующем примере функция подсчитывает числовые строки, символы и слова в текстовом файле. С помощью параметров можно указать, какие значения вы хотите вернуть и какие файлы необходимо измерять. Существует четыре набора параметров, определенных:
- Путь
- 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
}
}
}
Каждый набор параметров должен иметь уникальный параметр или уникальное сочетание параметров. Наборы Path параметров очень похожи, но параметр All является уникальным для PathAll набора PathAll параметров. То же самое имеет значение true с наборами LiteralPath параметров и LiteralPathAll наборами параметров. Несмотря на то, что PathAllLiteralPathAll оба набора параметров имеют параметр All , параметры Path и LiteralPath различают их.
Используйте Get-Command -Syntax синтаксис каждого набора параметров. Однако не отображается имя набора параметров. В следующем примере показано, какие параметры можно использовать в каждом наборе параметров.
(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>]
Наборы параметров в действии
В примере используется 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
Ошибка с использованием параметров из нескольких наборов
В этом примере используются уникальные параметры из разных наборов параметров.
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.
Параметры Path и LiteralPath уникальны для различных наборов параметров командлета Get-ChildItem . При выполнении параметров в одном командлете возникает ошибка. Одновременно можно использовать только один набор параметров для каждого вызова командлета.
Как узнать, какой набор параметров используется
Автоматическая переменная $PSCmdlet предоставляет свойство ParameterSetName .
Это свойство содержит имя используемого набора параметров. Это свойство можно использовать в функции, чтобы определить, какой набор параметров используется для выбора поведения набора параметров.
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
PowerShell
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по