Partilhar via

Register-ArgumentCompleter

  • Referência
Módulo:
Microsoft.PowerShell.Core

Registra um completo 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 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 conclusor de argumentos para comandos do PowerShell.

Exemplos

Exemplo 1: Registrar um preenchedor de argumento personalizado

O exemplo a seguir registra um conclusor 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 pelo $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 manipular valores que contêm espaços.

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

Exemplo 2: Adicionar detalhes aos valores de conclusão da guia

O exemplo a seguir substitui o preenchimento da guia pelo 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 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. 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+Space.

Exemplo 3: Registrar um completo 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 o preenchimento de tabulação para a interface de dotnet linha de comando (CLI).

Nota

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 guia. 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 preenchimento do argumento. Este parâmetro é obrigatório para comandos nativos.

Quando você especifica esse parâmetro sem os parâmetros ParameterName ou Nativo , o comando se comporta como se você tivesse especificado o parâmetro Nativo . Ao registrar conclusores de argumento para comandos do PowerShell, sempre especifique o parâmetro ParameterName .

Se você não especificar esse parâmetro, o PowerShell registrará o argumento completer para o ParameterName especificado em todos os comandos do PowerShell.

Tipo:String[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Native

Indica que o preenchimento do argumento é para um comando nativo em que o PowerShell não pode concluir nomes de parâmetros.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ParameterName

Especifica o nome do parâmetro ao qual o completador de argumentos se aplica. O tipo para 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 enums, consulte about_Enum.

Ao registrar um preenchedor 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
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ScriptBlock

Especifica os comandos a serem executados para executar o preenchimento de guias. 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. O retorno de uma matriz de valores faz com que o PowerShell trate toda a matriz como um valor de conclusão de guia.

O bloco de script também pode retornar objetos System.Management.Automation.CompletionResult para cada valor para melhorar a experiência do usuário. O retorno de objetos CompletionResult permite definir dicas de ferramentas e entradas de lista personalizadas exibidas quando os usuários pressionam Ctrl+Space para mostrar a lista de finalizaçõ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 conclusão de tabulação.
  • $parameterName (Posição 1, String) - Este parâmetro é definido como o parâmetro cujo valor requer o preenchimento da guia.
  • $wordToComplete (Posição 2, String) - Este parâmetro é definido para o valor que o usuário forneceu antes de pressionar Tab. Seu bloco de script deve usar esse valor para determinar os valores de conclusão 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) - Este parâmetro é definido como uma hashtable contendo o para o cmdlet, antes que $PSBoundParameters 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 para o valor que o usuário forneceu antes de pressionar Tab. Seu bloco de script deve usar esse valor para determinar os valores de conclusão 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 pressionou 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
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

None

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

Saídas

None

Este cmdlet não retorna nenhuma saída.