Register-ArgumentCompleter

Register-ArgumentCompleter
    -ParameterName <String>
    -ScriptBlock <ScriptBlock>
    [-CommandName <String[]>]
    [<CommonParameters>]

Register-ArgumentCompleter
    -CommandName <String[]>
    -ScriptBlock <ScriptBlock>
    [-Native]
    [<CommonParameters>]

O cmdlet Register-ArgumentCompleter registra um completo de argumento personalizado. Um completador de argumentos permite que você forneça preenchimento dinâmico de guias, em tempo de execução, para qualquer comando que você especificar.

O exemplo a seguir registra um completer de argumento para o parâmetro Id do cmdlet Set-TimeZone.

$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 leva os parâmetros necessários que são passados quando o usuário pressiona <TAB>. Para obter mais informações, consulte o ScriptBlock descrição do parâmetro.

Dentro do bloco de script, os valores disponíveis para Id são recuperados usando o cmdlet Get-TimeZone. A propriedade Id para cada Fuso Horário é canalizada para o cmdlet Where-Object. O cmdlet Where-Object 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 cmdlet For-EachObject que inclui cada valor entre aspas, caso o valor contenha espaços.

O segundo comando registra o argumento completer passando o scriptblock, o ParameterName "Id" e o CommandNameSet-TimeZone.

O exemplo a seguir substitui a conclusão da guia para o parâmetro Name do cmdlet Stop-Service e retorna apenas os serviços em execução.

$s = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
    $services = Get-Service | Where-Object {$_.Status -eq "Running" }
    $services | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_,
            $_,
            "ParameterValue",
            $_
    }
}
Register-ArgumentCompleter -CommandName dotnet -Native -ScriptBlock $s

O primeiro comando cria um bloco de script que leva os parâmetros necessários que são passados quando o usuário pressiona <TAB>. Para obter mais informações, consulte o ScriptBlock descrição do parâmetro.

Dentro do bloco de script, o primeiro comando recupera todos os serviços em execução usando o cmdlet Where-Object. Os serviços são canalizados para o cmdlet ForEach-Object. O cmdlet ForEach-Object cria um novo objeto [System.Management.Automation.CompletionResult] e o preenche com os valores do serviço atual (representado pela variável de pipeline $_).

O objeto CompletionResult permite fornecer detalhes adicionais para cada valor retornado:

• completionText (String) - O texto a ser usado como resultado de preenchimento automático. Este é o valor enviado para o comando.
• listItemText (String) - O texto a ser exibido em uma lista, como quando o usuário pressiona <Ctrl>+<Space>. 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>+<Space>.

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

Você pode usar o parâmetro Native para fornecer preenchimento de tabulação para um comando nativo. O exemplo a seguir adiciona o preenchimento de tabulação para o dotnet Command Line Interface (CLI).

$scriptblock = {
     param($commandName, $wordToComplete, $cursorPosition)
         dotnet complete --position $cursorPosition "$wordToComplete" | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
         }
 }
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

O primeiro comando cria um bloco de script que leva os parâmetros necessários que são passados quando o usuário pressiona <TAB>. Para obter mais informações, consulte o ScriptBlock descrição do parâmetro.

Dentro do bloco de script, o comando dotnet complete é usado para executar o preenchimento da guia. Os resultados são canalizados para o cmdlet que usa o método novo estático da classe para criar um novo objeto CompletionResult para cada valor.

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Não é possível canalizar objetos para este cmdlet.

Este cmdlet não retorna nenhuma saída.