Cara menggunakan ArgumentCompleter dan Register-ArgumentCompleter di PowerShell

Pada bagian berikut, kita akan melihat dengan tenang dan dengan contoh yang jelas, bagaimana cara menggunakan Register-ArgumentCompleter, atribut ArgumentCompletion, ArgumentCompletions, dan ValidateSet, serta kelas kustom. untuk mencapai pengalaman pelengkapan otomatis yang sangat canggih di PowerShell. Anda akan melihat kasus-kasus sederhana dan skenario yang jauh lebih kompleks, termasuk cara mengintegrasikannya ke dalam skrip Anda. Profil PowerShell agar selalu aktif dan cara menggunakannya juga dengan perintah bawaan seperti dotnet atau CLI pihak ketiga.

Apa itu Register-ArgumentCompleter dan masalah apa yang dipecahkannya?

Cmdletnya Register-ArgumentCompleter berfungsi untuk mendaftarkan pelengkap argumen khususDengan kata lain, Anda memberi tahu PowerShell apa yang harus disarankan saat pengguna menekan tombol tersebut. Tab saat mengisi nilai parameter atau perintah bawaan.

Pelengkap ini berjalan pada waktu eksekusiJadi Anda dapat menghitung saran secara dinamis: cari cmdlet seperti Get-TimeZonelayanan filter dengan Get-Service, panggil CLI sebagai dotnet completeMembaca API REST, memeriksa sistem file, dan lain sebagainya, semuanya dilakukan melalui... Blok Skrip yang mengembalikan nilai-nilai pelengkapan otomatis yang mungkin.

Detail penting lainnya adalah bagaimana parameter tersebut berperilaku. Nama Perintah: jika Anda menggunakannya tanpa menunjukkannya Nama Parameter ni AsliPowerShell memperlakukan panggilan tersebut seolah-olah Anda telah menambahkan sesuatu. -Warga asliIni berarti bahwa fitur pelengkap tidak akan berfungsi pada parameter cmdlet PowerShell, tetapi hanya sebagai pelengkap untuk perintah asli. Oleh karena itu, jika tujuan Anda adalah untuk melengkapi parameter untuk cmdlet atau fungsi PowerShell, Anda harus selalu tentukan ParameterName.

Sintaks dasar Register-ArgumentCompleter

Kumpulan parameter untuk perintah asli (NativeSet)

Untuk mendaftarkan pelengkap argumen untuk perintah asli, sintaks berikut digunakan, di mana kuncinya ada di dalam pengubah. -Warga asli:

Sintaks umum: Register-ArgumentCompleter -CommandName <String[]> -ScriptBlock <ScriptBlock> -Native

Dalam hal ini CommandName wajib diisi.karena PowerShell perlu mengetahui perintah asli mana yang akan dikaitkan dengan fitur pelengkap perintah. Blok Skrip Ia akan menerima serangkaian parameter yang berbeda dari pelengkap cmdlet PowerShell, seperti yang akan kita lihat nanti, dan akan diarahkan untuk menginterpretasikan seluruh baris dan posisi kursor.

Kumpulan parameter cmdlet PowerShell (PowerShellSet)

Jika Anda ingin menambahkan fitur pelengkapan otomatis ke satu atau lebih parameter cmdlet atau fungsi PowerShell, sintaks yang paling umum adalah:

Sintaks umum: Register-ArgumentCompleter -ParameterName <String> -ScriptBlock <ScriptBlock> >]

Di sini ParameterName wajib diisi. dan menentukan parameter mana yang akan diterapkan penyelesaiannya. Parameter tersebut CommandName bersifat opsional.Anda dapat membatasi fungsi pelengkap otomatis (completer) hanya untuk satu atau lebih perintah tertentu, atau jika Anda menghilangkannya, PowerShell akan mendaftarkan fungsi pelengkap otomatis tersebut untuk nama parameter tersebut di semua perintah yang memilikinya.

Parameter-parameter kunci dari Register-ArgumentCompleter

Parameter -NamaPerintah

