about_Functions_Argument_Completion

  • Статья

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

Завершение аргумента — это функция PowerShell, которая предоставляет подсказки, включает обнаружение и ускоряет ввод входных значений аргументов.

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

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

Примечание.

Вкладка — это привязка ключа по умолчанию в Windows. Это связывание ключей можно изменить модулем PSReadLine или приложением, на котором размещена PowerShell. Привязка ключей отличается на платформах, отличных от Windows. Дополнительные сведения см. в about_PSReadLine.

Атрибут ValidateSet

Атрибут ValidateSet задает набор допустимых значений для параметра или переменной и включает завершение вкладки. PowerShell создает ошибку, если значение параметра или переменной не соответствует значению в наборе. В следующем примере значение параметра Fruit может быть только Apple, Banana или Pear.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet('Apple', 'Banana', 'Pear')]
    [string[]]
    $Fruit
)

В следующем примере значение переменной $flavor должно иметь значение "Шоколад", "Клубника" или "Ванилья". Атрибут ValidateSet можно использовать для любой переменной, а не только параметров.

[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'

Проверка происходит всякий раз, когда эта переменная назначается даже в скрипте.

Param(
    [ValidateSet('hello', 'world')]
    [string]$Message
)

$Message = 'bye'

В этом примере возвращается следующая ошибка во время выполнения:

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

Дополнительные сведения о расширении вкладок см. в about_Tab_Expansion.

Значения Dynamic ValidateSet с помощью классов

Класс можно использовать для динамического создания значений для ValidateSet во время выполнения. В следующем примере допустимые значения переменной $Sound создаются с помощью класса с именем SoundNames, который проверка три пути файловой системы для доступных звуковых файлов:

Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [string[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
                      '/Library/Sounds',
                      '~/Library/Sounds'
        $SoundNames = ForEach ($SoundPath in $SoundPaths) {
            If (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [string[]] $SoundNames
    }
}

Затем [SoundNames] класс реализуется как динамическое значение ValidateSet следующим образом:

Param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

Примечание.

Класс IValidateSetValuesGenerator появился в PowerShell 6.0.

Атрибут ArgumentCompletions

Атрибут ArgumentCompletions позволяет добавлять значения завершения вкладки в определенный параметр. Атрибут ArgumentCompletions должен быть определен для каждого параметра, которому требуется завершение вкладки. Атрибут ArgumentCompletions похож на ValidateSet. Оба атрибута принимают список значений, которые будут представлены, когда пользователь нажимает клавишу TAB после имени параметра. Однако, в отличие от ValidateSet, значения не проверяются и более похожи на предложения. Поэтому пользователь может указать любое значение, а не только значения в списке.

Атрибут ArgumentCompletions не следует путать с атрибутом ArgumentCompleter, который требует скриптблока для определения параметров. Доступны указанные значения

Синтаксис выглядит следующим образом:

function Test-ArgumentCompletions {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [ArgumentCompletions('Fruits', 'Vegetables')]
        $Type,

        [Parameter()]
        [ArgumentCompletions('Apple', 'Banana', 'Orange')]
        $Fruit,

        [Parameter()]
        [ArgumentCompletions('Onion', 'Carrot', 'Lettuce')]
        $Vegetable
    )
}

Каждый из параметров предоставляет список параметров атрибуту ArgumentCompletions для включения завершения вкладки.

Этот атрибут появился в PowerShell 6.0.

Атрибут ArgumentCompleter

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

Чтобы добавить атрибут ArgumentCompleter , необходимо определить блок скрипта, определяющий значения. Блок скрипта должен принимать следующие параметры в указанном ниже порядке. Имена параметров не имеют значения, так как значения предоставляются позиционально.

Синтаксис выглядит следующим образом:

function MyArgumentCompleter {
    Param(
        [Parameter(Mandatory)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )
            # Perform calculation of tab completed values here.
        } )]
        $ParamName
    )
}

Блок скрипта ArgumentCompleter

Параметры блока скрипта задаются следующими значениями:

  • $commandName (Позиция 0) — этот параметр имеет имя команды, для которой блок скрипта предоставляет завершение вкладки.
  • $parameterName (Позиция 1) — этот параметр имеет значение параметра, значение которого требует завершения вкладки.
  • $wordToComplete (Позиция 2) — этот параметр имеет значение, указанное пользователем перед нажатием tab. Блок скрипта должен использовать это значение для определения значений завершения вкладки.
  • $commandAst (Позиция 3) — этот параметр имеет значение "Дерево абстрактного синтаксиса" (AST) для текущей входной строки. Дополнительные сведения см. в документации по типу AST .
  • $fakeBoundParameters(Позиция 4) — этот параметр имеет хэш-таблицу, содержащую $PSBoundParameters командлет, прежде чем пользователь нажимал клавишу TAB. Дополнительные сведения см. в about_Automatic_Variables.

