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.
Атрибут 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 , отображаются все возможные значения или аргументы для значения . При указании параметра 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
)
}
Register-ArgumentCompleter
Командлет Register-ArgumentCompleter
регистрирует полный настраиваемый аргумент.
Полный аргумент позволяет предоставить динамическое завершение вкладки во время выполнения для любой указанной команды.
Дополнительные сведения см. в статье Register-ArgumentCompleter.
См. также
PowerShell