about_Functions_Argument_Completion

Article
10/04/2023

Description courte

La saisie semi-automatique des arguments est une fonctionnalité de PowerShell qui fournit des indicateurs, active la découverte et accélère l’entrée d’entrée des valeurs d’argument.

Description longue

Cet article décrit les différentes façons dont vous pouvez implémenter des arguments complets pour les fonctions PowerShell. Les arguments complets fournissent les valeurs possibles pour un paramètre. Les valeurs disponibles sont calculées au moment de l’exécution lorsque l’utilisateur appuie sur la touche Tab après le nom du paramètre. Il existe plusieurs façons de définir un completer d’argument pour un paramètre.

Remarque

L’onglet est la liaison de touche par défaut sur Windows. Cette liaison de clés peut être modifiée par le module PSReadLine ou l’application qui héberge PowerShell. La liaison de clés est différente sur les plateformes autres que Windows. Pour plus d’informations, consultez about_PSReadLine.

Attribut ValidateSet

L’attribut ValidateSet spécifie un ensemble de valeurs valides pour un paramètre ou une variable et active la saisie semi-automatique de tabulation. PowerShell génère une erreur si un paramètre ou une valeur de variable ne correspond pas à une valeur dans l’ensemble. Dans l’exemple suivant, la valeur du paramètre Fruit peut uniquement être Apple, Banane ou Poire.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet('Apple', 'Banana', 'Pear')]
    [string[]]
    $Fruit
)

Dans l’exemple suivant, la valeur de la variable $flavor doit être chocolat, fraise ou vanille. L’attribut ValidateSet peut être utilisé sur n’importe quelle variable, pas seulement sur les paramètres.

[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'

La validation se produit chaque fois que cette variable est affectée même dans le script.

Param(
    [ValidateSet('hello', 'world')]
    [string]$Message
)

$Message = 'bye'

Cet exemple retourne l’erreur suivante au moment de l’exécution :

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

Pour plus d’informations sur l’expansion des onglets, consultez about_Tab_Expansion.

Valeurs ValidateSet dynamiques à l’aide de classes

Vous pouvez utiliser une classe pour générer dynamiquement les valeurs de ValidateSet au moment de l’exécution. Dans l’exemple suivant, les valeurs valides pour la variable $Sound sont générées via une classe nommée SoundNames qui vérifie trois chemins de système de fichiers pour les fichiers audio disponibles :

Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [string[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
                      '/Library/Sounds',
                      '~/Library/Sounds'
        $SoundNames = ForEach ($SoundPath in $SoundPaths) {
            If (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [string[]] $SoundNames
    }
}

La [SoundNames] classe est ensuite implémentée en tant que valeur ValidateSet dynamique comme suit :

Param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

Remarque

La IValidateSetValuesGenerator classe a été introduite dans PowerShell 6.0.

Attribut ArgumentCompletions

L’attribut ArgumentCompletions vous permet d’ajouter des valeurs d’achèvement de tabulation à un paramètre spécifique. Un attribut ArgumentCompletions doit être défini pour chaque paramètre qui a besoin de la saisie semi-automatique de tabulation. L’attribut ArgumentCompletions est similaire à ValidateSet. Les deux attributs prennent une liste de valeurs à présenter lorsque l’utilisateur appuie sur Tab après le nom du paramètre. Toutefois, contrairement à ValidateSet, les valeurs ne sont pas validées et plus comme des suggestions. Par conséquent, l’utilisateur peut fournir n’importe quelle valeur, pas seulement les valeurs de la liste.

L’attribut ArgumentCompletions ne doit pas être confondu avec l’attribut ArgumentCompleter , qui a besoin d’un scriptblock pour définir les options. les valeurs spécifiées sont disponibles

La syntaxe est la suivante :

function Test-ArgumentCompletions {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [ArgumentCompletions('Fruits', 'Vegetables')]
        $Type,

        [Parameter()]
        [ArgumentCompletions('Apple', 'Banana', 'Orange')]
        $Fruit,

        [Parameter()]
        [ArgumentCompletions('Onion', 'Carrot', 'Lettuce')]
        $Vegetable
    )
}

Chacun des paramètres est fourni une liste d’options à l’attribut ArgumentCompletions pour activer la saisie semi-automatique de tabulation.

Cet attribut a été introduit dans PowerShell 6.0.

Attribut ArgumentCompleter

L’attribut ArgumentCompleter vous permet d’ajouter des valeurs d’achèvement de tabulation à un paramètre spécifique. Un attribut ArgumentCompleter doit être défini pour chaque paramètre qui a besoin de la saisie semi-automatique de tabulation.

Pour ajouter un attribut ArgumentCompleter , vous devez définir un bloc de script qui détermine les valeurs. Le bloc de script doit prendre les paramètres suivants dans l’ordre spécifié ci-dessous. Les noms du paramètre n’ont pas d’importance, car les valeurs sont fournies positionnels.

La syntaxe est la suivante :

function MyArgumentCompleter {
    Param(
        [Parameter(Mandatory)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )
            # Perform calculation of tab completed values here.
        } )]
        $ParamName
    )
}

