Pedoman Pengembangan yang Sangat Disarankan

Bagian ini menjelaskan panduan yang harus Anda ikuti saat menulis cmdlet Anda. Mereka dipisahkan menjadi panduan untuk merancang cmdlet dan panduan untuk menulis kode cmdlet Anda. Anda mungkin menemukan bahwa panduan ini tidak berlaku untuk setiap skenario. Namun, jika ini berlaku dan Anda tidak mengikuti panduan ini, pengguna Anda mungkin mengalami pengalaman yang buruk saat mereka menggunakan cmdlet Anda.

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.

Menggunakan Noun Tertentu untuk Nama Cmdlet (SD01)

Kata benda yang digunakan dalam penamaan cmdlet harus sangat spesifik sehingga pengguna dapat menemukan cmdlet Anda. Gunakan awalan versi singkat dari nama produk untuk kata benda generik seperti "server". Misalnya, jika kata benda mengacu pada server yang menjalankan instans Microsoft SQL Server, gunakan kata benda seperti "SQLServer". Kombinasi kata benda tertentu dan daftar singkat kata kerja yang disetujui memungkinkan pengguna untuk dengan cepat menemukan dan mengantisipasi fungsionalitas sambil menghindari duplikasi di antara nama cmdlet.

Untuk meningkatkan pengalaman pengguna, kata benda yang Anda pilih untuk nama cmdlet harus tunggal. Misalnya, gunakan nama Get-Process alih-alih Get-Processes. Yang terbaik adalah mengikuti aturan ini untuk semua nama cmdlet, bahkan ketika cmdlet cenderung bertindak pada lebih dari satu item.

Gunakan Kasus Pascal untuk Nama Cmdlet (SD02)

Gunakan kasus Pascal untuk nama parameter. Dengan kata lain, kapitalisasi huruf pertama kata kerja dan semua istilah yang digunakan dalam kata benda. Misalnya, "Clear-ItemProperty".

Panduan Desain Parameter (SD03)

Cmdlet membutuhkan parameter yang menerima data di mana operasi harus dilakukan, dan parameter yang menunjukkan informasi yang digunakan untuk menentukan karakteristik operasi. Misalnya, cmdlet mungkin memiliki Name parameter yang menerima data dari alur, dan cmdlet mungkin memiliki Force parameter untuk menunjukkan bahwa cmdlet dapat dipaksa untuk melakukan operasinya. Tidak ada batasan jumlah parameter yang dapat ditentukan cmdlet.

Gunakan Nama Parameter Standar

Cmdlet Anda harus menggunakan nama parameter standar sehingga pengguna dapat dengan cepat menentukan apa arti parameter tertentu. Jika nama yang lebih spesifik diperlukan, gunakan nama parameter standar, lalu tentukan nama yang lebih spesifik sebagai alias. Misalnya, Get-Service cmdlet memiliki parameter yang memiliki nama generik (Name) dan alias yang lebih spesifik (ServiceName). Kedua istilah dapat digunakan untuk menentukan parameter .

Untuk informasi selengkapnya tentang nama parameter dan jenis datanya, lihat Nama Parameter Cmdlet dan Panduan Fungsionalitas.

Menggunakan Nama Parameter Tunggal

Hindari menggunakan nama jamak untuk parameter yang nilainya adalah elemen tunggal. Ini termasuk parameter yang mengambil array atau daftar karena pengguna mungkin menyediakan array atau daftar hanya dengan satu elemen.

Nama parameter plural harus digunakan hanya dalam kasus-kasus di mana nilai parameter selalu merupakan nilai beberapa elemen. Dalam kasus ini, cmdlet harus memverifikasi bahwa beberapa elemen disediakan, dan cmdlet harus menampilkan peringatan kepada pengguna jika beberapa elemen tidak disediakan.

Menggunakan Kasus Pascal untuk Nama Parameter

Gunakan kasus Pascal untuk nama parameter. Dengan kata lain, kapitalisasi huruf pertama setiap kata dalam nama parameter, termasuk huruf pertama nama. Misalnya, nama ErrorAction parameter menggunakan kapitalisasi yang benar. Nama parameter berikut menggunakan kapitalisasi yang salah:

• errorAction
• erroraction

Parameter yang Mengambil Daftar Opsi

Ada dua cara untuk membuat parameter yang nilainya dapat dipilih dari serangkaian opsi.

• Tentukan jenis enumerasi (atau gunakan jenis enumerasi yang ada) yang menentukan nilai yang valid. Kemudian, gunakan jenis enumerasi untuk membuat parameter jenis tersebut.

