Aturan dan rekomendasi PSScriptAnalyzer

Panduan berikut berasal dari upaya gabungan dari tim PowerShell dan komunitas. Pedoman diatur berdasarkan jenis. Dalam setiap jenis, ada daftar aturan. Aturan dikelompokkan menurut Tingkat Keparahan yang ditentukan dalam implementasi aturan PSScriptAnalyzer . Tingkat keparahan yang diberi TBD label berarti "Akan ditentukan". Item yang diberi label sebagai TBD adalah rekomendasi yang saat ini tidak memiliki aturan yang ditentukan.

Aturan Desain Cmdlet

Tingkat keparahan: Kesalahan

Tidak ada aturan yang ditentukan.

Tingkat keparahan: Peringatan

• Hanya gunakan Kata Kerja yang Disetujui UseApprovedVerbs
• Nama cmdlet dengan karakter yang tidak dapat digunakan AvoidReservedCharInCmdlet
• Nama parameter yang tidak dapat digunakan AvoidReservedParams
• Permintaan konfirmasi dukungan UseShouldProcessForStateChangingFunctions dan UseSupportsShouldProcess
• Harus memanggil ShouldProcess ketika atribut ShouldProcess ada dan sebaliknya UseShouldProcess
• Kata benda harus tunggal UseSingularNouns
• Bidang manifes modul yang hilang missingModuleManifestField
  • Versi
  • Pengarang
  • Deskripsi
  • LicenseUri (untuk Galeri PowerShell)
• Parameter pengalihan tidak boleh default ke true AvoidDefaultValueSwitchParameter

Tingkat keparahan: Informasi

Tidak ada aturan yang ditentukan.

Tingkat keparahan: TBD

• Mendukung parameter Paksa untuk sesi interaktif. Jika cmdlet Anda digunakan secara interaktif, selalu berikan parameter Force untuk mengambil alih tindakan interaktif, seperti perintah atau baris baca input. Parameter Force penting karena memungkinkan cmdlet Anda digunakan dalam skrip dan host non-interaktif.
• Objek output dokumen
• Modul harus dapat dimuat
• Tidak ada kesalahan sintaks
• Dependensi yang tidak terselesaikan adalah kesalahan
• Berasal dari Kelas Cmdlet atau PSCmdlet
• Tentukan Atribut Cmdlet
• Mengesampingkan Metode Pemrosesan Input
• Tentukan Atribut OutputType
• Menulis rekaman tunggal ke alur
• Membuat cmdlet tidak peka huruf besar/kecil dan pelestarian huruf besar/kecil

Fungsi Skrip

Tingkat keparahan: Kesalahan

Tidak ada aturan yang ditentukan.

Tingkat keparahan: Peringatan

• Hindari menggunakan alias AvoidUsingCmdletAliases
• Hindari menggunakan cmdlet WMI yang tidak digunakan lagi AvoidUsingWMICmdlet
• Hindari menggunakan kosong menangkap blokAvoidUsingEmptyCatchBlock
• Panggil cmdlet yang ada dengan parameter yang benar UseCmdletCorrectly
• Cmdlet harus memiliki parameter ShouldProcess/ShouldContinue dan Force jika menggunakan kata kerja pengubahan sistem tertentu (Perbarui, Atur, Hapus, Baru): UseShouldProcessForStateChangingFunctions
• Hindari menggunakan parameter posisi AvoidUsingPositionalParameters
• Hindari menggunakan variabel global AvoidGlobalVars
• Variabel yang dideklarasikan harus digunakan setelah penugasannya UseDeclaredVarsMoreThanAssignments
• Hindari menggunakan Invoke-ExpressionAvoidUsingInvokeExpression

Tingkat keparahan: Informasi

Tidak ada aturan yang ditentukan.

Tingkat keparahan: TBD

• Hindari menggunakan Clear-Host
• Hindari menggunakan jalur file UNC
• Penanganan Kesalahan
  • Gunakan -ErrorAction Stop saat memanggil cmdlet
  • Gunakan $ErrorActionPreference set ke Stop atau Continue saat memanggil noncmdlet
  • Hindari menggunakan bendera untuk menangani kesalahan
  • Hindari menggunakan $?
  • Hindari pengujian untuk variabel null sebagai kondisi kesalahan
  • Salin $Error[0] ke variabel Anda sendiri
