Panduan Pengembangan Konsultatif

Bagian ini menjelaskan panduan yang harus Anda pertimbangkan untuk memastikan pengembangan yang baik dan pengalaman pengguna. Kadang-kadang mungkin berlaku, dan kadang-kadang mereka mungkin tidak.

Panduan Desain

Panduan berikut harus dipertimbangkan saat merancang cmdlet. Saat Anda menemukan panduan Desain yang berlaku untuk situasi Anda, pastikan untuk melihat panduan Kode untuk panduan serupa.

Mendukung Parameter InputObject (AD01)

Karena Windows PowerShell bekerja langsung dengan objek Microsoft .NET Framework, objek .NET Framework sering tersedia yang sama persis dengan jenis yang dibutuhkan pengguna untuk melakukan operasi tertentu. InputObject adalah nama standar untuk parameter yang mengambil objek seperti input. Misalnya, cmdlet sampel Stop-Proc dalam Tutorial StopProc menentukan InputObject parameter jenis Proses yang mendukung input dari alur. Pengguna bisa mendapatkan serangkaian objek proses, memanipulasinya untuk memilih objek yang tepat untuk dihentikan, lalu meneruskannya ke Stop-Proc cmdlet secara langsung.

Mendukung Parameter Paksa (AD02)

Terkadang, cmdlet perlu melindungi pengguna dari melakukan operasi yang diminta. Cmdlet semacam itu harus mendukung parameter Force untuk memungkinkan pengguna mengambil alih perlindungan tersebut jika pengguna memiliki izin untuk melakukan operasi.

Misalnya, cmdlet Hapus Item biasanya tidak menghapus file baca-saja. Namun, cmdlet ini mendukung parameter Force sehingga pengguna dapat memaksa penghapusan file baca-saja. Jika pengguna sudah memiliki izin untuk mengubah atribut baca-saja, dan pengguna menghapus file, penggunaan parameter Force menyederhanakan operasi. Namun, jika pengguna tidak memiliki izin untuk menghapus file, parameter Force tidak berpengaruh.

Menangani Kredensial Melalui Windows PowerShell (AD03)

Cmdlet harus menentukan Credential parameter untuk mewakili kredensial. Parameter ini harus berjenis System.Management.Automation.PSCredential dan harus ditentukan menggunakan deklarasi atribut Kredensial. Dukungan ini secara otomatis meminta nama pengguna, untuk kata sandi, atau untuk keduanya saat kredensial lengkap tidak disediakan secara langsung. Untuk informasi selengkapnya tentang atribut Kredensial, lihat Deklarasi Atribut Kredensial.

Parameter Pengodean Dukungan (AD04)

Jika cmdlet Anda membaca atau menulis teks ke atau dari formulir biner, seperti menulis ke atau membaca dari file dalam sistem file, maka cmdlet Anda harus memiliki parameter Pengodean yang menentukan bagaimana teks dikodekan dalam bentuk biner.

Cmdlet Pengujian Harus Mengembalikan Boolean (AD05)

Cmdlet yang melakukan pengujian terhadap sumber daya mereka harus mengembalikan jenis System.Boolean ke alur sehingga dapat digunakan dalam ekspresi bersyarat.

Pedoman Kode

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

Ikuti Konvensi Penamaan Kelas Cmdlet (AC01)

Dengan mengikuti konvensi penamaan standar, Anda membuat cmdlet Anda lebih dapat ditemukan, dan Anda membantu pengguna memahami dengan tepat apa yang dilakukan cmdlet. Praktik ini sangat penting bagi pengembang lain yang menggunakan Windows PowerShell karena cmdlet adalah jenis publik.

Tentukan Cmdlet di Namespace Yang Benar

Anda biasanya menentukan kelas untuk cmdlet di namespace .NET Framework yang ditambahkan .Commands ke namespace layanan yang mewakili produk tempat cmdlet berjalan. Misalnya, cmdlet yang disertakan dengan Windows PowerShell didefinisikan dalam Microsoft.PowerShell.Commands namespace.

Beri nama Kelas Cmdlet agar Sesuai dengan Nama Cmdlet

Saat Anda memberi nama kelas .NET Framework yang mengimplementasikan cmdlet, beri nama kelas <Verb><Noun>Command, tempat Anda mengganti <Verb> tempat penampung dan <Noun> dengan kata kerja dan kata benda yang digunakan untuk nama cmdlet. Misalnya, cmdlet Get-Process diimplementasikan oleh kelas yang disebut GetProcessCommand.

Jika Tidak Ada Input Alur mengambil alih Metode BeginProcessing (AC02)