Блок скрипта ArgumentCompleter должен отменить значения с помощью конвейера, например ForEach-ObjectWhere-Object, или другого подходящего метода. Возврат массива значений приводит к тому, что PowerShell будет рассматривать весь массив как значение завершения одной вкладки.

В следующем примере добавляется завершение вкладки в параметр Value . Если указан только параметр Value , отображаются все возможные значения или аргументы для значения . При указании параметра Type параметр Value отображает только возможные значения этого типа.

Кроме того, оператор гарантирует, что если -like пользователь вводит следующую команду и использует завершение tab , возвращается только Apple .

Test-ArgumentCompleter -Type Fruits -Value A

function MyArgumentCompleter{
    param ( $commandName,
            $parameterName,
            $wordToComplete,
            $commandAst,
            $fakeBoundParameters )

    $possibleValues = @{
        Fruits = @('Apple', 'Orange', 'Banana')
        Vegetables = @('Onion', 'Carrot', 'Lettuce')
    }

    if ($fakeBoundParameters.ContainsKey('Type')) {
        $possibleValues[$fakeBoundParameters.Type] | Where-Object {
            $_ -like "$wordToComplete*"
        }
    } else {
        $possibleValues.Values | ForEach-Object {$_}
    }
}

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,

        [Parameter(Mandatory=$true)]
        [ArgumentCompleter({ MyArgumentCompleter @args })]
        $Value
      )
}

Завершенные аргументы на основе классов

Начиная с PowerShell 7.2, добавлена новая функция, которая позволяет определять более универсальные реализации параметризованных аргументов завершения.

Исходя из ArgumentCompleterAttributeэтого, можно создать универсальные комплекты, которые можно использовать повторно, например:

[DirectoryCompleter(ContainingFile="pswh.exe", Depth=2)]

[DateCompleter(WeekDay='Monday', From="LastYear")]

[GitCommits(Branch='release')]

Производные атрибуты должны реализовать IArgumentCompleterFactory интерфейс и использовать значения свойств для создания специализированного завершенного объекта.

using namespace System.Collections
using namespace System.Collections.Generic
using namespace System.Management.Automation
using namespace System.Management.Automation.Language

class NumberCompleter : IArgumentCompleter {

    [int] $From
    [int] $To
    [int] $Step

    NumberCompleter([int] $from, [int] $to, [int] $step) {
        if ($from -gt $to) {
            throw [ArgumentOutOfRangeException]::new("from")
        }
        $this.From = $from
        $this.To = $to
        $this.Step = $step -lt 1 ? 1 : $step
    }

    [IEnumerable[CompletionResult]] CompleteArgument(
        [string] $CommandName,
        [string] $parameterName,
        [string] $wordToComplete,
        [CommandAst] $commandAst,
        [IDictionary] $fakeBoundParameters) {

        $resultList = [List[CompletionResult]]::new()
        $local:to = $this.To
        $local:step = $this.Step
        for ($i = $this.From; $i -lt $to; $i += $step) {
            $resultList.Add([CompletionResult]::new($i.ToString()))
        }

        return $resultList
    }
}

class NumberCompletionsAttribute : ArgumentCompleterAttribute, IArgumentCompleterFactory {
    [int] $From
    [int] $To
    [int] $Step

    NumberCompletionsAttribute([int] $from, [int] $to, [int] $step) {
        $this.From = $from
        $this.To = $to
        $this.Step = $step
    }

    [IArgumentCompleter] Create() { return [NumberCompleter]::new($this.From, $this.To, $this.Step) }
}

Затем использование из PowerShell будет следующим:

function Add{
    param(
       [NumberCompletions(0, 100, 5)]
       [int] $X,

       [NumberCompletions(0, 100, 5)]
       [int] $Y
    )
    $X + $Y
}

Register-ArgumentCompleter

Командлет Register-ArgumentCompleter регистрирует полный настраиваемый аргумент. Полный аргумент позволяет предоставить динамическое завершение вкладки во время выполнения для любой указанной команды.

Дополнительные сведения см. в статье Register-ArgumentCompleter.

См. также