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

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 регистрирует полный настраиваемый аргумент. Полный аргумент позволяет предоставить динамическое завершение вкладки во время выполнения для любой указанной команды.

При вызове этой команды с параметром CommandName и без параметров ParameterName или Native команда выполняется, как если бы вы указали собственный параметр. Это предотвращает работу аргумента для параметров команды PowerShell. Всегда указывайте параметр ParameterName , если требуется зарегистрировать завершенный аргумент для команд PowerShell.

Примеры

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

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

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

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
        "'$_'"
    }
}

Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s

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

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

Вторая команда регистрирует полный аргумент путем передачи скриптблока, идентификатора имени параметра и имени командыSet-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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

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+ПРОБЕЛ. PowerShell использует это только для отображения. Он не передается команде при выборе.
  • resultType (CompletionResultType) — тип результата завершения.
  • подсказка (Строка) — текст подсказки со сведениями о объекте. Это видно, когда пользователь выбирает элемент после нажатия клавиш CTRL+ПРОБЕЛ.

Пример 3. Регистрация пользовательского полного аргумента 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(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

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

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

Параметры

-CommandName

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

При указании этого параметра без параметров ParameterName или Native команда ведет себя так, как если бы вы указали собственный параметр. При регистрации завершенных аргументов для команд PowerShell всегда укажите параметр ParameterName .

Если этот параметр не указан, PowerShell регистрирует полный аргумент для указанного имени параметра во всех командах PowerShell.

Тип: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.

При регистрации завершенного аргумента для команд PowerShell всегда укажите этот параметр. При указании параметра CommandName без параметров ParameterName или Native команда ведет себя так, как если бы вы указали собственный параметр.

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

-ScriptBlock

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

Блок скрипта также может возвращать объекты System.Management.Automation.CompletionResult для каждого значения, чтобы улучшить взаимодействие с пользователем. Возврат объектов CompletionResult позволяет определять подсказки и настраиваемые записи списка, отображаемые при нажатии клавиш CTRL+ПРОБЕЛ, чтобы отобразить список доступных завершений.

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

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

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

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

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

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

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

None

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

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

None

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