Bagikan melalui

Pedoman Pengembangan yang Diperlukan

Panduan berikut harus diikuti saat Anda menulis cmdlet Anda. Mereka dipisahkan menjadi panduan untuk merancang cmdlet dan panduan untuk menulis kode cmdlet Anda. Jika Anda tidak mengikuti panduan ini, cmdlet Anda bisa gagal, dan pengguna Anda mungkin memiliki pengalaman yang buruk saat mereka menggunakan cmdlet Anda.

Dalam Topik ini

Panduan Desain

Pedoman Kode

Panduan Desain

Panduan berikut harus diikuti saat merancang cmdlet untuk memastikan pengalaman pengguna yang konsisten antara menggunakan cmdlet Anda dan cmdlet lainnya. Saat Anda menemukan panduan Desain yang berlaku untuk situasi Anda, pastikan untuk melihat panduan Kode untuk panduan serupa.

Gunakan Kata Kerja yang Disetujui Saja (RD01)

Kata kerja yang ditentukan dalam atribut Cmdlet harus berasal dari kumpulan kata kerja yang dikenali yang disediakan oleh Windows PowerShell. Ini tidak boleh menjadi salah satu sinonim yang dilarang. Gunakan string konstanta yang ditentukan oleh enumerasi berikut untuk menentukan kata kerja cmdlet:

Untuk informasi selengkapnya tentang nama kata kerja yang disetujui, lihat Cmdlet Verbs.

Pengguna memerlukan sekumpulan nama cmdlet yang dapat ditemukan dan diharapkan. Gunakan kata kerja yang sesuai sehingga pengguna dapat membuat penilaian cepat tentang apa yang dilakukan cmdlet dan untuk dengan mudah menemukan kemampuan sistem. Misalnya, perintah baris perintah berikut mendapatkan daftar semua perintah pada sistem yang namanya dimulai dengan "Mulai": Get-Command Start-*. Gunakan kata benda dalam cmdlet Anda untuk membedakan cmdlet Anda dari cmdlet lain. Kata benda menunjukkan sumber daya tempat operasi akan dilakukan. Operasi itu sendiri diwakili oleh kata kerja.

Nama Cmdlet: Karakter yang tidak dapat Digunakan (RD02)

Saat Anda memberi nama cmdlet, jangan gunakan salah satu karakter khusus berikut.

