Register-ArgumentCompleter

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

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

La cmdlet Register-ArgumentCompleter enregistre un compléteur d'argument personnalisé. Un compléteur d'argument vous permet de fournir une complétion de tabulation dynamique, au moment de l'exécution, pour n'importe quelle commande que vous spécifiez.

L'exemple suivant enregistre un compléteur d'argument pour le paramètre ID de la cmdlet Set-TimeZone.

$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 commande Get-TimeZone. La propriété Id pour chaque fuseau horaire est redirigée vers l’applet de commande Where-Object. L’applet de commande Where-Object 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 de commande For-EachObject qui place chaque valeur entre guillemets, si la valeur contient des espaces.

La deuxième commande inscrit l’argument completer en transmettant le scriptblock, l'ParameterName « Id » et le CommandNameSet-TimeZone.

L'exemple suivant remplace la complétion par tabulation pour le paramètre Nom de la cmdlet Stop-Service et ne renvoie que les services en cours d'exécution.

$s = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
    $services = Get-Service | Where-Object {$_.Status -eq "Running" }
    $services | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_,
            $_,
            "ParameterValue",
            $_
    }
}
Register-ArgumentCompleter -CommandName dotnet -Native -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 commande Where-Object. Les services sont redirigés vers l’applet de commande ForEach-Object. L’applet de commande ForEach-Object crée un objet [System.Management.Automation.CompletionResult] et le remplit avec les valeurs du service actuel (représentée par la variable de pipeline $_).

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

• completionText (Chaîne) - Le texte à utiliser comme résultat de l'auto-complétion. 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>+<Space>. 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) - Le type de résultat de l'achèvement.
• info-bulle (chaîne) : 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>+<Space>.

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

Vous pouvez utiliser le paramètre Native pour compléter la tabulation d'une commande native. L'exemple suivant ajoute une complétion de tabulation pour l'interface de ligne de commande (CLI) dotnet.

$scriptblock = {
     param($commandName, $wordToComplete, $cursorPosition)
         dotnet complete --position $cursorPosition "$wordToComplete" | 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 commande dotnet complete est utilisée pour effectuer la saisie semi-automatique de tabulation. Les résultats sont redirigés vers l’applet de commande ForEach-Object qui utilise la méthode statique nouvelle de la classe [System.Management.Automation.CompletionResult] pour créer un objet CompletionResult pour chaque valeur.

Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.

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

Cette applet de commande ne retourne aucune sortie.