• Tambahkan atribut ValidateSet ke deklarasi parameter. Untuk informasi selengkapnya tentang atribut ini, lihat ValidateSet Attribute Declaration.

Menggunakan Jenis Standar untuk Parameter

Untuk memastikan konsistensi dengan cmdlet lain, gunakan jenis standar untuk parameter jika memungkinkan. Untuk informasi selengkapnya tentang jenis yang harus digunakan untuk parameter yang berbeda, lihat Nama dan Jenis Parameter Cmdlet Standar. Topik ini menyediakan tautan ke beberapa topik yang menjelaskan nama dan jenis .NET Framework untuk grup parameter standar, seperti "parameter aktivitas".

Menggunakan Tipe .NET Framework yang Bertipe-Kuat

Parameter harus didefinisikan sebagai jenis .NET Framework untuk memberikan validasi parameter yang lebih baik. Misalnya, parameter yang dibatasi untuk satu nilai dari sekumpulan nilai harus didefinisikan sebagai jenis enumerasi. Untuk mendukung nilai Pengidentifikasi Sumber Daya Seragam (URI), tentukan parameter sebagai jenis System.Uri . Hindari parameter string dasar untuk semua properti teks kecuali properti teks bentuk bebas.

Gunakan Jenis Parameter Yang Konsisten

Ketika parameter yang sama digunakan oleh beberapa cmdlet, selalu gunakan jenis parameter yang sama. Misalnya, jika Process parameter adalah jenis System.Int16 untuk satu cmdlet, jangan buat Process parameter untuk cmdlet lain jenis System.Uint16 .

Parameter yang Menerima "True" dan "False"

Jika parameter Anda hanya dapat mengambil nilai true dan false, tentukan parameter sebagai jenis System.Management.Automation.SwitchParameter. Parameter [switch] diperlakukan seperti true ketika ditentukan dalam perintah. Jika parameter tidak disertakan dalam perintah, Windows PowerShell menganggap nilai parameter false. Jangan tentukan parameter Boolean.

Jika parameter Anda perlu membedakan antara 3 nilai: $true, $false dan "tidak ditentukan", maka tentukan parameter jenis bool< Nullable>. Kebutuhan akan nilai ke-3, "tidak ditentukan" biasanya terjadi ketika cmdlet dapat memodifikasi properti Boolean dari objek. Dalam hal ini "tidak ditentukan" berarti tidak mengubah nilai properti saat ini.

Mendukung Array untuk Parameter

Seringkali, pengguna harus melakukan operasi yang sama terhadap beberapa argumen. Untuk pengguna ini, cmdlet harus menerima array sebagai input parameter sehingga pengguna dapat meneruskan argumen ke parameter sebagai variabel PowerShell Windows. Misalnya, cmdlet Get-Process menggunakan array untuk string yang mengidentifikasi nama proses yang akan diambil.

Mendukung Parameter PassThru

Secara default, banyak cmdlet yang memodifikasi sistem, seperti cmdlet Stop-Process, bertindak sebagai "sink" untuk objek dan tidak mengembalikan hasilnya. Cmdlet ini harus mengimplementasikan PassThru parameter untuk memaksa cmdlet mengembalikan objek. PassThru Ketika parameter ditentukan, cmdlet mengembalikan objek dengan menggunakan panggilan ke metode System.Management.Automation.Cmdlet.WriteObject. Misalnya, perintah berikut menghentikan Calc (CalculatorApp.exe) dan meneruskan proses yang dihasilkan ke alur.

Stop-Process -Name CalculatorApp -PassThru

Dalam kebanyakan kasus, cmdlet Tambahkan, Atur, dan Baru harus mendukung PassThru parameter.

Set Dukungan Parameter

Cmdlet dimaksudkan untuk mencapai satu tujuan. Namun, sering ada lebih dari satu cara untuk menjelaskan operasi atau target operasi. Misalnya, proses mungkin diidentifikasi dengan namanya, oleh pengidentifikasinya, atau oleh objek proses. Cmdlet harus mendukung semua representasi yang sesuai dari target sasarannya. Biasanya, cmdlet memenuhi persyaratan ini dengan menentukan set parameter (disebut sebagai set parameter) yang beroperasi bersama-sama. Parameter tunggal dapat termasuk dalam sejumlah set parameter. Untuk informasi selengkapnya tentang set parameter, lihat Set Parameter Cmdlet.

Saat Anda menentukan set parameter, atur hanya satu parameter dalam set ke ValueFromPipeline. Untuk informasi selengkapnya tentang cara mendeklarasikan atribut Parameter , lihat Deklarasi ParameterAttribute.

