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

Register-ArgumentCompleter

  • Ссылка
Модуль:
Microsoft.PowerShell.Core

Регистрирует пользовательский метод завершения аргументов.

Синтаксис

Register-ArgumentCompleter
        -CommandName <String[]>
        -ScriptBlock <ScriptBlock>
        [-Native]
        [<CommonParameters>]
Register-ArgumentCompleter
        [-CommandName <String[]>]
        -ParameterName <String>
        -ScriptBlock <ScriptBlock>
        [<CommonParameters>]

Описание

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

Примеры

Пример 1. Регистрация завершения пользовательского аргумента

В следующем примере регистрируется метод завершения аргумента для параметра Id командлета Set-TimeZone .

$scriptBlock = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
          "'$_'"
    }
}
Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $scriptBlock

Первая команда создает блок скрипта, который принимает необходимые параметры, передаваемые при нажатии пользователем клавиши TAB. Дополнительные сведения см. в описании параметра ScriptBlock .

В блоке скрипта доступные значения id извлекаются с помощью командлета Get-TimeZone . Свойство Id для каждого часового пояса передается в Where-Object командлет . Командлет Where-Object отфильтровывает все идентификаторы, которые не начинаются со значения , предоставленного параметром $wordToComplete, который представляет текст, введенный пользователем до нажатия клавиши TAB. Отфильтрованные идентификаторы передаются в ForEach-Object командлет, который заключает каждое значение в кавычки, если значение содержит пробелы.

Вторая команда регистрирует завершение аргумента, передавая scriptblock, идентификатор ParameterName и CommandNameSet-TimeZone.

Пример 2. Добавление сведений в значения завершения табуляции

В следующем примере выполняется перезапись завершения табуляции для параметра Name командлета Stop-Service и возвращаются только запущенные службы.

$s = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
    $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"}
    $services | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_.Name,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

Первая команда создает блок скрипта, который принимает необходимые параметры, передаваемые при нажатии пользователем клавиши TAB. Дополнительные сведения см. в описании параметра ScriptBlock .

В блоке скрипта первая команда извлекает все запущенные службы с помощью командлета Where-Object . Службы передаются в ForEach-Object командлет . Командлет ForEach-Object создает новый объект System.Management.Automation.CompletionResult и заполняет его именем текущей службы (представленной переменной $_.Nameконвейера ).

Объект CompletionResult позволяет указать дополнительные сведения о каждом возвращаемом значении:

  • completionText (String) — текст, используемый в качестве результата автозавершения. Это значение, отправленное команде.
  • listItemText (String) — текст, отображаемый в списке, например, когда пользователь нажимает клавиши CTRL+ПРОБЕЛ. Используется только для отображения и не передается команде при выборе.
  • resultType (CompletionResultType) — тип результата завершения.
  • toolTip (String) — текст подсказки с подробными сведениями об объекте. Это отображается, когда пользователь выбирает элемент после нажатия клавиши CTRL+ПРОБЕЛ.

Последняя команда демонстрирует, что остановленные службы по-прежнему можно передать в командлет вручную Stop-Service . Единственный аспект, на который влияет завершение табуляции.

Пример 3. Регистрация пользовательского комплекта собственных аргументов

Параметр Native можно использовать для предоставления завершения табуляции для собственной команды. В следующем примере добавляется завершение табуляции для интерфейса командной dotnet строки (CLI).

Примечание

Команда dotnet complete доступна только в интерфейсе командной строки dotnet версии 2.0 и выше.

$scriptblock = {
    param($wordToComplete, $commandAst, $cursorPosition)
        dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
        }
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

Первая команда создает блок скрипта, который принимает необходимые параметры, передаваемые при нажатии пользователем клавиши TAB. Дополнительные сведения см. в описании параметра ScriptBlock .

В блоке скрипта dotnet complete для завершения табуляции используется команда . Результаты передаются в ForEach-Object командлет, который использует новый статический метод класса System.Management.Automation.CompletionResult для создания нового объекта CompletionResult для каждого значения.

Параметры

-CommandName

Задает имя команд в виде массива.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Native

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ParameterName

Указывает имя параметра, аргумент которого завершается. Указанное имя параметра не может быть перечисленным значением, например параметр ForegroundColor командлета Write-Host .

Дополнительные сведения о перечислениях см. в разделе about_Enum.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ScriptBlock

Указывает команды для выполнения завершения табуляции. Предоставленный блок скрипта должен возвращать значения, которые завершают входные данные. Блок скрипта должен раскрутить значения с помощью конвейера (ForEach-Object, Where-Objectи т. д.) или другого подходящего метода. Возврат массива значений приводит к тому, что PowerShell обрабатывает весь массив как одно значение завершения табуляции.

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

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

При указании параметра Native блок скрипта должен принимать следующие параметры в указанном порядке. Имена параметров не важны, так как PowerShell передает значения по позиции.

  • $wordToComplete (Позиция 0) — этот параметр имеет значение, указанное пользователем перед нажатием клавиши TAB. Блок скрипта должен использовать это значение для определения значений завершения табуляции.
  • $commandAst (Позиция 1) — для этого параметра задано абстрактное синтаксический дерево (AST) для текущей входной строки. Дополнительные сведения см. в разделе Класс Ast.
  • $cursorPosition (Позиция 2) — этот параметр устанавливается в положение курсора при нажатии пользователем клавиши TAB.

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

Type:ScriptBlock
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Входные данные

None

Вы не можете передавать объекты в этот командлет.

Выходные данные

None

Этот командлет не возвращает выходные данные.