Register-ArgumentCompleter

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 $_.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. 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).

$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

-Native

-ParameterName

-ScriptBlock

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

None

Esse cmdlet não retorna nenhuma saída.

Links Relacionados

• about_Functions_Argument_Completion