Parameter -NamaPerintah Menunjukkan perintah mana yang akan didaftarkan untuk penyelesai. Menerima satu nilai. susunan stringOleh karena itu, Anda dapat mengaitkan ScriptBlock yang sama dengan beberapa cmdlet atau alat bawaan secara bersamaan.

Saat digunakan dalam kumpulan parameter NativeSetAdalah wajibkarena pelengkap bawaan tidak dapat didaftarkan secara generik tanpa menunjuk ke biner atau perintah tertentu. Dalam himpunan PowerShellSet Ini opsional, tetapi, seperti yang disebutkan sebelumnya, jika Anda menggunakannya tanpa Nama Parameter ni AsliPowerShell akan menginterpretasikan bahwa Anda sedang membuat pelengkap otomatis (completer) bawaan.

Parameter -Asli

Pengubah -Warga asli memberi tahu PowerShell bahwa pelengkap harus diterapkan ke perintah asliArtinya, file eksekusi eksternal di mana PowerShell tidak mengontrol atau tidak dapat melengkapi nama parameter. Mari kita pertimbangkan dotnet, winget, aws atau CLI berbasis .NET lainnya, Ular sanca atau serupa.

Dalam mode ini, ScriptBlock menerima lebih sedikit parameter dan untuk tujuan yang berbeda: teks yang telah ditulis, AST dari perintah, dan posisi kursorDari situ, biasanya naskah Ia memanggil CLI itu sendiri untuk mengembalikan saran, seperti yang terjadi pada dotnet complete.

Parameter -NamaParameter

Parameter -NamaParameter Menentukan nama parameter yang akan diterapkan penyelesaian argumen. Ada satu batasan penting: tipe parameter tersebut. Ini tidak bisa berupa daftar.Misalnya, jika parameter menggunakan tipe seperti Warna Depan de Write-HostAnda tidak dapat menggunakan Register-ArgumentCompleter untuk menyelesaikannya.

Saat mendaftarkan pelengkap untuk cmdlet atau fungsi PowerShell, sangat disarankan agar selalu gunakan ParameterNameJika Anda lupa dan hanya menggunakan CommandName, Anda akan secara tidak sengaja mendaftarkan pelengkap bawaan dan tidak akan melihat saran untuk parameter yang Anda minati.

Parameter -ScriptBlock

Inti dari setiap orang yang berhasil menyelesaikan tugasnya adalah... Blok SkripBlok skrip ini mendefinisikan logika yang menghasilkan nilai-nilai yang akan disarankan saat pengguna menekan tombol. TabYang paling penting adalah ScriptBlock harus mengembalikan elemen-elemen melalui pipelineMisalnya, dengan ForEach-Object o Where-Object, alih-alih mengembalikan array tunggal, karena jika array yang tidak dipipelin dikembalikan, PowerShell akan menginterpretasikannya sebagai nilai pelengkapan otomatis tunggal.

Selain itu, ScriptBlock dapat langsung mengembalikan string atau objek bertipe System.Management.Automation.CompletionResultIni menawarkan fleksibilitas yang jauh lebih besar, karena memungkinkan Anda untuk menentukan teks yang akan diisi, teks yang ditampilkan dalam daftar, jenis hasil, dan deskripsi atau tooltip.

Parameter ScriptBlock untuk pelengkap PowerShell

Pada pengisi normal (non-asli), ScriptBlock harus menerima lima parameter dalam urutan ini, terlepas dari nama mereka:

• Nama perintah: string yang berisi nama perintah yang penyelesaiannya sedang dihitung.
• Nama parameter: string yang berisi nama parameter yang sedang diselesaikan.
• $kataYangAkanSelesai: string yang berisi apa yang diketik pengguna tepat sebelum menekan Tab.
• perintahAst: Objek CommandAst yang mewakili pohon sintaks abstrak dari jalur saat ini.
• Parameter Terikat Palsu: tipe kamus Kamus yang mereplikasi konten dari $PSBoundParameters pada saat mendesak Tab.