Bloc de script ArgumentCompleter

Les paramètres de bloc de script sont définis sur les valeurs suivantes :

$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 la documentation de type 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.

Le bloc de script ArgumentCompleter doit désinscrire les valeurs à l’aide du pipeline, par ForEach-Objectexemple, Where-Objectou 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 .

L’exemple suivant ajoute la saisie semi-automatique de tabulation au paramètre Value . Si seul le paramètre Value est spécifié, toutes les valeurs ou arguments possibles sont affichés pour Value . Lorsque le paramètre Type est spécifié, le paramètre Value affiche uniquement les valeurs possibles pour ce type.

En outre, l’opérateur -like garantit que si l’utilisateur tape la commande suivante et utilise la saisie semi-automatique tabulation , seul Apple est retourné.

Test-ArgumentCompleter -Type Fruits -Value A

function MyArgumentCompleter{
    param ( $commandName,
            $parameterName,
            $wordToComplete,
            $commandAst,
            $fakeBoundParameters )

    $possibleValues = @{
        Fruits = @('Apple', 'Orange', 'Banana')
        Vegetables = @('Onion', 'Carrot', 'Lettuce')
    }

    if ($fakeBoundParameters.ContainsKey('Type')) {
        $possibleValues[$fakeBoundParameters.Type] | Where-Object {
            $_ -like "$wordToComplete*"
        }
    } else {
        $possibleValues.Values | ForEach-Object {$_}
    }
}

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,

        [Parameter(Mandatory=$true)]
        [ArgumentCompleter({ MyArgumentCompleter @args })]
        $Value
      )
}

Complets d’arguments basés sur des classes

À compter de PowerShell 7.2, une nouvelle fonctionnalité a été ajoutée qui vous permet de définir des implémentations plus génériques des complets d’arguments paramétrables.

En dérivant de ArgumentCompleterAttribute, il est possible de créer des complets génériques qui peuvent être réutilisés, par exemple :

[DirectoryCompleter(ContainingFile="pwsh.exe", Depth=2)]

[DateCompleter(WeekDay='Monday', From="LastYear")]

[GitCommits(Branch='release')]

Les attributs dérivés doivent implémenter l’interface IArgumentCompleterFactory et utiliser des valeurs de propriété pour créer un completer spécialisé.

using namespace System.Collections
using namespace System.Collections.Generic
using namespace System.Management.Automation
using namespace System.Management.Automation.Language

class NumberCompleter : IArgumentCompleter {

    [int] $From
    [int] $To
    [int] $Step

    NumberCompleter([int] $from, [int] $to, [int] $step) {
        if ($from -gt $to) {
            throw [ArgumentOutOfRangeException]::new("from")
        }
        $this.From = $from
        $this.To = $to
        $this.Step = $step -lt 1 ? 1 : $step
    }

    [IEnumerable[CompletionResult]] CompleteArgument(
        [string] $CommandName,
        [string] $parameterName,
        [string] $wordToComplete,
        [CommandAst] $commandAst,
        [IDictionary] $fakeBoundParameters) {

        $resultList = [List[CompletionResult]]::new()
        $local:to = $this.To
        $local:step = $this.Step
        for ($i = $this.From; $i -lt $to; $i += $step) {
            $resultList.Add([CompletionResult]::new($i.ToString()))
        }

        return $resultList
    }
}

class NumberCompletionsAttribute : ArgumentCompleterAttribute, IArgumentCompleterFactory {
    [int] $From
    [int] $To
    [int] $Step

    NumberCompletionsAttribute([int] $from, [int] $to, [int] $step) {
        $this.From = $from
        $this.To = $to
        $this.Step = $step
    }

    [IArgumentCompleter] Create() { return [NumberCompleter]::new($this.From, $this.To, $this.Step) }
}

L’utilisation de PowerShell serait alors :

function Add{
    param(
       [NumberCompletions(0, 100, 5)]
       [int] $X,

       [NumberCompletions(0, 100, 5)]
       [int] $Y
    )
    $X + $Y
}

Register-ArgumentCompleter

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.

Pour plus d’informations, consultez Register-ArgumentCompleter.

Partager via