Register-ArgumentCompleter

  • Référence
Module:
Microsoft.PowerShell.Core

Inscrit un completer d’argument personnalisé.

Syntax

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.

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.

$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

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 qui place chaque valeur entre guillemets, si la valeur contient des espaces.

La deuxième commande inscrit l’argument completer en passant le scriptblock, l’ID ParameterName et le CommandNameSet-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,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
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. Cette option est utilisée uniquement pour l’affichage et 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.

La dernière commande montre que les services arrêtés peuvent toujours être transmis manuellement à l’applet de Stop-Service commande. La saisie semi-automatique de tabulation est le seul aspect affecté.

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).

Remarque

La dotnet complete commande est disponible uniquement dans la version 2.0 et supérieure de l’interface 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

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 est utilisée pour effectuer la saisie semi-automatique de tabulation. 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

Spécifie le nom des commandes sous forme de tableau.

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

-Native

Indique que l’argument completer est destiné à une commande native où PowerShell ne peut pas terminer les noms de paramètres.

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

-ParameterName

Spécifie le nom du paramètre dont l’argument est terminé. Le nom de paramètre spécifié ne peut pas être une valeur énumérée, telle que le paramètre ForegroundColor de l’applet Write-Host de commande.

Pour plus d’informations sur les énumérations, consultez about_Enum.

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

-ScriptBlock

Spécifie les commandes à exécuter pour effectuer la saisie semi-automatique de tabulation. Le bloc de script que vous fournissez doit retourner les valeurs qui terminent l’entrée. Le bloc de script doit désinscrire les valeurs à l’aide du pipeline (ForEach-Object, Where-Objectetc.) ou d’une autre méthode appropriée. Le renvoi d’un tableau de valeurs entraîne le traitement de PowerShell dans l’ensemble du tableau comme une valeur d’achèvement d’onglet .

Le bloc de script doit accepter les paramètres suivants dans l’ordre spécifié ci-dessous. Les noms des paramètres ne sont pas importants, car PowerShell passe les valeurs par position.

  • $commandName (Position 0) : ce paramètre est défini sur le nom de la commande pour laquelle le bloc de script fournit la saisie semi-automatique de tabulation.
  • $parameterName (Position 1) : ce paramètre est défini sur le paramètre dont la valeur nécessite l’achèvement de tabulation.
  • $wordToComplete (Position 2) : ce paramètre est défini sur la valeur fournie par l’utilisateur avant d’appuyer sur Tab. Votre bloc de script doit utiliser cette valeur pour déterminer les valeurs d’achèvement de tabulation.
  • $commandAst (Position 3) : ce paramètre est défini sur l’arborescence de syntaxe abstraite (AST) de la ligne d’entrée actuelle. Pour plus d’informations, consultez Classe Ast.
  • $fakeBoundParameters (Position 4) : ce paramètre est défini sur une table de hachage contenant l’applet $PSBoundParameters de commande, avant que l’utilisateur n’appuie sur Tab. Pour plus d’informations, consultez about_Automatic_Variables.

Lorsque vous spécifiez le paramètre natif , le bloc de script doit prendre les paramètres suivants dans l’ordre spécifié. Les noms des paramètres ne sont pas importants, car PowerShell passe les valeurs par position.

  • $wordToComplete (Position 0) : ce paramètre est défini sur la valeur fournie par l’utilisateur avant d’appuyer sur Tab. Votre bloc de script doit utiliser cette valeur pour déterminer les valeurs d’achèvement de tabulation.
  • $commandAst (Position 1) : ce paramètre est défini sur l’arborescence de syntaxe abstraite (AST) de la ligne d’entrée actuelle. Pour plus d’informations, consultez Classe Ast.
  • $cursorPosition (Position 2) : ce paramètre est défini sur la position du curseur lorsque l’utilisateur a appuyé sur Tab.

Vous pouvez également fournir un ArgumentCompleter en tant qu’attribut de paramètre. Pour plus d’informations, consultez about_Functions_Advanced_Parameters.

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

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.