Parameter $kataYangAkanSelesai Ini sering digunakan untuk menyaring nilai dengan operator seperti -likesehingga hanya item yang diawali dengan apa yang telah diketik pengguna yang disarankan. Sementara itu, Parameter Terikat Palsu Ini memungkinkan Anda untuk membuat bahan pengisi yang bergantung pada parameter lain, seperti yang akan kita lihat dengan contoh buah-buahan dan sayuran.

Parameter ScriptBlock untuk pengisi bawaan

Kapan digunakan? -Warga asliScriptBlock menerima tiga parameter, juga berdasarkan posisi:

• $kataYangAkanSelesai (posisi 0): teks yang telah diketik pengguna sebelum tombol ditekan Tab.
• perintahAst (posisi 1): pohon sintaks dari perintah lengkap, bukan hanya argumen saat ini.
• Posisi kursor (posisi 2): indeks posisi kursor pada baris.

Format ini sangat cocok dengan CLI yang sudah menyediakan sistem pelengkapan otomatisnya sendiri. Contoh kasus tipikalnya adalah... dotnet complete, yang menerima posisi baris dan kursor dan mengembalikan saran teks biasa yang kemudian diubah menjadi Hasil Penyelesaian.

Contoh praktis dengan Register-ArgumentCompleter

Contoh 1: Mengisi zona waktu secara dinamis

Bayangkan Anda ingin membuat penggunaan cmdlet semudah mungkin. Set-TimeZone memungkinkan pengguna untuk melengkapi parameter Id dengan tombol Tab. Anda dapat membuat ScriptBlock yang mengambil semua zona waktu dengan Get-TimeZone -ListAvailableSaring berdasarkan apa yang diketik pengguna dan sertakan setiap nilai dalam tanda kutip jika terdapat spasi:

Contoh skrip 1: $script = {<br> param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)<br> (Get-TimeZone -ListAvailable).Id |<br> Where-Object { $_ -like "$wordToComplete*" } |<br> ForEach-Object { "'$_'" }<br>}<br>Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $script

Dengan ini, ketika Anda menulis Set-TimeZone -Id dan mulailah mengetik, saat Anda menekan Tab kamu akan memilikinya Daftar ID zona waktu yang difilter Berdasarkan apa yang telah Anda tulis. Tanda kutip tunggal ditambahkan untuk menghindari masalah dengan pengidentifikasi yang mengandung spasi.

Contoh 2: Saran yang diperkaya dengan CompletionResult

Dalam skenario kedua, Anda menginginkan hal itu saat menggunakan Stop-Service -Name hanya muncul layanan yang sedang berlangsungdan Anda juga ingin menampilkan informasi tambahan di daftar saran saat pengguna menekan Ctrl+ruang.

