Register-ArgumentCompleter

Ссылка

Модуль:: Microsoft.PowerShell.Core

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

Синтаксис

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, который заключает каждое значение в кавычки, должно содержать пробелы.

Вторая команда регистрирует полный аргумент, передав блок скрипта, идентификатор параметра и имя CommandName.

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

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

$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

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

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

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

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

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

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

Заметка

Команда dotnet complete доступна только в версии 2.0 и более поздней версии dotnet cli.

$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

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

Параметры

-CommandName

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

Тип:	String[]
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-Native

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

Тип:	SwitchParameter
Position:	Named
Default value:	None
Обязательно:	False
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

-ParameterName

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

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

Тип:	String
Position:	Named
Default value:	None
Обязательно:	True
Принять входные данные конвейера:	False
Принять подстановочные знаки:	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.

Тип:	ScriptBlock
Position:	Named
Default value:	None
Обязательно:	True
Принять входные данные конвейера:	False
Принять подстановочные знаки:	False

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

None

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

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