Register-ArgumentCompleter

  • Riferimento
Modulo:
Microsoft.PowerShell.Core

Registra un completore di argomenti personalizzato.

Sintassi

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

Descrizione

Il Register-ArgumentCompleter cmdlet registra un completore di argomenti personalizzato. Un completore di argomenti consente di fornire il completamento di schede dinamiche, in fase di esecuzione per qualsiasi comando specificato.

Esempio

Esempio 1: Registrare un completore di argomenti personalizzato

Nell'esempio seguente viene registrato un completore di argomenti per il parametro Id del 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

Il primo comando crea un blocco di script che accetta i parametri obbligatori passati quando l'utente preme TAB. Per altre informazioni, vedere la descrizione del parametro ScriptBlock .

All'interno del blocco di script, i valori disponibili per ID vengono recuperati usando il Get-TimeZone cmdlet . La proprietà Id per ogni fuso orario viene inviata tramite pipe al Where-Object cmdlet . Il Where-Object cmdlet filtra tutti gli ID che non iniziano con il valore fornito da $wordToComplete, che rappresenta il testo digitato dall'utente prima di premere TAB. Gli ID filtrati vengono inviati tramite pipe al ForEach-Object cmdlet che racchiude ogni valore tra virgolette, se il valore contiene spazi.

Il secondo comando registra il completer dell'argomento passando lo scriptblock, l'ID ParameterNamee il CommandNameSet-TimeZone.

Esempio 2: Aggiungere dettagli ai valori di completamento della scheda

L'esempio seguente sovrascrive il completamento della scheda per il parametro Name del Stop-Service cmdlet e restituisce solo i servizi in esecuzione.

$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

Il primo comando crea un blocco di script che accetta i parametri obbligatori passati quando l'utente preme TAB. Per altre informazioni, vedere la descrizione del parametro ScriptBlock .

All'interno del blocco di script, il primo comando recupera tutti i servizi in esecuzione usando il Where-Object cmdlet . I servizi vengono inviati tramite pipe al ForEach-Object cmdlet . Il ForEach-Object cmdlet crea un nuovo oggetto System.Management.Automation.CompletionResult e lo popola con il nome del servizio corrente (rappresentato dalla variabile $_.Namedella pipeline ).

L'oggetto CompletionResult consente di fornire dettagli aggiuntivi a ogni valore restituito:

  • completionText (String) - Testo da usare come risultato di completamento automatico. Questo è il valore inviato al comando.
  • listItemText (String) - Testo da visualizzare in un elenco, ad esempio quando l'utente preme CTRL+SPAZIO. Viene usato solo per la visualizzazione e non viene passato al comando quando selezionato.
  • resultType (CompletionResultType): tipo di risultato di completamento.
  • toolTip (String) - Testo della descrizione comando con i dettagli da visualizzare sull'oggetto. Questa opzione è visibile quando l'utente seleziona un elemento dopo aver premuto CTRL+SPAZIO.

L'ultimo comando dimostra che i servizi arrestati possono comunque essere passati manualmente al Stop-Service cmdlet . Il completamento della scheda è l'unico aspetto interessato.

Esempio 3: Registrare un completore di argomenti nativi personalizzato

È possibile usare il parametro Native per fornire il completamento tramite tabulazione per un comando nativo. Nell'esempio seguente viene aggiunto il completamento tramite tabulazione per l'interfaccia della dotnet riga di comando .

Nota

Il dotnet complete comando è disponibile solo nella versione 2.0 e successiva dell'interfaccia della riga di comando 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

Il primo comando crea un blocco di script che accetta i parametri obbligatori passati quando l'utente preme TAB. Per altre informazioni, vedere la descrizione del parametro ScriptBlock .

All'interno del blocco di script, il dotnet complete comando viene usato per eseguire il completamento della scheda. I risultati vengono inviati tramite pipe al ForEach-Object cmdlet che utilizzano il nuovo metodo statico della classe System.Management.Automation.CompletionResult per creare un nuovo oggetto CompletionResult per ogni valore.

Parametri

-CommandName

Specifica il nome dei comandi come matrice.

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

-Native

Indica che l'argomento completer è per un comando nativo in cui PowerShell non può completare i nomi dei parametri.

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

-ParameterName

Specifica il nome del parametro il cui argomento viene completato. Il nome del parametro specificato non può essere un valore enumerato, ad esempio il parametro ForegroundColor del Write-Host cmdlet.

Per altre informazioni sulle enumerazioni, vedere about_Enum.

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

-ScriptBlock

Specifica i comandi da eseguire per eseguire il completamento della scheda. Il blocco di script specificato deve restituire i valori che completano l'input. Il blocco di script deve annullare la registrazione dei valori usando la pipeline (ForEach-Object, Where-Objecte così via) o un altro metodo appropriato. Se si restituisce una matrice di valori, PowerShell considera l'intera matrice come un valore di completamento tramite tabulazione.

Il blocco di script deve accettare i parametri seguenti nell'ordine specificato di seguito. I nomi dei parametri non sono importanti perché PowerShell passa i valori in base alla posizione.

  • $commandName (Posizione 0): questo parametro viene impostato sul nome del comando per il quale il blocco di script fornisce il completamento tramite tabulazione.
  • $parameterName (Posizione 1): questo parametro è impostato sul parametro il cui valore richiede il completamento della scheda.
  • $wordToComplete (Posizione 2): questo parametro è impostato sul valore fornito dall'utente prima di premere TAB. Il blocco di script deve usare questo valore per determinare i valori di completamento della scheda.
  • $commandAst (Posizione 3): questo parametro è impostato sull'albero della sintassi astratta (AST) per la riga di input corrente. Per altre informazioni, vedere Classe Ast.
  • $fakeBoundParameters(Posizione 4): questo parametro è impostato su una tabella hash contenente per $PSBoundParameters il cmdlet, prima che l'utente preme tab. Per altre informazioni, vedere about_Automatic_Variables.

Quando si specifica il parametro Native , il blocco di script deve accettare i parametri seguenti nell'ordine specificato. I nomi dei parametri non sono importanti perché PowerShell passa i valori in base alla posizione.

  • $wordToComplete (Posizione 0): questo parametro è impostato sul valore specificato dall'utente prima di premere TAB. Il blocco di script deve usare questo valore per determinare i valori di completamento della scheda.
  • $commandAst (Posizione 1): questo parametro è impostato sull'albero della sintassi astratta (AST) per la riga di input corrente. Per altre informazioni, vedere Classe Ast.
  • $cursorPosition (Posizione 2): questo parametro viene impostato sulla posizione del cursore quando l'utente ha premuto TAB.

È anche possibile specificare argumentCompleter come attributo di parametro. Per altre informazioni, vedere about_Functions_Advanced_Parameters.

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

Input

None

Non è possibile inviare tramite pipe oggetti a questo cmdlet.

Output

None

Questo cmdlet non restituisce output.