Contoh skrip 2 (CompletionResult): $script = {<br> param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)<br> $services = Get-Service | Where-Object {<br> $_.Status -eq 'Running' -and $_.Name -like "$wordToComplete*"<br> }<br> $services | ForEach-Object {<br> New-Object -TypeName System.Management.Automation.CompletionResult -ArgumentList @(<br> $_.Name, # completionText<br> $_.Name, # listItemText<br> 'ParameterValue', # resultType<br> $_.Name # toolTip<br> )<br> }<br>}<br>Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $script

Perhatikan kolom-kolom berikut: Di setiap objek CompletionResult, Anda dapat mengontrol bidang-bidang utama ini untuk pengalaman yang lebih baik:

• Teks penyelesaian: teks yang sebenarnya dimasukkan ke dalam perintah saat Anda memilih saran tersebut.
• listItemText: teks yang ditampilkan dalam daftar proposal; mungkin berbeda dari string yang dimasukkan.
• tipe hasil: jenis hasil (misalnya, ParameterValue).
• Petunjuk alat: deskripsi yang muncul saat Anda memilih item dalam daftar yang sudah selesai, sangat berguna terutama untuk Ctrl+ruang.

Contoh 3: Pelengkap bawaan untuk CLI dotnet

Anda juga dapat menggunakan Register-ArgumentCompleter untuk memperluas fitur pelengkapan otomatis. alat asliContoh klasiknya adalah dotnet, yang mencakup subperintah dotnet complete untuk mengembalikan item yang telah selesai berdasarkan baris saat ini.

Contoh skrip asli: $scriptblock = {<br> param($wordToComplete, $commandAst, $cursorPosition)<br> dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {<br> ::new(<br> $_, # completionText<br> $_, # listItemText<br> 'ParameterValue', # resultType<br> $_ # toolTip<br> )<br> }<br>}<br>Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

Dalam contoh ini, perintah itu sendiri dotnet complete Ini adalah bagian yang melakukan perhitungan saran. ScriptBlock hanya mengubah output menjadi objek CompletionResult. Dengan cara ini Anda mencapai hasil yang diinginkan. Integrasi yang sangat lancar antara PowerShell dan CLI eksternal., dengan tab yang mengetahui semua opsi dotnet bawaan.

Cara lain untuk mengimplementasikan pelengkap argumen

ValidateSet: nilai tetap dengan validasi ketat

Atribut ValidateSet Fitur ini menawarkan cara sederhana untuk membatasi parameter atau variabel ke serangkaian nilai tertutup dan, pada saat yang sama, mengaktifkan penyelesaian otomatis (Tab completion) tanpa harus menulis ScriptBlock khusus.

Bayangkan sebuah parameter. Buah yang hanya menerima "Apple", "Banana", atau "Pear". Anda bisa mendefinisikannya seperti ini:

Contoh definisi: param (<br> <br> <br> ]$Fruit<br>)

Jika pengguna memasukkan nilai yang tidak ada dalam himpunan, PowerShell akan melempar pengecualian. kesalahan validasiHal yang sama berlaku untuk variabel saat ini, bukan hanya parameter, misalnya:

Deklarasi variabel: <br>$Flavor = 'Strawberry'

Setiap kali sesuatu ditugaskan kepada $FlavorSkrip akan memeriksa apakah nilai tersebut termasuk dalam himpunan. Jika di titik mana pun dalam skrip Anda melakukan hal berikut:

param(<br> <br> $Message<br>)<br>$Message = 'bye'

PowerShell akan mengembalikan kesalahan bertipe Kesalahan Metadata, yang menunjukkan bahwa variabel tersebut akan kehilangan validitasnya jika nilai tersebut diterapkan, yang membantu menjaga kontrak ketat dalam naskah Anda.

ValidateSet dinamis dengan kelas

Selain himpunan statis, PowerShell memungkinkan pembuatan nilai dari ValidateSet secara dinamis menggunakan kelas. yang mengimplementasikan antarmuka System.Management.Automation.IValidateSetValuesGeneratorDalam model ini, kelas tersebut mengekspos sebuah metode. GetValidValues() yang mengembalikan opsi-opsi yang mungkin.

Contoh tipikalnya adalah kelas Nama Suara, yang memindai beberapa folder sistem untuk mencari file suara dan mengembalikan nama dasarnya sebagai nilai yang valid:

Contoh kelas (SoundNames): class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {<br> ] GetValidValues() {<br> $SoundPaths = '/System/Library/Sounds/', '/Library/Sounds', '~/Library/Sounds'<br> $SoundNames = foreach ($SoundPath in $SoundPaths) {<br> if (Test-Path $SoundPath) {<br> (Get-ChildItem $SoundPath).BaseName<br> }<br> }<br> return ] $SoundNames<br> }<br>}

Kemudian Anda mengimplementasikan kelas tersebut sebagai sebuah ValidateSet Dinamis dalam sebuah parameter atau variabel:

Menggunakan ValidateSet dinamis: param (<br> )]<br> $Sound<br>)

Inilah cara Anda mendapatkan tampilan lengkap dengan tab yang mencerminkan keadaan sebenarnya dari sistem file setiap kali skrip dieksekusi.

ArgumentCompletions: saran tanpa memvalidasi nilainya

Atribut Penyelesaian Argumen Ini memungkinkan Anda untuk menambahkan daftar nilai yang disarankan ke suatu parameter, tetapi tidak seperti ValidateSet, Validasi ketat tidak dilakukanArtinya, pengguna dapat memilih salah satu saran atau menulis hal lain, meskipun tidak ada dalam daftar.