Saat set parameter digunakan, set parameter default ditentukan oleh atribut Cmdlet . Kumpulan parameter default harus menyertakan parameter yang kemungkinan besar akan digunakan dalam sesi PowerShell Windows interaktif. Untuk informasi selengkapnya tentang cara mendeklarasikan atribut Cmdlet , lihat Deklarasi CmdletAttribute.

Berikan Umpan Balik kepada Pengguna (SD04)

Gunakan panduan di bagian ini untuk memberikan umpan balik kepada pengguna. Umpan balik ini memungkinkan pengguna untuk mengetahui apa yang terjadi dalam sistem dan membuat keputusan administratif yang lebih baik.

Runtime PowerShell Windows memungkinkan pengguna untuk menentukan cara menangani output dari setiap panggilan ke metode Write dengan mengatur variabel preferensi. Pengguna dapat mengatur beberapa variabel preferensi, termasuk variabel yang menentukan apakah sistem harus menampilkan informasi dan variabel yang menentukan apakah sistem harus mengkueri pengguna sebelum mengambil tindakan lebih lanjut.

Mendukung Metode WriteWarning, WriteVerbose, dan WriteDebug

Cmdlet harus memanggil metode System.Management.Automation.Cmdlet.WriteWarning ketika cmdlet akan melakukan operasi yang mungkin memiliki hasil yang tidak diinginkan. Misalnya, cmdlet harus memanggil metode ini jika cmdlet akan menimpa file baca-saja.

Cmdlet harus memanggil metode System.Management.Automation.Cmdlet.WriteVerbose ketika pengguna memerlukan beberapa detail tentang apa yang dilakukan cmdlet. Misalnya, cmdlet harus memanggil informasi ini jika penulis cmdlet merasa bahwa ada skenario yang mungkin memerlukan informasi lebih lanjut tentang apa yang dilakukan cmdlet.

Cmdlet harus memanggil metode System.Management.Automation.Cmdlet.WriteDebug ketika pengembang atau teknisi dukungan produk harus memahami apa yang telah merusak operasi cmdlet. Cmdlet tidak diperlukan untuk memanggil metode System.Management.Automation.Cmdlet.WriteDebug dalam kode yang sama yang memanggil metode System.Management.Automation.Cmdlet.WriteVerbose karena Debug parameter menyajikan kedua set informasi.

Mendukung WriteProgress untuk Operasi yang membutuhkan Waktu Lama

Operasi cmdlet yang membutuhkan waktu lama untuk diselesaikan dan yang tidak dapat berjalan di latar belakang harus mendukung pelaporan kemajuan melalui panggilan berkala ke metode System.Management.Automation.Cmdlet.WriteProgress .

Menggunakan Antarmuka Host

Terkadang, cmdlet harus berkomunikasi langsung dengan pengguna, alih-alih menggunakan berbagai metode Write atau Should yang didukung oleh kelas System.Management.Automation.Cmdlet. Dalam hal ini, cmdlet harus berasal dari kelas System.Management.Automation.PSCmdlet dan menggunakan properti System.Management.Automation.PSCmdlet.Host* . Properti ini mendukung berbagai tingkat jenis komunikasi, termasuk jenis PromptForChoice, Prompt, dan WriteLine/ReadLine. Pada tingkat yang paling spesifik, ini juga menyediakan cara untuk membaca dan menulis kunci individual dan untuk menangani buffer.

Kecuali cmdlet dirancang khusus untuk menghasilkan antarmuka pengguna grafis (GUI), cmdlet tidak boleh melewati host dengan menggunakan properti System.Management.Automation.PSCmdlet.Host* . Contoh cmdlet yang dirancang untuk menghasilkan GUI adalah cmdlet Out-GridView.

Nota

Cmdlet tidak boleh menggunakan SYSTEM.Console API.

Membuat Berkas Bantuan Cmdlet (SD05)

Untuk setiap perakitan cmdlet, buat file Help.xml yang berisi informasi tentang cmdlet. Informasi ini mencakup deskripsi cmdlet, deskripsi parameter cmdlet, contoh penggunaan cmdlet, dan banyak lagi.

Panduan Pengkodean

Panduan berikut harus diikuti saat mengkodekan cmdlet guna menjamin pengalaman pengguna yang seragam antara penggunaan cmdlet Anda dan cmdlet lainnya. Saat Anda menemukan pedoman Kode yang berlaku untuk situasi Anda, pastikan untuk melihat panduan Desain untuk panduan serupa.

Parameter Pengkodian (SC01)

