Partilhar via

Register-ArgumentCompleter

Módulo:
Microsoft.PowerShell.Core Module

Registra um completo de argumento personalizado.

Sintaxe

NativeSet 

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

PowerShellSet 

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

Description

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.

Exemplos

Exemplo 1: Registrar um preenchedor de argumento personalizado

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 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 cmdlet Get-TimeZone. A propriedade Id para cada Fuso Horário é canalizada para o cmdlet Where-Object. 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 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,
            $_.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 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. 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+Espaço.

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.

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 o dotnet Command Line Interface (CLI).

Observação

O comando dotnet complete 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 comando dotnet complete é 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.

Propriedades dos parâmetros

Tipo:

String[]

Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

NativeSet
Position:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False
PowerShellSet
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Native

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

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

NativeSet
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 cmdlet Write-Host.

Para obter mais informações sobre enums, consulte about_Enum.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

PowerShellSet
Position:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos: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 como 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 Ast Class.
  • $fakeBoundParameters (Posição 4) - Este parâmetro é definido como uma hashtable contendo o $PSBoundParameters para o cmdlet, antes que o usuário pressione Tab. Para obter mais informações, consulte about_Automatic_Variables.

Quando você especifica o parâmetro Native, 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 Ast Class.
  • $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. Consulte about_Functions_Advanced_Parameterspara obter mais informações.

Propriedades dos parâmetros

Tipo:ScriptBlock
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

CommonParameters

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.

Entradas

None

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

Saídas

None

Este cmdlet não retorna nenhuma saída.