Sintaksnya sangat mudah dipahami. Misalnya, Anda dapat mendefinisikan fungsi dengan satu parameter. Tipe yang menunjukkan "Buah-buahan" dan "Sayuran", dan parameter. Buah y Sayuran dengan daftar nilai yang mungkin:

Definisi fungsi: function Test-ArgumentCompletions {<br> <br> param (<br> <br> <br> $Type,<br;<br> <br> <br> $Fruit,<br;<br> <br> <br> $Vegetable<br> )<br>}

Atribut ini sangat cocok ketika Anda menginginkan Membimbing pengguna dengan contoh. dengan nilai-nilai umum, tetapi Anda tidak ingin mencegahnya memasukkan nilai-nilai berbeda lainnya karena persyaratan bisnis atau kompatibilitas dengan kasus-kasus khusus.

ArgumentCompleter: pelengkap tingkat atribut parameter

Atribut Pelengkap Argumen Ini digunakan untuk melampirkan ScriptBlock ke parameter dengan tanda tangan yang sama dengan completer yang terdaftar di Register-ArgumentCompletertetapi tanpa perlu memanggil cmdlet ini. Ini adalah cara elegan untuk merangkum logika pelengkapan otomatis yang kompleks langsung dalam definisi fungsi.

Contoh dasar: Contoh penggunaannya adalah:

Contoh atribut: function MyArgumentCompleter {<br> param (<br> <br> <br> $ParamName<br> )<br>}

Sama seperti Register-ArgumentCompleter, ScriptBlock harus mengembalikan nilai melalui pipeline, dan dapat memanfaatkan keduanya. $kataYangAkanSelesai sebagai Parameter Terikat Palsu atau bahkan menganalisis AST untuk mempertimbangkan konteks lengkap dari perintah tersebut.

Contoh lanjutan dari ArgumentCompleter yang bergantung pada parameter lain.

Pola yang sangat berguna melibatkan pembuatan fungsi lengkap yang bergantung pada nilai parameter lain. Bayangkan sebuah fungsi dengan sebuah parameter. Tipe yang bisa berupa "Buah-buahan" atau "Sayuran", dan sebuah parameter. Nilai yang rangkaian sarannya berubah tergantung pada jenis yang dipilih.

Implementasi mesin: function MyArgumentCompleter {<br> param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)<br><br> $possibleValues = @{<br> Fruits = @('Apple','Orange','Banana')<br> Vegetables = @('Onion','Carrot','Lettuce')<br> }<br><br>> if ($fakeBoundParameters.ContainsKey('Type')) {<br> $possibleValues |<br> Where-Object { $_ -like "$wordToComplete*" }<br> } else {<br> $possibleValues.Values | ForEach-Object { $_ }<br> }<br>}

Konsumsi bahan pengisi: function Test-ArgumentCompleter {<br> <br> param (<br> <br> <br> $Type,<br;<br> <br> <br> $Value<br> )<br>}

Dalam skenario ini, jika Anda menulis, misalnya Test-ArgumentCompleter -Type Fruits -Value A dan Anda menekan Tab, berkat penggunaan -seperti dan dari kamus Parameter Terikat PalsuPengisi hanya akan mengembalikan nilai buah yang diawali dengan huruf "A", yaitu, AppleIni adalah teknik yang sangat ampuh untuk membangun. antarmuka baris perintah yang ramah pengguna bahkan ketika dihadapkan dengan data yang tidak sepele.

Pelengkap argumen berbasis kelas (dimulai dari PowerShell 7.2)

Mulai dari PowerShell 7.2, sebuah fitur ditambahkan yang memungkinkan Anda untuk mendefinisikan pengisi yang dapat digunakan kembali berdasarkan kelasHal ini sangat mempermudah pembuatan filler yang dapat diparameterisasi dan bersifat generik.

Idenya adalah untuk mengambil dari Atribut Pelengkap Argumen dan mengimplementasikan antarmuka tersebut IArgumentCompleterFactoryKelas turunan dapat memiliki properti yang dapat dikonfigurasi (misalnya, rentang numerik, kedalaman direktori, tanggal, cabang Git, dll.) yang digunakan untuk membangun pelengkap sebenarnya.

