about_Functions_Argument_Completion

Deskripsi singkat

Penyelesaian argumen adalah fitur PowerShell yang menyediakan petunjuk, memungkinkan penemuan, dan mempercepat entri input nilai argumen.

Deskripsi panjang

Artikel ini menjelaskan berbagai cara untuk menerapkan penyelesaian argumen untuk fungsi PowerShell. Penyelesaian argumen menyediakan nilai yang mungkin untuk parameter. Nilai yang tersedia dihitung pada runtime saat pengguna menekan tombol Tab setelah nama parameter. Ada beberapa cara untuk menentukan penyelesaian argumen untuk parameter.

Catatan

Tab adalah pengikatan kunci default di Windows. Keybinding ini dapat diubah oleh modul PSReadLine atau aplikasi yang menghosting PowerShell. Keybinding berbeda pada platform non-Windows. Untuk informasi selengkapnya, lihat about_PSReadLine.

Atribut ValidateSet

Atribut ValidateSet menentukan sekumpulan nilai yang valid untuk parameter atau variabel dan mengaktifkan penyelesaian tab. PowerShell menghasilkan kesalahan jika parameter atau nilai variabel tidak cocok dengan nilai dalam set. Dalam contoh berikut, nilai parameter Buah hanya dapat berupa Apel, Pisang, atau Pir.

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

Dalam contoh berikut, nilai variabel $flavor harus Chocolate, Strawberry, atau Vanilla. Atribut ValidateSet dapat digunakan pada variabel apa pun, bukan hanya parameter.

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

Validasi terjadi setiap kali variabel tersebut ditetapkan bahkan dalam skrip.

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

$Message = 'bye'

Contoh ini mengembalikan kesalahan berikut saat runtime:

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

Untuk informasi selengkapnya tentang perluasan tab, lihat about_Tab_Expansion.

Nilai ValidateSet Dinamis menggunakan kelas

Anda dapat menggunakan Kelas untuk menghasilkan nilai untuk ValidateSet secara dinamis saat runtime. Dalam contoh berikut, nilai yang valid untuk variabel $Sound dihasilkan melalui Kelas bernama SoundNames yang memeriksa tiga jalur sistem file untuk file suara yang tersedia:

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

Kelas [SoundNames] kemudian diimplementasikan sebagai nilai ValidateSet dinamis sebagai berikut:

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

Catatan

Kelas IValidateSetValuesGenerator ini diperkenalkan di PowerShell 6.0.

Atribut ArgumentCompletions

Atribut ArgumentCompletions memungkinkan Anda menambahkan nilai penyelesaian tab ke parameter tertentu. Atribut ArgumentCompletions harus ditentukan untuk setiap parameter yang memerlukan penyelesaian tab. Atribut ArgumentCompletions mirip dengan ValidateSet. Kedua atribut mengambil daftar nilai yang akan disajikan saat pengguna menekan Tab setelah nama parameter. Namun, tidak seperti ValidateSet, nilai tidak divalidasi dan lebih seperti saran. Oleh karena itu pengguna dapat memberikan nilai apa pun, bukan hanya nilai dalam daftar.

Atribut ArgumentCompletions tidak boleh dikacaukan dengan atribut ArgumentCompleter , yang memerlukan blok skrip untuk menentukan opsi. nilai yang ditentukan tersedia

Sintaksnya adalah sebagai berikut:

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

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

        [Parameter()]
        [ArgumentCompletions('Tomato', 'Corn', 'Squash')]
        $Vegetable
    )
}

Setiap parameter disediakan daftar opsi ke atribut ArgumentCompletions untuk mengaktifkan penyelesaian tab.

Atribut ini diperkenalkan di PowerShell 6.0.

Atribut ArgumentCompleter

Atribut ArgumentCompleter memungkinkan Anda menambahkan nilai penyelesaian tab ke parameter tertentu. Atribut ArgumentCompleter harus ditentukan untuk setiap parameter yang memerlukan penyelesaian tab.

Untuk menambahkan atribut ArgumentCompleter , Anda perlu menentukan blok skrip yang menentukan nilai. Blok skrip harus mengambil parameter berikut dalam urutan yang ditentukan di bawah ini. Nama parameter tidak masalah karena nilai disediakan secara posisional.

Sintaksnya adalah sebagai berikut:

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

Blok skrip ArgumentCompleter

Parameter blok skrip diatur ke nilai berikut:

  • $commandName (Posisi 0) - Parameter ini diatur ke nama perintah tempat blok skrip menyediakan penyelesaian tab.
  • $parameterName (Posisi 1) - Parameter ini diatur ke parameter yang nilainya memerlukan penyelesaian tab.
  • $wordToComplete (Posisi 2) - Parameter ini diatur ke nilai yang telah disediakan pengguna sebelum mereka menekan Tab. Blok skrip Anda harus menggunakan nilai ini untuk menentukan nilai penyelesaian tab.
  • $commandAst (Posisi 3) - Parameter ini diatur ke Pohon Sintaks Abstrak (AST) untuk baris input saat ini. Untuk informasi selengkapnya, lihat dokumentasi jenis AST .
  • $fakeBoundParameters (Posisi 4) - Parameter ini diatur ke hashtable yang berisi $PSBoundParameters untuk cmdlet, sebelum pengguna menekan Tab. Untuk informasi selengkapnya, lihat about_Automatic_Variables.

Blok skrip ArgumentCompleter harus membuka pendaftaran nilai menggunakan alur, seperti ForEach-Object, Where-Object, atau metode lain yang sesuai. Mengembalikan array nilai menyebabkan PowerShell memperlakukan seluruh array sebagai nilai penyelesaian satu tab.

Contoh berikut menambahkan penyelesaian tab ke parameter Nilai . Jika hanya parameter Nilai yang ditentukan, semua nilai yang mungkin, atau argumen, untuk Nilai ditampilkan. Saat parameter Jenis ditentukan, parameter Nilai hanya menampilkan nilai yang mungkin untuk jenis tersebut.

Selain itu, -like operator memastikan bahwa jika pengguna mengetik perintah berikut dan menggunakan penyelesaian Tab , hanya Apple yang dikembalikan.

Test-ArgumentCompleter -Type Fruits -Value A

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

    $possibleValues = @{
        Fruits = @('Apple', 'Orange', 'Banana')
        Vegetables = @('Tomato', 'Squash', 'Corn')
    }

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

Penyelesaian argumen berbasis kelas

Dimulai di PowerShell 7.2, fitur baru ditambahkan yang memungkinkan Anda menentukan implementasi yang lebih umum dari penyelesaian argumen berparameter.

Dengan berasal dari ArgumentCompleterAttribute, dimungkinkan untuk membuat penyelesaian generik yang dapat digunakan kembali, misalnya:

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

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

[GitCommits(Branch='release')]

Atribut turunan harus mengimplementasikan IArgumentCompleterFactory antarmuka dan menggunakan nilai properti untuk membuat penyelesaian khusus.

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

Penggunaan dari PowerShell kemudian akan menjadi:

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

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

Register-ArgumentCompleter

Register-ArgumentCompleter Cmdlet mendaftarkan penyelesaian argumen kustom. Pelengkap argumen memungkinkan Anda menyediakan penyelesaian tab dinamis, pada waktu proses untuk perintah apa pun yang Anda tentukan.

Untuk informasi selengkapnya, lihat Register-ArgumentCompleter.

Lihat juga