Jika cmdlet Anda tidak menerima input dari alur, pemrosesan harus diimplementasikan dalam metode System.Management.Automation.Cmdlet.BeginProcessing . Penggunaan metode ini memungkinkan Windows PowerShell untuk mempertahankan pengurutan antar cmdlet. Cmdlet pertama dalam alur selalu mengembalikan objeknya sebelum cmdlet yang tersisa dalam alur mendapatkan kesempatan untuk memulai pemrosesannya.

Untuk Menangani Permintaan Berhenti Ambil Alih Metode StopProcessing (AC03)

Ambil alih metode System.Management.Automation.Cmdlet.StopProcessing sehingga cmdlet Anda dapat menangani sinyal berhenti. Beberapa cmdlet membutuhkan waktu lama untuk menyelesaikan operasi mereka, dan mereka membiarkan waktu yang lama berlalu antara panggilan ke runtime Windows PowerShell, seperti ketika cmdlet memblokir utas dalam panggilan RPC yang berjalan lama. Ini termasuk cmdlet yang melakukan panggilan ke metode System.Management.Automation.Cmdlet.WriteObject , ke metode System.Management.Automation.Cmdlet.WriteError , dan ke mekanisme umpan balik lainnya yang mungkin membutuhkan waktu lama untuk diselesaikan. Untuk kasus ini, pengguna mungkin perlu mengirim sinyal berhenti ke cmdlet ini.

Menerapkan Antarmuka IDisposable (AC04)

Jika cmdlet Anda memiliki objek yang tidak dibuang (ditulis ke alur) oleh metode System.Management.Automation.Cmdlet.ProcessRecord , cmdlet Anda mungkin memerlukan pembuangan objek tambahan. Misalnya, jika cmdlet Anda membuka handel file di metode System.Management.Automation.Cmdlet.BeginProcessing dan menjaga handel tetap terbuka untuk digunakan oleh metode System.Management.Automation.Cmdlet.ProcessRecord , handel ini harus ditutup di akhir pemrosesan.

Runtime Windows PowerShell tidak selalu memanggil metode System.Management.Automation.Cmdlet.EndProcessing . Misalnya, metode System.Management.Automation.Cmdlet.EndProcessing mungkin tidak dipanggil jika cmdlet dibatalkan di tengah operasinya atau jika kesalahan penghentian terjadi di bagian mana pun dari cmdlet. Oleh karena itu, kelas .NET Framework untuk cmdlet yang memerlukan pembersihan objek harus menerapkan pola antarmuka System.IDisposable lengkap, termasuk finalizer, sehingga runtime Windows PowerShell dapat memanggil metode System.Management.Automation.Cmdlet.EndProcessing dan System.IDisposable.Dispose* di akhir pemrosesan.

Gunakan Jenis Parameter ramah Serialisasi (AC05)

Untuk mendukung menjalankan cmdlet Anda pada komputer jarak jauh, gunakan jenis yang dapat diserialisasikan pada komputer klien lalu direhidrasi pada komputer server. Jenis berikut ramah serialisasi.

Jenis primitif:

• Byte, SByte, Desimal, Tunggal, Ganda, Int16, Int32, Int64, Uint16, UInt32, dan UInt64.
• Boolean, Guid, Byte[], TimeSpan, DateTime, Uri, dan Version.
• Karakter, String, XmlDocument.

Jenis rehidrasi bawaan:

• PSPrimitiveDictionary
• SwitchParameter
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Jenis lainnya:

• SecureString
• Kontainer (daftar dan kamus dari jenis di atas)

Menggunakan SecureString untuk Data Sensitif (AC06)

Saat menangani data sensitif selalu gunakan tipe data System.Security.SecureString . Ini dapat mencakup input alur ke parameter, serta mengembalikan data sensitif ke alur.

Meskipun .NET merekomendasikan untuk tidak menggunakan SecureString untuk pengembangan baru, PowerShell terus mendukung kelas SecureString untuk kompatibilitas mundur. Menggunakan SecureString masih lebih aman daripada menggunakan string teks biasa. PowerShell masih mengandalkan jenis SecureString untuk menghindari mengekspos konten secara tidak sengaja ke konsol atau log. Gunakan SecureString dengan hati-hati, karena dapat dengan mudah dikonversi ke string teks biasa. Untuk diskusi lengkap tentang menggunakan SecureString, lihat dokumentasi kelas System.Security.SecureString.

Lihat Juga

Pedoman Pengembangan yang Diperlukan

Pedoman Pengembangan yang Sangat Didorong

Menulis Cmdlet Windows PowerShell