Register-ArgumentCompleter

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

Registra um completo de argumento personalizado.

Syntax

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.

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.

$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 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, caso o valor contenha espaços.

O segundo comando registra o argumento completer passando o scriptblock, o ParameterNameId e o CommandNameSet-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,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
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. 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 Stop-Service cmdlet. O preenchimento da guia é o único aspeto afetado.

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($_, $_, 'ParameterValue', $_)
        }
}
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 é usado para executar 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 novo objeto CompletionResult para cada valor.

Parâmetros

-CommandName

Especifica o nome dos comandos como uma matriz.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Native

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 enums, consulte about_Enum.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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 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 preenchimento de tabulação.
  • $parameterName (Posição 1) - Este parâmetro é definido como o parâmetro cujo valor requer preenchimento de tabulação.
  • $wordToComplete (Posição 2) - 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) - 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) – Este parâmetro está definido para uma tabela hash que contenha o cmdlet $PSBoundParameters, antes de o utilizador premir a Tecla de Tabulação. Para obter mais informações, veja 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 para valorizar o 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) - 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.

Type:ScriptBlock
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

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

Saídas

None

Este cmdlet não retorna nenhuma saída.