about_Parameter_Sets

Статья
03/27/2024

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

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

Подробное описание

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

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

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

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

Примечание.

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

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

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

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

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

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

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

Примеры

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

Путь
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 наборами параметров. Несмотря на то, что 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

Поделиться через