Kode kelas (contoh): using namespace System.Collections<br>using namespace System.Collections.Generic<br>using namespace System.Management.Automation<br>using namespace System.Management.Automation.Language<br><br>class NumberCompleter : IArgumentCompleter {<br> $From<br> $To<br> $Step<br><br> NumberCompleter( $from, $to, $step) {<br> if ($from -gt $to) {<br> throw ::new("from")<br> }<br> $this.From = $from<br> $this.To = $to<br> $this.Step = $step -lt 1 ? 1 : $step<br> }<br><br> ] CompleteArgument(<br> $CommandName,<br> $parameterName,<br> $wordToComplete,<br> $commandAst,<br;> $fakeBoundParameters<br> ) {<br> $resultList = ]::new()<br> $Local:to = $this.To<br> $Local:step = $this.Step<br><br> for ($i = $this.From; $i -lt $to; $i += $step) {<br> $resultList.Add(::new($i.ToString()))<br> }<br><br> return $resultList<br> }<br>}<br><br>class NumberCompletionsAttribute : ArgumentCompleterAttribute, IArgumentCompleterFactory {<br> $From<br> $To<br> $Step<br><br> NumberCompletionsAttribute( $from, $to, $step) {<br> $this.From = $from<br> $this.To = $to<br> $this.Step = $step<br> }<br><br> Create() {<br> return ::new($this.From, $this.To, $this.Step)<br> }<br>}

Penggunaan atribut: function Add {<br> param(<br> <br> $X,<br;<br> <br> $Y<br> )<br> $X + $Y<br>}

Saat Anda menulis fungsi dan mulai mengisi parameter, Tab akan memberikan saran. Nilai numerik antara 0 dan 100 dengan kelipatan 5.tanpa harus mengulangi logika pelengkapan otomatis di setiap fungsi. Teknik yang sama dapat diterapkan pada jalur direktori, tanggal yang dihitung, commit Git untuk cabang tertentu, dan, secara umum, skenario apa pun di mana Anda membutuhkannya. pengisi yang dapat digunakan kembali dan dikonfigurasi.

Fitur pelengkapan otomatis ala Linux di PowerShell menggunakan PSReadLine dan Register-ArgumentCompleter

Jika Anda berasal dari dunia GNU/Linux, Anda mungkin sudah terbiasa dengan pengalaman pelengkapan otomatis tingkat lanjut yang ditawarkan oleh shell seperti zshdengan menu interaktif dan saran yang sangat cerdas. PowerShell, meskipun berbeda, juga memungkinkan Anda untuk mendekati pengalaman tersebut dengan menggabungkan PSReadLine dan Register-ArgumentCompleter.

Di satu sisi, dengan Set-PSReadlineKeyHandler Anda dapat mengubah cara kerja tombol Tab. Trik yang sangat berguna adalah mengkonfigurasi Tab untuk menampilkan menu pilihan yang mudah dinavigasi alih-alih sekadar menyelesaikan item berikutnya:

Perintah PSReadLine: Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete

Jika Anda memasukkan baris ini ke dalam berkas profil dari PowerShell, misalnya dengan mengeditnya dengan notepad $profileIni akan memastikan bahwa setiap sesi PowerShell baru dimulai dengan perilaku Tab tersebut, sehingga jauh lebih menyenangkan untuk menjelajahi opsi yang tersedia. Namun, Anda mungkin perlu... menyesuaikan kebijakan eksekusi di sistem Anda sehingga profil berjalan tanpa batasan yang berlebihan.

Di sisi lain, menggabungkan fitur PSReadLine ini dengan pengisi yang terdaftar melalui Pelengkap Argumen Register (misalnya, untuk winget, dotnet atau modul Anda sendiri), Anda bisa mendapatkan kelancaran yang hampir sama dengan fitur pelengkapan otomatis. LinuxBanyak tim berbagi ScriptBlock pelengkap di repositori mereka, sehingga seluruh organisasi dapat memilikinya. lingkungan baris perintah yang koheren dan sangat produktif.