• Hindari menggunakan alur dalam skrip
• Jika jenis pengembalian dideklarasikan, cmdlet harus mengembalikan jenis tersebut. Jika jenis dikembalikan, jenis pengembalian harus dideklarasikan.

Gaya Pembuatan Skrip

Tingkat keparahan: Kesalahan

Tidak ada aturan yang ditentukan.

Tingkat keparahan: Peringatan

• Hindari menggunakan Write-Host kecuali menulis ke host adalah semua yang ingin Anda lakukan AvoidUsingWriteHost

Tingkat keparahan: Informasi

• Menulis bantuan berbasis komentar ProvideCommentHelp

Tingkat keparahan: TBD

• Berikan Contoh Penggunaan
• Gunakan bagian Catatan untuk detail tentang cara kerja alat
• Setiap perintah yang diekspor harus memiliki bantuan (termasuk dokumentasi parameter)
• Dokumentasikan versi PowerShell tempat skrip ditulis
• Inden kode Anda
• Hindari backtick

Keamanan Skrip

Tingkat keparahan: Kesalahan

• Hindari menggunakan kata sandi teks biasa AvoidUsingPlainTextForPassword
• Hindari parameter dan (gunakan PSCredential ): UsePSCredentialType
• Hindari hardcoding argumen parameter -ComputerName (pengungkapan informasi): AvoidUsingComputerNameHardcoded
• Hindari menggunakan ConvertTo-SecureString dengan teks biasa (pengungkapan informasi): AvoidUsingConvertToSecureStringWithPlainText

Tingkat keparahan: Peringatan

• Hindari menggunakan $Password = 'string' (pengungkapan informasi). AvoidUsingUsernameAndPasswordParams

Tingkat keparahan: Informasi

Tidak ada aturan yang ditentukan.

Tingkat keparahan: TBD

• Hindari menginisialisasi kunci API dan variabel kredensial (pengungkapan informasi)

Aturan Terkait DSC

Tingkat keparahan: Kesalahan

• Gunakan metode DSC standar StandardDSCFunctionsInResource
• Gunakan parameter wajib yang identik untuk semua metode DSC UseIdenticalMandatoryParametersForDSC
• Gunakan parameter identik untuk Metode Set and Test DSC UseIdenticalParametersForDSC

Tingkat keparahan: Peringatan

Tidak ada aturan yang ditentukan.

Tingkat keparahan: Informasi

• Tiga rekomendasi berikut dicakup oleh aturan ReturnCorrectTypesForDSCFunctions
  • Hindari mengembalikan objek apa pun dari fungsi Set-TargetResource atau Atur (Berbasis Kelas)
  • Mengembalikan nilai Boolean dari fungsi Test-TargetResource atau Uji (Berbasis Kelas)
  • Mengembalikan objek dari fungsi Get-TargetResource atau Dapatkan (Berbasis Kelas)
• Sumber daya DSC harus memiliki pengujian DSC DSCTestsPresent
• Sumber daya DSC harus memiliki contoh DSC DSCExamplesPresent

Tingkat keparahan: TBD

• Untuk Windows PowerShell v4, modul sumber daya harus memiliki .psd1 file dan schema.mof untuk setiap sumber daya
• Modul sumber daya harus memiliki file .psd1 (selalu) dan schema.mof (untuk sumber daya non-kelas) lihat Masalah #116
• Modul sumber daya harus memiliki folder DscResources yang berisi sumber daya - lihat Masalah #130
• MOF harus memiliki deskripsi untuk setiap elemen - lihat Masalah #131
• Menggunakan ShouldProcess untuk metode Set DSC

Referensi

• Pedoman Pengembangan Cmdlet
• Desain dan Pengujian Sumber Daya PowerShell DSC
• Pedoman DSC juga dapat ditemukan di Repositori Sumber Daya DSC
  • Panduan Gaya Sumber Daya DSC & Praktik Terbaik
  • Penamaan Sumber Daya DSC
  • Membuat Modul Sumber Daya DSC Berkualitas Tinggi
• Panduan Praktik Terbaik dan Gaya PowerShell Tidak Resmi