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

about_Functions_Argument_Completion

  • Статья

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

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

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

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

Примечание

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 должна иметь значение Chocolate, Strawberry или Vanilla. Атрибут 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.

Динамические значения 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 , которому требуется scriptblock для определения параметров. указанные значения доступны

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

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-Object, Where-Objectили другого подходящего метода. Возврат массива значений приводит к тому, что PowerShell обрабатывает весь массив как одно значение завершения табуляции.

В следующем примере к параметру Value добавляется завершение табуляции. Если указан только параметр 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.

См. также раздел