about_Functions_Argument_Completion

  • Artikel

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 pada 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 harus Chocolate, Strawberry, atau Vanilla. $flavor 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 secara dinamis untuk ValidateSet 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 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 penting karena nilai disediakan secara posisional.

Sintaksisnya 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 membatalkan 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 atau argumen yang mungkin, 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 = @('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
      )
}

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