Register-ArgumentCompleter

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

Register-ArgumentCompleter
    -ParameterName <String>
    -ScriptBlock <ScriptBlock>
    [-CommandName <String[]>]
    [<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.

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 preenchimento de argumentos funcione para parâmetros de comando do PowerShell. Sempre especifique o parâmetro ParameterName quando quiser registrar um preenchedor de argumentos para comandos do PowerShell.

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

$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 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 ForEach-Object, que coloca cada valor entre aspas para manipular valores que contêm espaços.

O segundo comando registra o argumento completer passando o scriptblock, o ParameterNameId 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' -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 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 o nome do serviço atual (representado pela variável de pipeline $_.Name).

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+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.

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(
        $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 o ScriptBlock descrição do parâmetro.

Dentro do bloco de script, o comando dotnet complete executa o preenchimento da guia. Os resultados são canalizados para o cmdlet ForEach-Object, que usa o método novo estático da classe System.Management.Automation.CompletionResult para criar um 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.