Tentukan parameter dengan mendeklarasikan properti publik dari kelas cmdlet yang dihiasi dengan atribut Parameter . Parameter tidak harus menjadi anggota statis dari kelas .NET Framework turunan untuk cmdlet. Untuk informasi selengkapnya tentang cara mendeklarasikan atribut Parameter , lihat Deklarasi Atribut Parameter.

Mendukung Windows Jalur PowerShell

Jalur Windows PowerShell adalah mekanisme untuk mengatur akses ke namespace. Saat Anda menetapkan jalur PowerShell Windows ke parameter di cmdlet, pengguna dapat menentukan "drive" kustom yang bertindak sebagai pintasan ke jalur tertentu. Saat pengguna menunjuk drive seperti itu, data yang disimpan, seperti data di Registri, dapat digunakan dengan cara yang konsisten.

Jika cmdlet Anda memungkinkan pengguna menentukan file atau sumber data, cmdlet tersebut harus menentukan parameter jenis System.String. Jika lebih dari satu drive didukung, jenisnya harus berupa array. Nama parameter harus Path, dengan alias .PSPath Selain itu, parameter Path harus mendukung karakter wildcard. Jika dukungan untuk karakter pengganti tidak diperlukan, tentukan parameter LiteralPath.

Jika data yang dibaca atau ditulis cmdlet harus berupa file, cmdlet harus menerima input jalur Windows PowerShell, dan cmdlet harus menggunakan System.Management.Automation.SessionState.Path untuk menerjemahkan jalur Windows PowerShell ke jalur yang dikenali sistem file. Mekanisme khusus mencakup metode berikut:

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

Jika data yang dibaca atau ditulis cmdlet hanyalah sekumpulan string alih-alih file, cmdlet harus menggunakan informasi konten penyedia (Content anggota) untuk membaca dan menulis. Informasi ini diperoleh dari properti System.Management.Automation.Provider.CmdletProvider.InvokeProvider . Mekanisme ini memungkinkan penyimpanan data lain untuk berpartisipasi dalam pembacaan dan penulisan data.

Dukung Karakter Pengganti

Cmdlet harus mendukung karakter kartu bebas jika memungkinkan. Dukungan untuk karakter wildcard dapat digunakan di banyak tempat dalam cmdlet (terutama ketika parameter mengambil string untuk mengidentifikasi satu objek dari sekumpulan objek). Misalnya, cmdlet sampel Stop-Proc dari Tutorial StopProc menentukan Name parameter untuk menangani string yang mewakili nama proses. Parameter ini mendukung karakter kartu bebas sehingga pengguna dapat dengan mudah menentukan proses yang akan dihentikan ini.

Ketika dukungan untuk karakter wildcard tersedia, operasi cmdlet biasanya menghasilkan array. Terkadang, tidak masuk akal untuk mendukung array karena pengguna mungkin hanya menggunakan satu item pada satu waktu. Misalnya, cmdlet Set-Location tidak perlu mendukung array karena pengguna hanya mengatur satu lokasi. Dalam hal ini, cmdlet masih mendukung karakter pengganti, tetapi memaksa untuk diresolusikan ke satu lokasi saja.

Untuk informasi selengkapnya tentang pola karakter wildcard, lihat Mendukung Karakter Wildcard dalam Parameter Cmdlet.

Menentukan Objek

Bagian ini berisi panduan untuk menentukan objek untuk cmdlet dan untuk memperluas objek yang ada.

Tentukan Anggota Standar

Tentukan anggota standar untuk memperluas jenis objek dalam file Type.ps1xml kustom (gunakan file Windows PowerShell Type.ps1xml sebagai templat). Anggota standar didefinisikan oleh simpul dengan nama PSStandardMembers. Definisi ini memungkinkan cmdlet lain dan runtime PowerShell Windows untuk bekerja dengan objek Anda dengan cara yang konsisten.

Tentukan ObjectMembers yang Akan Digunakan sebagai Parameter

Jika Anda merancang objek untuk cmdlet, pastikan anggotanya memetakan langsung ke parameter cmdlet yang akan menggunakannya. Pemetaan ini memungkinkan objek untuk dikirim dengan mudah ke jalur pipa dan diteruskan dari satu cmdlet ke cmdlet lainnya.

Objek kerangka kerja .NET yang sudah ada sebelumnya yang dikembalikan oleh cmdlet sering kehilangan beberapa anggota penting atau nyaman yang diperlukan oleh pengembang atau pengguna skrip. Anggota yang hilang ini dapat sangat penting untuk ditampilkan dan untuk membuat nama anggota yang benar sehingga objek dapat diteruskan dengan benar ke alur. Buat berkas Types.ps1xml kustom untuk mendokumentasikan anggota-anggota yang diperlukan ini. Saat Anda membuat file ini, kami merekomendasikan konvensi penamaan berikut: <Your_Product_Name>. Type.ps1xml.

