about_Functions_Argument_Completion
Descrição breve
A conclusão de argumentos é um recurso do PowerShell que fornece dicas, habilita a descoberta e acelera a entrada de valores de argumento.
Descrição longa
Este artigo descreve as diferentes maneiras de implementar completadores de argumentos para funções do PowerShell. Os completadores de argumentos fornecem os valores possíveis para um parâmetro. Os valores disponíveis são calculados em tempo de execução quando o usuário pressiona a tecla Tab após o nome do parâmetro. Há várias maneiras de definir um complementador de argumento para um parâmetro.
Observação
Tab é a associação de chave padrão no Windows. Essa associação de chave pode ser alterada pelo módulo PSReadLine ou pelo aplicativo que está hospedando o PowerShell. A associação de chaves é diferente em plataformas que não sejam Windows. Para obter mais informações, confira about_PSReadLine.
Atributo ValidateSet
O atributo ValidateSet especifica um conjunto de valores válidos para um parâmetro ou variável e habilita o preenchimento de tabulação. O PowerShell gerará um erro se um valor de parâmetro ou variável não corresponder a um valor no conjunto. No exemplo a seguir, o valor do parâmetro Fruit só pode ser Apple, Banana ou Pear.
Param(
[Parameter(Mandatory=$true)]
[ValidateSet('Apple', 'Banana', 'Pear')]
[string[]]
$Fruit
)
No exemplo a seguir, o valor da variável $flavor deve ser Chocolate, Morango ou Baunilha. O ValidateSet atributo pode ser usado em qualquer variável, não apenas em parâmetros.
[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'
A validação ocorre sempre que essa variável é atribuída mesmo dentro do script.
Param(
[ValidateSet('hello', 'world')]
[string]$Message
)
$Message = 'bye'
Este exemplo retorna o seguinte erro em tempo de execução:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Para obter mais informações sobre expansão de guias, consulte about_Tab_Expansion.
Valores Dynamic ValidateSet usando classes
Você pode usar uma classe para gerar dinamicamente os valores para ValidateSet em tempo de execução. No exemplo a seguir, os valores válidos para a variável $Sound são gerados por meio de uma classe chamada SoundNames que verifica três caminhos de sistema de arquivos para arquivos de som disponíveis:
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
}
}
A [SoundNames] classe é então implementada como um valor ValidateSet dinâmico da seguinte maneira:
Param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Observação
A IValidateSetValuesGenerator classe foi introduzida no PowerShell 6.0.
Atributo ArgumentCompletions
O atributo ArgumentCompletions permite adicionar valores de conclusão de tabulação a um parâmetro específico. Um atributo ArgumentCompletions deve ser definido para cada parâmetro que precisa de conclusão de tabulação. O atributo ArgumentCompletions é semelhante a ValidateSet. Ambos os atributos usam uma lista de valores a serem apresentados quando o usuário pressiona Tab após o nome do parâmetro. No entanto, ao contrário de ValidateSet, os valores não são validados e mais como sugestões. Portanto, o usuário pode fornecer qualquer valor, não apenas os valores na lista.
O atributo ArgumentCompletions não deve ser confundido com o atributo ArgumentCompleter , que precisa de um scriptblock para definir as opções. os valores especificados estão disponíveis
A sintaxe dela é a seguinte:
function Test-ArgumentCompletions {
[CmdletBinding()]
param (
[Parameter(Mandatory=$true)]
[ArgumentCompletions('Fruits', 'Vegetables')]
$Type,
[Parameter()]
[ArgumentCompletions('Apple', 'Banana', 'Orange')]
$Fruit,
[Parameter()]
[ArgumentCompletions('Onion', 'Carrot', 'Lettuce')]
$Vegetable
)
}
Cada um dos parâmetros recebe uma lista de opções para o atributo ArgumentCompletions para habilitar a conclusão de tabulação.
Esse atributo foi introduzido no PowerShell 6.0.
Atributo ArgumentCompleter
O atributo ArgumentCompleter permite adicionar valores de conclusão de tabulação a um parâmetro específico. Um atributo ArgumentCompleter deve ser definido para cada parâmetro que precisa de conclusão de tabulação.
Para adicionar um atributo ArgumentCompleter , você precisa definir um bloco de script que determine os valores. O bloco de script deve ter os seguintes parâmetros na ordem especificada abaixo. Os nomes dos parâmetros não importam, pois os valores são fornecidos posicionalmente.
A sintaxe dela é a seguinte:
function MyArgumentCompleter {
Param(
[Parameter(Mandatory)]
[ArgumentCompleter( {
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
# Perform calculation of tab completed values here.
} )]
$ParamName
)
}
Bloco de script ArgumentCompleter
Os parâmetros de bloco de script são definidos com os seguintes valores:
$commandName(Posição 0) - Esse parâmetro é definido como o nome do comando para o qual o bloco de script está fornecendo conclusão de tabulação.$parameterName(Posição 1) - Este parâmetro é definido como o parâmetro cujo valor requer preenchimento de tabulação.$wordToComplete(Posição 2) - Este parâmetro é definido para o valor que o usuário forneceu antes de pressionar Tab. Seu bloco de script deve usar esse valor para determinar valores de conclusão de tabulação.$commandAst(Posição 3) - Este parâmetro é definido como a Árvore de Sintaxe Abstrata (AST) para a linha de entrada atual. Para obter mais informações, consulte a documentação do tipo AST .$fakeBoundParameters(Posição 4) - Esse parâmetro é definido como uma tabela de hash que contém o$PSBoundParameterspara o cmdlet, antes que o usuário pressione Tab. Para obter mais informações, consulte about_Automatic_Variables.
O bloco de script ArgumentCompleter deve desenrolar os valores usando o pipeline, como ForEach-Object, Where-Objectou outro método adequado.
O retorno de uma matriz de valores faz com que o PowerShell trate toda a matriz como um valor de conclusão de tabulação.
O exemplo a seguir adiciona autocompletar de tabulação ao parâmetro Value . Se apenas o parâmetro Value for especificado, todos os valores ou argumentos possíveis para Value serão exibidos. Quando o parâmetro Type é especificado, o parâmetro Value exibe apenas os valores possíveis para esse tipo.
Além disso, o operador garante que, se o usuário digitar o seguinte comando e usar a conclusão de tabulação, somente a -like Apple será retornada.
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
)
}
Completadores de argumentos baseados em classe
A partir do PowerShell 7.2, um novo recurso foi adicionado que permite definir implementações mais genéricas de completadores de argumentos parametrizados.
Derivando do ArgumentCompleterAttribute, é possível criar completers genéricos que podem ser reutilizados, por exemplo:
[DirectoryCompleter(ContainingFile="pswh.exe", Depth=2)]
[DateCompleter(WeekDay='Monday', From="LastYear")]
[GitCommits(Branch='release')]
Os atributos derivados devem implementar a IArgumentCompleterFactory interface e usar valores de propriedade para criar um completador especializado.
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) }
}
O uso do PowerShell seria, então:
function Add{
param(
[NumberCompletions(0, 100, 5)]
[int] $X,
[NumberCompletions(0, 100, 5)]
[int] $Y
)
$X + $Y
}
Register-ArgumentCompleter
O Register-ArgumentCompleter cmdlet registra um completo de argumento personalizado.
Um completador de argumentos permite que você forneça conclusão de guia dinâmica, em tempo de execução, para qualquer comando que você especificar.
Para obter mais informações, consulte Register-ArgumentCompleter.
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de