Register-ArgumentCompleter

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 .

$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

-Native

-ParameterName

-ScriptBlock

Input

None

Non è possibile inviare tramite pipe oggetti a questo cmdlet.

Output

None

Questo cmdlet non restituisce output.

Collegamenti correlati

• about_Functions_Argument_Completion