Register-ArgumentCompleter
Registra um completador de argumento personalizado.
Sintaxe
Register-ArgumentCompleter
-CommandName <String[]>
-ScriptBlock <ScriptBlock>
[-Native]
[<CommonParameters>]
Register-ArgumentCompleter
[-CommandName <String[]>]
-ParameterName <String>
-ScriptBlock <ScriptBlock>
[<CommonParameters>]
Description
O Register-ArgumentCompleter
cmdlet registra um completador de argumento personalizado. Um completador de argumentos permite que você forneça o preenchimento dinâmico de tabulação, em tempo de execução para qualquer comando especificado.
Quando você chama esse comando com o parâmetro CommandName e sem os parâmetros ParameterName ou Native , o comando é executado como se você tivesse especificado o parâmetro Native . Isso impede que o completador de argumentos funcione para parâmetros de comando do PowerShell. Sempre especifique o parâmetro ParameterName quando quiser registrar um completador de argumentos para comandos do PowerShell.
Exemplos
Exemplo 1: Registrar um completador de argumento personalizado
O exemplo a seguir registra um completer de argumento para o parâmetro Id do Set-TimeZone
cmdlet.
$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
O primeiro comando cria um bloco de script que usa os parâmetros necessários, que são passados quando o usuário pressiona Tab. Para obter mais informações, consulte a descrição do parâmetro ScriptBlock .
Dentro do bloco de script, os valores disponíveis para Id são recuperados usando o Get-TimeZone
cmdlet. A propriedade Id de cada fuso horário é canalizada para o Where-Object
cmdlet. O Where-Object
cmdlet filtra todas as IDs que não começam com o valor fornecido por $wordToComplete
, que representa o texto que o usuário digitou antes de pressionar Tab. As IDs filtradas são canalizadas para o ForEach-Object
cmdlet, que coloca cada valor entre aspas para lidar com valores que contêm espaços.
O segundo comando registra o completer de argumentos passando o scriptblock, o ParameterName Id e o CommandName Set-TimeZone
.
Exemplo 2: Adicionar detalhes aos valores de preenchimento de tabulação
O exemplo a seguir substitui a conclusão de tabulação para o parâmetro Name do Stop-Service
cmdlet e retorna apenas os serviços em execução.
$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
O primeiro comando cria um bloco de script que usa os parâmetros necessários, que são passados quando o usuário pressiona Tab. Para obter mais informações, consulte a descrição do parâmetro ScriptBlock .
Dentro do bloco de script, o primeiro comando recupera todos os serviços em execução usando o Where-Object
cmdlet. Os serviços são canalizados para o ForEach-Object
cmdlet. O ForEach-Object
cmdlet cria um novo objeto System.Management.Automation.CompletionResult e o preenche com o nome do serviço atual (representado pela variável $_.Name
de pipeline).
O objeto CompletionResult permite que você forneça detalhes adicionais para cada valor retornado:
- completionText (String) - O texto a ser usado como resultado do preenchimento automático. Esse é o valor enviado ao comando.
- listItemText (String) - O texto a ser exibido em uma lista, como quando o usuário pressiona Ctrl+Espaço. O PowerShell usa isso apenas para exibição. Ele não é passado para o comando quando selecionado.
- resultType (CompletionResultType) - O tipo de resultado de conclusão.
- toolTip (String) - O texto da dica de ferramenta com detalhes a serem exibidos sobre o objeto. Isso é visível quando o usuário seleciona um item depois de pressionar Ctrl+Espaço.
Exemplo 3: Registrar um completador de argumento nativo personalizado
Você pode usar o parâmetro Native para fornecer preenchimento de tabulação para um comando nativo. O exemplo a seguir adiciona preenchimento de tabulação para a dotnet
CLI (Interface de Linha de Comando).
Observação
O dotnet complete
comando só está disponível na versão 2.0 e superior da CLI dotnet.
$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
O primeiro comando cria um bloco de script que usa os parâmetros necessários, que são passados quando o usuário pressiona Tab. Para obter mais informações, consulte a descrição do parâmetro ScriptBlock .
Dentro do bloco de script, o dotnet complete
comando executa o preenchimento da tabulação. Os resultados são canalizados para o ForEach-Object
cmdlet, que usa o novo método estático da classe System.Management.Automation.CompletionResult para criar um objeto CompletionResult para cada valor.
Parâmetros
-CommandName
Especifica o nome de um ou mais comandos para registrar o completador de argumentos. Este parâmetro é obrigatório para comandos nativos.
Quando você especifica esse parâmetro sem os parâmetros ParameterName ou Native , o comando se comporta como se você tivesse especificado o parâmetro Native . Ao registrar complementadores de argumento para comandos do PowerShell, sempre especifique o parâmetro ParameterName .
Se você não especificar esse parâmetro, o PowerShell registrará o completer de argumentos para o ParameterName especificado em todos os comandos do PowerShell.
Tipo: | String[] |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Native
Indica que o completer de argumentos é para um comando nativo em que o PowerShell não pode concluir nomes de parâmetros.
Tipo: | SwitchParameter |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-ParameterName
Especifica o nome do parâmetro ao qual o concluidor de argumentos se aplica. O tipo de parâmetros especificados não pode ser uma enumeração, como o parâmetro ForegroundColor do Write-Host
cmdlet.
Para obter mais informações sobre enumerações, consulte about_Enum.
Ao registrar um completador de argumentos para comandos do PowerShell, sempre especifique esse parâmetro. Quando você especifica o parâmetro CommandName sem os parâmetros ParameterName ou Native , o comando se comporta como se você tivesse especificado o parâmetro Native .
Tipo: | String |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-ScriptBlock
Especifica os comandos a serem executados para executar o preenchimento de tabulação. O bloco de script fornecido deve retornar os valores que completam a entrada. O bloco de script deve desenrolar os valores usando o pipeline (ForEach-Object
, Where-Object
, etc.) ou outro método adequado. Retornar uma matriz de valores faz com que o PowerShell trate toda a matriz como um valor de conclusão de tabulação.
O bloco de script também pode retornar objetos System.Management.Automation.CompletionResult para cada valor para aprimorar a experiência do usuário. O retorno de objetos CompletionResult permite que você defina dicas de ferramentas e entradas de lista personalizadas exibidas quando os usuários pressionam Ctrl+Space para mostrar a lista de conclusões disponíveis.
O bloco de script deve aceitar os seguintes parâmetros na ordem especificada abaixo. Os nomes dos parâmetros não são importantes porque o PowerShell passa os valores por posição.
$commandName
(Posição 0, String) - Este parâmetro é definido como o nome do comando para o qual o bloco de script está fornecendo o preenchimento da guia.$parameterName
(Posição 1, String) - Este parâmetro é definido como o parâmetro cujo valor requer o preenchimento da tabulação.$wordToComplete
(Posição 2, String) - Este parâmetro é definido como o valor que o usuário forneceu antes de pressionar Tab. Seu bloco de script deve usar esse valor para determinar os valores de preenchimento de tabulação.$commandAst
(Posição 3, CommandAst) - Este parâmetro é definido como a Árvore de Sintaxe Abstrata (AST) para a linha de entrada atual. Para obter mais informações, consulte Classe CommandAst.$fakeBoundParameters
(Posição 4 IDictionary) – esse parâmetro é definido como uma tabela de hash que contém o$PSBoundParameters
cmdlet, antes que o usuário pressione Tab. Para obter mais informações, consulte about_Automatic_Variables.
Quando você especifica o parâmetro Nativo , o bloco de script deve usar os seguintes parâmetros na ordem especificada. Os nomes dos parâmetros não são importantes porque o PowerShell passa os valores por posição.
$wordToComplete
(Posição 0, String) - Este parâmetro é definido como o valor que o usuário forneceu antes de pressionar Tab. Seu bloco de script deve usar esse valor para determinar os valores de preenchimento de tabulação.$commandAst
(Posição 1, CommandAst) - Este parâmetro é definido como a Árvore de Sintaxe Abstrata (AST) para a linha de entrada atual. Para obter mais informações, consulte Classe CommandAst.$cursorPosition
(Posição 2, Int32) - Este parâmetro é definido para a posição do cursor quando o usuário pressiona Tab.
Você também pode fornecer um ArgumentCompleter como um atributo de parâmetro. Para obter mais informações, consulte about_Functions_Advanced_Parameters.
Tipo: | ScriptBlock |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
Entradas
None
Você não pode canalizar objetos para esse cmdlet.
Saídas
None
Esse cmdlet não retorna nenhuma saída.