Misalnya, Anda dapat menambahkan Mode properti skrip ke jenis System.IO.FileInfo untuk menampilkan atribut file dengan lebih jelas. Selain itu, Anda dapat menambahkan Count properti alias ke jenis System.Array untuk memungkinkan penggunaan nama properti tersebut secara konsisten (bukan Length).

Menerapkan Antarmuka IComparable

Menerapkan antarmuka System.IComparable pada semua objek output. Ini memungkinkan objek output untuk dengan mudah disalurkan ke berbagai cmdlet pengurutan dan analisis.

Perbarui Informasi Tampilan

Jika tampilan untuk objek tidak memberikan hasil yang diharapkan, buat Format kustom<YourProductName>.file Format.ps1xml untuk objek tersebut.

Mendukung Input Alur yang Ditentukan Dengan Baik (SC02)

Terapkan untuk Tengah Alur

Terapkan cmdlet dengan asumsi bahwa cmdlet akan dipanggil dari tengah alur (artinya, cmdlet lain akan menghasilkan inputnya atau mengonsumsi outputnya). Misalnya, Anda mungkin berasumsi bahwa Get-Process cmdlet, karena menghasilkan data, hanya digunakan sebagai cmdlet pertama dalam alur. Namun, karena cmdlet ini dirancang untuk tengah alur, cmdlet ini memungkinkan cmdlet atau data sebelumnya dalam alur untuk menentukan proses yang akan diambil.

Dukungan Input dari Pipeline

Di setiap pengaturan parameter untuk cmdlet, sertakan setidaknya satu parameter yang mendukung input dari saluran pipa. Dukungan untuk input alur memungkinkan pengguna untuk mengambil data atau objek, mengirimnya ke set parameter yang benar, dan meneruskan hasilnya langsung ke cmdlet.

Parameter menerima input dari alur jika atribut Parameter menyertakan ValueFromPipeline kata kunci, ValueFromPipelineByPropertyName atribut kata kunci, atau kedua kata kunci dalam deklarasinya. Jika tidak ada parameter dalam himpunan parameter yang mendukung kata kunci ValueFromPipeline atau ValueFromPipelineByPropertyName, cmdlet tidak dapat ditempatkan dengan tepat setelah cmdlet lain karena akan mengabaikan input alur apa pun.

Dukung Metode ProcessRecord

Untuk menerima semua rekaman dari cmdlet sebelumnya dalam alur, cmdlet Anda harus menerapkan metode System.Management.Automation.Cmdlet.ProcessRecord . Windows PowerShell memanggil metode ini beberapa kali, sekali untuk setiap rekaman yang dikirim ke cmdlet Anda.

Menulis Rekaman Tunggal ke Pipa (SC03)

Ketika cmdlet mengembalikan objek, cmdlet harus menuliskan objek seketika saat dibuat. Cmdlet tidak boleh menahannya untuk menyangganya ke dalam array gabungan. Cmdlet yang menerima objek sebagai input kemudian akan dapat memproses, menampilkan, atau memproses dan menampilkan objek output tanpa penundaan. Cmdlet yang menghasilkan objek output satu per satu harus memanggil metode System.Management.Automation.Cmdlet.WriteObject . Cmdlet yang menghasilkan objek output dalam batch (misalnya, karena API yang mendasar mengembalikan array objek output) harus memanggil Metode System.Management.Automation.Cmdlet.WriteObject dengan parameter kedua diatur ke true.

Membuat Cmdlet Case-Insensitive dan Case-Preserving (SC04)

Secara default, Windows PowerShell itu sendiri tidak peka huruf besar/kecil. Namun, karena berkaitan dengan banyak sistem yang sudah ada sebelumnya, Windows PowerShell mempertahankan kasus untuk kemudahan operasi dan kompatibilitas. Dengan kata lain, jika karakter disediakan dalam huruf besar, Windows PowerShell menyimpannya dalam huruf besar. Agar sistem berfungsi dengan baik, cmdlet perlu mengikuti konvensi ini. Jika memungkinkan, itu harus beroperasi secara tidak peka terhadap huruf besar atau kecil. Namun, ini harus mempertahankan kasus asli untuk cmdlet yang terjadi nanti dalam perintah atau di alur.

Lihat Juga

Pedoman Pengembangan yang Diperlukan

Pedoman Pengembangan Saran

Menulis Cmdlet Windows PowerShell