Karakter Nama
# tanda angka
, koma
() tanda kurung
{} kawat gigi
[] Kurung
& tanda dan
- tanda hubung Catatan: Tanda hubung dapat digunakan untuk memisahkan kata kerja dari kata benda, tetapi tidak dapat digunakan dalam kata benda atau dalam kata kerja.
/ tanda garis miring
\ garis miring terbalik
$ tanda dolar
^ caret
; titik koma
: titik dua
" tanda kutip ganda
' tanda kutip tunggal
<> tanda kurung sudut
| bilah vertikal
? tanda tanya
@ tanda tangan
` tanda centang belakang (aksen kuburan)
* tanda bintang
% tanda persen
+ tanda plus
= tanda sama dengan
~ Tilde

Nama Parameter yang tidak dapat Digunakan (RD03)

Windows PowerShell menyediakan set parameter umum untuk semua cmdlet ditambah parameter tambahan yang ditambahkan dalam situasi tertentu. Saat merancang cmdlet Anda sendiri, Anda tidak dapat menggunakan nama berikut: Konfirmasi, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction, dan Verbose. Untuk informasi selengkapnya tentang parameter ini, lihat Nama Parameter Umum.

Permintaan Konfirmasi Dukungan (RD04)

Untuk cmdlet yang melakukan operasi yang memodifikasi sistem, mereka harus memanggil metode System.Management.Automation.Cmdlet.ShouldProcess* untuk meminta konfirmasi, dan dalam kasus khusus memanggil metode System.Management.Automation.Cmdlet.ShouldContinue*. (Metode System.Management.Automation.Cmdlet.ShouldContinue* harus dipanggil hanya setelah metode System.Management.Automation.Cmdlet.ShouldProcess* dipanggil.)

Untuk melakukan panggilan ini, cmdlet harus menentukan bahwa ia mendukung permintaan konfirmasi dengan mengatur kata kunci SupportsShouldProcess atribut Cmdlet. Untuk informasi selengkapnya tentang mengatur atribut ini, lihat Deklarasi Atribut Cmdlet.

Nota

Jika atribut Cmdlet dari kelas cmdlet menunjukkan bahwa cmdlet mendukung panggilan ke metode System.Management.Automation.Cmdlet.ShouldProcess*, dan cmdlet gagal melakukan panggilan ke metode System.Management.Automation.Cmdlet.ShouldProcess*, pengguna dapat memodifikasi sistem secara tak terduga.

Gunakan metode System.Management.Automation.Cmdlet.ShouldProcess* untuk setiap modifikasi sistem. Preferensi pengguna dan parameter WhatIf mengontrol metode System.Management.Automation.Cmdlet.ShouldProcess*. Sebaliknya, panggilan System.Management.Automation.Cmdlet.ShouldContinue* melakukan pemeriksaan tambahan untuk modifikasi yang berpotensi berbahaya. Metode ini tidak dikontrol oleh preferensi pengguna atau parameter WhatIf. Jika cmdlet Anda memanggil metode System.Management.Automation.Cmdlet.ShouldContinue*, cmdlet Anda harus memiliki parameter Force yang melewati panggilan ke dua metode ini dan yang melanjutkan operasi. Ini penting karena memungkinkan cmdlet Anda digunakan dalam skrip dan host non-interaktif.

Jika cmdlet Anda mendukung panggilan ini, pengguna dapat menentukan apakah tindakan harus benar-benar dilakukan. Misalnya, cmdlet Stop-Process memanggil metode System.Management.Automation.Cmdlet.ShouldContinue* sebelum menghentikan serangkaian proses penting, termasuk proses Sistem, Winlogon, dan Spoolsv.

Untuk informasi selengkapnya tentang mendukung metode ini, lihat Meminta Konfirmasi.

Parameter Paksa Dukungan untuk Sesi Interaktif (RD05)

Jika cmdlet Anda digunakan secara interaktif, selalu berikan parameter Paksa untuk mengambil alih tindakan interaktif, seperti perintah atau baris baca input). Ini penting karena memungkinkan cmdlet Anda digunakan dalam skrip dan host non-interaktif. Metode berikut dapat diimplementasikan oleh host interaktif.

Objek Output Dokumen (RD06)

Windows PowerShell menggunakan objek yang ditulis ke alur. Agar pengguna dapat memanfaatkan objek yang dikembalikan oleh setiap cmdlet, Anda harus mendokumentasikan objek yang dikembalikan, dan Anda harus mendokumentasikan untuk apa anggota objek yang dikembalikan tersebut digunakan.

Pedoman Kode

Panduan berikut harus diikuti saat menulis kode cmdlet. Saat Anda menemukan pedoman Kode yang berlaku untuk situasi Anda, pastikan untuk melihat panduan Desain untuk panduan serupa.

Berasal dari Kelas Cmdlet atau PSCmdlet (RC01)

Cmdlet harus berasal dari System.Management.Automation.Cmdlet atau System.Management.Automation.PSCmdlet kelas dasar. Cmdlet yang berasal dari kelas System.Management.Automation.Cmdlet tidak bergantung pada runtime Windows PowerShell. Mereka dapat dipanggil langsung dari bahasa Microsoft .NET Framework apa pun. Cmdlet yang berasal dari kelas System.Management.Automation.PSCmdlet bergantung pada runtime Windows PowerShell. Oleh karena itu, mereka mengeksekusi dalam runspace.

Semua kelas cmdlet yang Anda terapkan harus kelas publik. Untuk informasi selengkapnya tentang kelas cmdlet ini, lihat Gambaran Umum cmdlet .

Tentukan Atribut Cmdlet (RC02)

Agar cmdlet dikenali oleh Windows PowerShell, kelas .NET Framework-nya harus dihiasi dengan atribut Cmdlet. Atribut ini menentukan fitur cmdlet berikut.

  • Pasangan kata kerja dan kata benda yang mengidentifikasi cmdlet.

  • Kumpulan parameter default yang digunakan saat beberapa set parameter ditentukan. Kumpulan parameter default digunakan ketika Windows PowerShell tidak memiliki informasi yang cukup untuk menentukan parameter mana yang diatur untuk digunakan.

  • Menunjukkan apakah cmdlet mendukung panggilan ke metode System.Management.Automation.Cmdlet.ShouldProcess*. Metode ini menampilkan pesan konfirmasi kepada pengguna sebelum cmdlet membuat perubahan pada sistem. Untuk informasi selengkapnya tentang bagaimana permintaan konfirmasi dibuat, lihat Meminta Konfirmasi.

  • Menunjukkan tingkat dampak (atau tingkat keparahan) tindakan yang terkait dengan pesan konfirmasi. Dalam kebanyakan kasus, nilai default Medium harus digunakan. Untuk informasi selengkapnya tentang bagaimana tingkat dampak memengaruhi permintaan konfirmasi yang ditampilkan kepada pengguna, lihat Meminta Konfirmasi.

Untuk informasi selengkapnya tentang cara mendeklarasikan atribut cmdlet, lihat Deklarasi CmdletAttribute.

Mengambil alih Metode Pemrosesan Input (RC03)

Agar cmdlet berpartisipasi dalam lingkungan Windows PowerShell, cmdlet harus mengambil alih setidaknya salah satu metode pemrosesan input berikut.

System.Management.Automation.Cmdlet.BeginProcessing Metode ini disebut satu kali, dan digunakan untuk menyediakan fungsionalitas pra-pemrosesan.

System.Management.Automation.Cmdlet.ProcessRecord Metode ini dipanggil beberapa kali, dan digunakan untuk menyediakan fungsionalitas rekaman demi rekaman.

System.Management.Automation.Cmdlet.EndProcessing Metode ini disebut satu kali, dan digunakan untuk menyediakan fungsionalitas pasca-pemrosesan.

Tentukan Atribut OutputType (RC04)

Atribut OutputType (diperkenalkan di Windows PowerShell 2.0) menentukan jenis .NET Framework yang dikembalikan cmdlet Anda ke alur. Dengan menentukan jenis output cmdlet Anda, Anda membuat objek yang dikembalikan oleh cmdlet Anda lebih dapat ditemukan oleh cmdlet lain. Untuk informasi selengkapnya tentang mendekorasi kelas cmdlet dengan atribut ini, lihat Deklarasi Atribut OutputType.

Jangan Pertahankan Handel ke Objek Output (RC05)

Cmdlet Anda tidak boleh mempertahankan handel apa pun ke objek yang diteruskan ke metode System.Management.Automation.Cmdlet.WriteObject*. Objek ini diteruskan ke cmdlet berikutnya dalam alur, atau digunakan oleh skrip. Jika Anda mempertahankan handel ke objek, dua entitas akan memiliki setiap objek, yang menyebabkan kesalahan.

Menangani Kesalahan Dengan Kuat (RC06)

Lingkungan administrasi secara inheren mendeteksi dan membuat perubahan penting pada sistem yang Anda kelola. Oleh karena itu, sangat penting bahwa cmdlet menangani kesalahan dengan benar. Untuk informasi selengkapnya tentang rekaman kesalahan, lihat Pelaporan Kesalahan Windows PowerShell .

  • Ketika kesalahan mencegah cmdlet terus memproses rekaman lagi, itu adalah kesalahan yang mengakhiri. Cmdlet harus memanggil metode System.Management.Automation.Cmdlet.ThrowTerminatingError* yang mereferensikan objek System.Management.Automation.ErrorRecord. Jika pengecualian tidak tertangkap oleh cmdlet, runtime Windows PowerShell itu sendiri melemparkan kesalahan penghentian yang berisi lebih sedikit informasi.

  • Untuk kesalahan non-penghentian yang tidak menghentikan operasi pada rekaman berikutnya yang berasal dari alur (misalnya, rekaman yang dihasilkan oleh proses yang berbeda), cmdlet harus memanggil metode System.Management.Automation.Cmdlet.WriteError* yang mereferensikan System.Management.Automation.ErrorRecord objek. Contoh kesalahan yang tidak mengakhiri adalah kesalahan yang terjadi jika proses tertentu gagal dihentikan. Memanggil metode System.Management.Automation.Cmdlet.WriteError* memungkinkan pengguna untuk secara konsisten melakukan tindakan yang diminta dan mempertahankan informasi untuk tindakan tertentu yang gagal. Cmdlet Anda harus menangani setiap rekaman secara independen mungkin.

  • Objek System.Management.Automation.ErrorRecord yang direferensikan oleh metode System.Management.Automation.Cmdlet.ThrowTerminatingError* dan System.Management.Automation.Cmdlet.WriteError* memerlukan pengecualian pada intinya. Ikuti panduan desain .NET Framework saat Anda menentukan pengecualian untuk digunakan. Jika kesalahan secara semantik sama dengan pengecualian yang ada, gunakan pengecualian tersebut atau berasal dari pengecualian tersebut. Jika tidak, dapatkan hierarki pengecualian atau pengecualian baru langsung dari jenis System.Exception.

Objek System.Management.Automation.ErrorRecord juga memerlukan kategori kesalahan yang mengelompokkan kesalahan untuk pengguna. Pengguna dapat melihat kesalahan berdasarkan kategori dengan mengatur nilai variabel shell $ErrorView ke CategoryView. Kategori yang mungkin ditentukan oleh enumerasi System.Management.Automation.ErrorCategory.

  • Jika cmdlet membuat utas baru, dan jika kode yang berjalan di utas tersebut melemparkan pengecualian yang tidak tertangani, Windows PowerShell tidak akan menangkap kesalahan dan akan mengakhiri proses.

  • Jika objek memiliki kode dalam destruktornya yang menyebabkan pengecualian yang tidak tertangani, Windows PowerShell tidak akan menangkap kesalahan dan akan mengakhiri proses. Ini juga terjadi jika objek memanggil Metode buang yang menyebabkan pengecualian yang tidak tertangani.

Menggunakan Modul Windows PowerShell untuk Menyebarkan Cmdlet Anda (RC07)

Buat modul Windows PowerShell untuk mengemas dan menyebarkan cmdlet Anda. Dukungan untuk modul diperkenalkan di Windows PowerShell 2.0. Anda dapat menggunakan rakitan yang berisi kelas cmdlet Anda secara langsung sebagai file modul biner (ini sangat berguna saat menguji cmdlet Anda), atau Anda dapat membuat manifes modul yang mereferensikan rakitan cmdlet. (Anda juga dapat menambahkan rakitan snap-in yang ada saat menggunakan modul.) Untuk informasi selengkapnya tentang modul, lihat Menulis Modul Windows PowerShell.

Lihat Juga

Pedoman Pengembangan yang Sangat Didorong

Pedoman Pengembangan Nasihat

Menulis Cmdlet Windows PowerShell

  • Last updated on