Register-ArgumentCompleter

Referência

Módulo:: Microsoft.PowerShell.Core

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.

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.

$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

O primeiro comando cria um bloco de script que recebe 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 inclui cada valor entre aspas, caso o valor contenha 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,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

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 $_.Namede 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. Isso é usado apenas para exibição e 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.

O último comando demonstra que os serviços interrompidos ainda podem ser passados manualmente para o Stop-Service cmdlet. O preenchimento da guia é o único aspecto afetado.

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($_, $_, 'ParameterValue', $_)
        }
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

Dentro do bloco de script, o dotnet complete comando é usado para executar 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 novo objeto CompletionResult para cada valor.

Parâmetros

-CommandName

Especifica o nome dos comandos como uma matriz.

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 completador 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 cujo argumento está sendo concluído. O nome do parâmetro especificado não pode ser um valor enumerado, como o parâmetro ForegroundColor do Write-Host cmdlet.

Para obter mais informações sobre enumerações, consulte about_Enum.

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 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) - 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) - Este parâmetro é definido como o parâmetro cujo valor requer o preenchimento da tabulação.
$wordToComplete (Posição 2) - 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) - Este parâmetro é definido como a Árvore de Sintaxe Abstrata (AST) para a linha de entrada atual. Para obter mais informações, consulte Classe Ast.
$fakeBoundParameters (Posição 4) – esse parâmetro é definido como uma tabela de hash que contém o $PSBoundParameters cmdlet para o 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) - 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) - Este parâmetro é definido como a Árvore de Sintaxe Abstrata (AST) para a linha de entrada atual. Para obter mais informações, consulte Classe Ast.
$cursorPosition (Posição 2) - 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