about_Parameter_Sets

Краткое описание

Описание определения и использования наборов параметров в расширенных функциях.

Длинное описание

PowerShell использует наборы параметров для записи одной функции, которая может выполнять различные действия для разных сценариев. Наборы параметров позволяют предоставлять пользователям различные параметры. Чтобы вернуть разные сведения на основе параметров, указанных пользователем. Одновременно можно использовать только один набор параметров.

Требования к набору параметров

Следующие требования применяются ко всем наборам параметров.

Если для параметра не указан набор параметров, параметр принадлежит всем наборам параметров.
Каждый набор параметров должен иметь уникальное сочетание параметров. Если это возможно, хотя бы один из уникальных параметров должен быть обязательным параметром.
Набор параметров, содержащий несколько позиционных параметров, должен определять уникальные позиции для каждого параметра. Нет двух позиционных параметров, которые могут указывать одну и ту же позицию.

Заметка

Существует ограничение в 32 набора параметров.

Наборы параметров по умолчанию

При определении нескольких наборов параметров ключевое слово DefaultParameterSetName атрибута КомандлетBinding указывает набор параметров по умолчанию. PowerShell использует набор параметров по умолчанию, если он не может определить набор параметров, используемый на основе сведений, предоставленных команде. Дополнительные сведения о атрибуте командлета командлетов см. в about_Functions_CmdletBindingAttribute.

Объявление наборов параметров

Чтобы создать набор параметров, необходимо указать ключевое слово ParameterSetName атрибута параметра для каждого параметра в наборе параметров. Для параметров, принадлежащих нескольким наборам параметров, добавьте атрибут параметра для каждого набора параметров.

Атрибут параметра позволяет определять параметр по-разному для каждого набора параметров. Например, можно определить параметр как обязательный в одном наборе и необязательном в другом. Однако каждый набор параметров должен содержать по крайней мере один уникальный параметр.

Параметры, у которых нет имени набора параметров, относятся ко всем наборам параметров.

Имя зарезервированного набора параметров

PowerShell резервирует имя __AllParameterSets набора параметров для специальной обработки.

__AllParameterSets — это имя набора параметров по умолчанию, если явное имя по умолчанию не используется.

ParameterSetName Задание атрибута __AllParameterSets эквивалентно назначению атрибута ParameterSetName. В обоих случаях параметр принадлежит всем наборам параметров.

Заметка

Атрибут КомандлетBinding не препятствует настройке DefaultParameterSetName значения __AllParameterSets. Если это сделать, PowerShell создает явный набор параметров, на который не удается правильно ссылаться атрибутом "Параметр ".

Примеры

В следующем примере функция подсчитывает числовые строки, символы и слова в текстовом файле. С помощью параметров можно указать значения, которые вы хотите вернуть, и файлы, которые нужно измерить. Существует четыре набора параметров, определенных:

Путь
PathAll
ЛитералPath
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 и PathAll очень похожи, но параметр All является уникальным для набора параметров PathAll. То же самое верно с наборами параметров LiteralPath и LiteralPathAll. Несмотря на то, что наборы параметров PathAll и LiteralPathAll имеют параметр 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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-09-29