Register-ArgumentCompleter

Syntaxe

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

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

Description

L’applet Register-ArgumentCompleter de commande inscrit un completer d’argument personnalisé. Un compléteur d’arguments vous permet de fournir une saisie semi-automatique de tabulation dynamique, au moment de l’exécution pour toute commande que vous spécifiez.

Lorsque vous appelez cette commande avec le paramètre CommandName et sans les paramètres ParameterName ou Natif, la commande s’exécute comme si vous avez spécifié le paramètre natif. Cela empêche le completer d’argument de fonctionner pour les paramètres de commande PowerShell. Spécifiez toujours le paramètre ParameterName lorsque vous souhaitez inscrire un completer d’argument pour les commandes PowerShell.

Exemples

Exemple 1 : Inscrire un completer d’argument personnalisé

L’exemple suivant inscrit un completer d’argument pour le paramètre ID de l’applet Set-TimeZone de commande.

$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

La première commande crée un bloc de script qui accepte les paramètres requis, qui sont passés lorsque l’utilisateur appuie sur Tab. Pour plus d’informations, consultez la description du paramètre ScriptBlock .

Dans le bloc de script, les valeurs disponibles pour ID sont récupérées à l’aide de l’applet de Get-TimeZone commande. La propriété ID pour chaque fuseau horaire est redirigée vers l’applet de Where-Object commande. L’applet Where-Object de commande filtre les ID qui ne commencent pas par la valeur fournie par $wordToComplete, qui représente le texte tapé par l’utilisateur avant d’appuyer sur Tab. Les ID filtrés sont redirigés vers l’applet ForEach-Object de commande, ce qui place chaque valeur entre guillemets pour gérer les valeurs qui contiennent des espaces.

La deuxième commande inscrit l’argument completer en passant le scriptblock, l’ID ParameterName et le CommandName Set-TimeZone.

Exemple 2 : Ajouter des détails à vos valeurs de saisie semi-automatique de tabulation

L’exemple suivant remplace la saisie semi-automatique de tabulation pour le paramètre Name de l’applet Stop-Service de commande et retourne uniquement les services en cours d’exécution.

$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

La première commande crée un bloc de script qui accepte les paramètres requis, qui sont passés lorsque l’utilisateur appuie sur Tab. Pour plus d’informations, consultez la description du paramètre ScriptBlock .

Dans le bloc de script, la première commande récupère tous les services en cours d’exécution à l’aide de l’applet de Where-Object commande. Les services sont redirigés vers l’applet ForEach-Object de commande. L’applet ForEach-Object de commande crée un objet System.Management.Automation.CompletionResult et le remplit avec le nom du service actuel (représenté par la variable $_.Namede pipeline).

L’objet CompletionResult vous permet de fournir des détails supplémentaires à chaque valeur retournée :

• completionText (String) : texte à utiliser comme résultat de saisie semi-automatique. Il s’agit de la valeur envoyée à la commande.
• listItemText (String) : texte à afficher dans une liste, par exemple lorsque l’utilisateur appuie sur Ctrl+Espace. PowerShell utilise cette option uniquement pour l’affichage. Elle n’est pas passée à la commande quand elle est sélectionnée.
• resultType (CompletionResultType) : type de résultat d’achèvement.
• toolTip (String) : texte de l’info-bulle avec des détails à afficher sur l’objet. Cela est visible lorsque l’utilisateur sélectionne un élément après avoir appuyé sur Ctrl+Espace.

Exemple 3 : Inscrire un completer d’argument natif personnalisé

Vous pouvez utiliser le paramètre Natif pour fournir la saisie semi-automatique de tabulation pour une commande native. L’exemple suivant ajoute la saisie semi-automatique de tabulation pour l’interface dotnet de ligne de commande (CLI).

$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

La première commande crée un bloc de script qui accepte les paramètres requis, qui sont passés lorsque l’utilisateur appuie sur Tab. Pour plus d’informations, consultez la description du paramètre ScriptBlock .

Dans le bloc de script, la dotnet complete commande effectue l’achèvement de l’onglet. Les résultats sont redirigés vers l’applet ForEach-Object de commande, qui utilise la nouvelle méthode statique de la classe System.Management.Automation.CompletionResult pour créer un objet CompletionResult pour chaque valeur.

Paramètres

-CommandName

-Native

-ParameterName

-ScriptBlock

Entrées

None

Vous ne pouvez pas diriger les objets vers cette applet de commande.

Sorties

None

Cette applet de commande ne retourne pas de sortie.

Liens associés

• about_Functions_Argument_Completion