Register-ArgumentCompleter
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 dynamique de tabulation, 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 prend 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 de chaque fuseau horaire est redirigée vers l’applet de Where-Object
commande. L’applet Where-Object
de commande filtre tous les ID qui ne commencent pas par la valeur fournie par , qui représente le texte tapé par $wordToComplete
l’utilisateur avant d’appuyer sur Tab. Les ID filtrés sont dirigé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 d’onglet
L’exemple suivant remplace la saisie semi-automatique par 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 prend 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 dirigés vers l’applet de ForEach-Object
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 $_.Name
de 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 lorsqu’elle est sélectionnée.
- resultType (CompletionResultType) : type de résultat d’achèvement.
- toolTip (String) : texte de l’info-bulle avec les 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 Native pour fournir la saisie semi-automatique par tabulation d’une commande native. L’exemple suivant ajoute la saisie semi-automatique par tabulation pour l’interface dotnet
de ligne de commande (CLI).
Notes
La dotnet complete
commande est disponible uniquement dans les versions 2.0 et ultérieures 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 prend 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 dirigé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 en cours d’exécution. 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 enums, 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 par tabulation. Le bloc de script que vous fournissez doit retourner les valeurs qui terminent l’entrée. Le bloc de script doit dérouler les valeurs à l’aide du pipeline (ForEach-Object
, Where-Object
, etc.) ou d’une autre méthode appropriée. Si vous retournez un tableau de valeurs, PowerShell traite l’ensemble du tableau comme une valeur de saisie semi-automatique.
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 transmet 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 par tabulation.$parameterName
(Position 1) : ce paramètre est défini sur le paramètre dont la valeur nécessite la saisie semi-automatique par 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 de saisie semi-automatique de tabulation.$commandAst
(Position 3) : ce paramètre est défini sur l’arborescence de syntaxe abstraite (AST) pour 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 le$PSBoundParameters
pour l’applet 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 transmet 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 de saisie semi-automatique de tabulation.$commandAst
(Position 1) : ce paramètre est défini sur l’arborescence de syntaxe abstraite (AST) pour 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 rediriger des objets vers cette applet de commande.
Sorties
None
Cette applet de commande ne retourne pas de sortie.