Condividi tramite

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.

Quando si chiama questo comando con il parametro CommandName e senza parametri ParameterName o Native , il comando viene eseguito come se si specificasse il parametro Native . In questo modo, il completamento dell'argomento non funziona per i parametri dei comandi di PowerShell. Specificare sempre il parametro ParameterName quando si vuole registrare un completore di argomenti per i comandi di PowerShell.

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 .

$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

Il primo comando crea un blocco di script che accetta i parametri obbligatori, che vengono 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 per gestire i valori che contengono spazi.

Il secondo comando registra il completer dell'argomento passando lo scriptblock, l'ID ParameterName e il commandName Set-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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

Il primo comando crea un blocco di script che accetta i parametri obbligatori, che vengono 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. PowerShell usa questa opzione solo per la visualizzazione. 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.

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(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

Il primo comando crea un blocco di script che accetta i parametri obbligatori, che vengono 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 esegue il completamento della scheda. I risultati vengono inviati tramite pipe al ForEach-Object cmdlet , che usa il nuovo metodo statico della classe System.Management.Automation.CompletionResult per creare un oggetto CompletionResult per ogni valore.

Parametri

-CommandName

Specifica il nome di uno o più comandi per cui registrare il completer dell'argomento. Questo parametro è obbligatorio per i comandi nativi.

Quando si specifica questo parametro senza parametri ParameterName o Native , il comando si comporta come se fosse stato specificato il parametro Native . Quando si registrano i completer di argomenti per i comandi di PowerShell, specificare sempre il parametro ParameterName .

Se non si specifica questo parametro, PowerShell registra l'argomento completer per il parametro ParameterName specificato in tutti i comandi di PowerShell.

Tipo:String[]
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-Native

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

Tipo:SwitchParameter
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-ParameterName

Specifica il nome del parametro a cui si applica l'argomento completatore. Il tipo per i parametri specificati non può essere un'enumerazione, ad esempio il parametro ForegroundColor del Write-Host cmdlet.

Per altre informazioni sulle enumerazioni, vedere about_Enum.

Quando si registra un completore di argomenti per i comandi di PowerShell, specificare sempre questo parametro. Quando si specifica il parametro CommandName senza parametri ParameterName o Native , il comando si comporta come se si specificasse il parametro Native .

Tipo:String
Posizione:Named
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly: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 può anche restituire oggetti System.Management.Automation.CompletionResult per ogni valore per migliorare l'esperienza utente. La restituzione di oggetti CompletionResult consente di definire descrizioni comando e voci di elenco personalizzate visualizzate quando gli utenti preme ctrl+ spazio per visualizzare l'elenco dei completamenti disponibili.

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, String) - Questo parametro è impostato sul nome del comando per il quale il blocco di script fornisce il completamento della scheda.
  • $parameterName (Posizione 1, String) - Questo parametro è impostato sul parametro il cui valore richiede il completamento tramite tabulazione.
  • $wordToComplete (Posizione 2, Stringa): 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 3, CommandAst): questo parametro è impostato sull'albero della sintassi astratta (AST) per la riga di input corrente. Per altre informazioni, vedere Classe CommandAst.
  • $fakeBoundParameters(Posizione 4 IDictionary): 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, Stringa): 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, CommandAst): questo parametro è impostato sull'albero della sintassi astratta (AST) per la riga di input corrente. Per altre informazioni, vedere Classe CommandAst.
  • $cursorPosition (Posizione 2, Int32): 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.

Tipo:ScriptBlock
Posizione:Named
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

Input

None

Non è possibile inviare tramite pipe oggetti a questo cmdlet.

Output

None

Questo cmdlet non restituisce output.