about_Functions_Argument_Completion

Cikk
10/04/2023

Rövid leírás

Az argumentumkiegészítés a PowerShell egyik funkciója, amely tippeket ad, lehetővé teszi a felderítést, és felgyorsítja az argumentumértékek bevitelét.

Hosszú leírás

Ez a cikk a PowerShell-függvények argumentum-kiegészítéseinek különböző implementálási módjait ismerteti. Az argumentum-befejezők egy paraméter lehetséges értékeit adják meg. Az elérhető értékek futásidőben lesznek kiszámítva, amikor a felhasználó lenyomja a Tab billentyűt a paraméter neve után. Egy paraméter argumentum-befejezője többféleképpen is definiálható.

Feljegyzés

A Tab a Windows alapértelmezett kulcskötése. Ezt a kulcskötést a PSReadLine modul vagy a PowerShellt üzemeltető alkalmazás módosíthatja. A kulcskötés nem Windows-platformokon eltérő. További információ: about_PSReadLine.

ValidateSet attribútum

A ValidateSet attribútum egy paraméter vagy változó érvényes értékeinek készletét adja meg, és engedélyezi a lapkizárást. A PowerShell hibát okoz, ha egy paraméter vagy változó értéke nem egyezik meg a készlet egyik értékével. Az alábbi példában a Fruit paraméter értéke csak apple, banán vagy körte lehet.

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

A következő példában a változó $flavor értékének Csokoládé, Eper vagy Vanilla értéknek kell lennie. Az ValidateSet attribútum bármely változóhoz használható, nem csak paraméterekhez.

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

Az ellenőrzés akkor történik, ha a változót még a szkripten belül is hozzárendelik.

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

$Message = 'bye'

Ez a példa a következő hibát adja vissza futásidőben:

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

További információ a lapbővítésről: about_Tab_Expansion.

Dynamic ValidateSet értékek osztályok használatával

Osztály használatával dinamikusan hozhatja létre a ValidateSet értékeit futásidőben. Az alábbi példában a változó $Sound érvényes értékei egy SoundNames nevű osztályon keresztül jönnek létre, amely három fájlrendszer elérési útját ellenőrzi az elérhető hangfájlok esetében:

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
    }
}

Az [SoundNames] osztály ezután dinamikus ValidateSet-értékként lesz implementálva az alábbiak szerint:

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

Feljegyzés

Az IValidateSetValuesGenerator osztály a PowerShell 6.0-ban lett bevezetve.

ArgumentCompletions attribútum

Az ArgumentCompletions attribútum lehetővé teszi lapkiegészítési értékek hozzáadását egy adott paraméterhez. Minden olyan paraméterhez meg kell határozni egy Argumentumkiegészítés attribútumot, amely lapkiegészítést igényel. Az ArgumentCompletions attribútum a ValidateSethez hasonló. Mindkét attribútum tartalmazza a megjelenítendő értékek listáját, amikor a felhasználó lenyomja a Tab billentyűt a paraméter neve után. A ValidateSettől eltérően azonban a rendszer nem érvényesíti az értékeket, és inkább a javaslatokat. Ezért a felhasználó bármilyen értéket megadhat, nem csak a listában szereplő értékeket.

Az ArgumentCompletions attribútum nem tévesztendő össze az ArgumentCompleter attribútummal, amelynek szkriptblokkra van szüksége a beállítások definiálásához. a megadott értékek elérhetők

A szintaxis a következő:

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

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

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

Az egyes paraméterek az Argumentumkiegészítés attribútum beállításainak listáját biztosítják a lap befejezésének engedélyezéséhez.

Ez az attribútum a PowerShell 6.0-ban lett bevezetve.

ArgumentCompleter attribútum

Az ArgumentCompleter attribútum lehetővé teszi lapkiegészítési értékek hozzáadását egy adott paraméterhez. Minden olyan paraméterhez meg kell határozni egy ArgumentCompleter attribútumot, amely lapkimenetet igényel.

Az ArgumentCompleter attribútum hozzáadásához definiálnia kell egy szkriptblokkot, amely meghatározza az értékeket. A szkriptblokknak az alábbi paramétereket kell figyelembe vennie az alább megadott sorrendben. A paraméter neve nem számít, mivel az értékek pozícióban vannak megadva.

A szintaxis a következő:

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

Argumentumkiegészítő szkriptblokkja

A szkriptblokk paraméterei a következő értékekre vannak beállítva:

$commandName (0. pozíció) – Ez a paraméter annak a parancsnak a nevére van beállítva, amelyhez a szkriptblokk lapkiegészítést biztosít.
$parameterName (1. pozíció) – Ez a paraméter arra a paraméterre van beállítva, amelynek értéke lapkiegészítést igényel.
$wordToComplete(2. pozíció) – Ez a paraméter úgy van beállítva, hogy a felhasználó a Tab billentyű lenyomása előtt megadott értéket adja meg. A szkriptblokknak ezt az értéket kell használnia a lapkiegészítési értékek meghatározásához.
$commandAst (3. pozíció) – Ez a paraméter az aktuális bemeneti sor absztrakt szintaxisfára (AST) van állítva. További információkért tekintse meg az AST-típus dokumentációját.
$fakeBoundParameters(4. pozíció) – Ez a paraméter egy kivonatolóra van állítva, amely tartalmazza a $PSBoundParameters parancsmagot, mielőtt a felhasználó lenyomta a Tab billentyűt. További információ: about_Automatic_Variables.

Az ArgumentCompleter szkriptblokknak fel kell vennie az értékek regisztrációját a folyamat használatával, például ForEach-Object, Where-Objectvagy egy másik megfelelő módszerrel. Ha értéktömböt ad vissza, a PowerShell a teljes tömböt egyetlen lapkiegészítési értékként kezeli.

Az alábbi példa tabulátorkiegészítést ad hozzá az Érték paraméterhez. Ha csak az Érték paraméter van megadva, az érték összes lehetséges értéke vagy argumentuma megjelenik. A Típus paraméter megadásakor az Érték paraméter csak az adott típus lehetséges értékeit jeleníti meg.

Emellett az -like operátor biztosítja, hogy ha a felhasználó begépeli a következő parancsot, és tabulátorkiegészítést használ, csak az Apple lesz visszaadva.

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

Osztályalapú argumentum-kiegészítések

A PowerShell 7.2-től kezdve egy új funkció lett hozzáadva, amely lehetővé teszi a paraméteres argumentum-befejezők általánosabb implementációinak definiálását.

A forrásból ArgumentCompleterAttributekiindulva létrehozhat általános befejezőket, amelyek újra felhasználhatók, például:

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

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

[GitCommits(Branch='release')]

A származtatott attribútumoknak implementálniuk kell az IArgumentCompleterFactory interfészt, és tulajdonságértékeket kell használniuk egy speciális befejező létrehozásához.

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

A PowerShell használata ezután a következő lesz:

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

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

Register-ArgumentCompleter

A Register-ArgumentCompleter parancsmag regisztrál egy egyéni argumentum-befejezőt. Az argumentumkiegészítő lehetővé teszi a dinamikus lapkiegészítést a megadott parancsok futásidejű futtatásához.

További információ: Register-ArgumentCompleter.

Megosztás a következőn keresztül: