Panduan Penerbitan dan Praktik Terbaik PowerShellGallery

  • Artikel

Artikel ini menjelaskan langkah-langkah yang direkomendasikan yang digunakan oleh tim Microsoft untuk memastikan paket yang diterbitkan ke Galeri PowerShell akan diadopsi secara luas dan memberikan nilai tinggi kepada pengguna, berdasarkan cara Galeri PowerShell menangani data manifes dan umpan balik dari sejumlah besar pengguna Galeri PowerShell. Paket yang diterbitkan mengikuti panduan ini akan lebih mungkin diinstal, dipercaya, dan menarik lebih banyak pengguna.

Disertakan di bawah ini adalah panduan untuk apa yang membuat paket Galeri PowerShell yang baik, pengaturan Manifes opsional apa yang paling penting, meningkatkan kode Anda dengan umpan balik dari peninjau awal dan Powershell Script Analyzer, membuat versi modul, dokumentasi, pengujian, dan contoh tentang cara menggunakan apa yang telah Anda bagikan. Sebagian besar dokumentasi ini mengikuti panduan untuk menerbitkan Modul Sumber Daya DSC Berkualitas Tinggi.

Untuk mekanisme penerbitan paket ke Galeri PowerShell, lihat Membuat dan Menerbitkan Paket.

Umpan balik tentang pedoman ini disambut. Jika Anda memiliki umpan balik, silakan buka masalah di repositori dokumentasi GitHub kami.

Praktik terbaik untuk menerbitkan paket

Praktik terbaik berikut adalah apa yang dikatakan pengguna item Galeri PowerShell penting, dan tercantum dalam urutan prioritas nominal. Paket yang mengikuti pedoman ini jauh lebih mungkin diunduh dan diadopsi oleh orang lain.

  • Menggunakan PSScriptAnalyzer
  • Sertakan dokumentasi dan contoh
  • Responsif terhadap umpan balik
  • Menyediakan modul daripada skrip
  • Menyediakan tautan ke situs proyek
  • Tandai paket Anda dengan PSEdition dan platform yang kompatibel
  • Sertakan pengujian dengan modul Anda
  • Sertakan dan/atau tautkan ke ketentuan lisensi
  • Tanda tangani kode Anda
  • Ikuti panduan SemVer untuk penerapan versi
  • Gunakan tag umum, seperti yang didokumenkan dalam tag Galeri PowerShell Umum
  • Menguji penerbitan menggunakan repositori lokal
  • Menggunakan PowerShellGet untuk menerbitkan

Masing-masing dibahas secara singkat di bagian di bawah ini.

Menggunakan PSScriptAnalyzer

PSScriptAnalyzer adalah alat analisis kode statis gratis yang berfungsi pada kode PowerShell. PSScriptAnalyzer akan mengidentifikasi masalah paling umum yang terlihat dalam kode PowerShell, dan seringkali rekomendasi tentang cara memperbaiki masalah. Alat ini mudah digunakan, dan mengategorikan masalah sebagai Kesalahan (parah, harus ditangani), Peringatan (perlu ditinjau dan harus ditangani), dan Informasi (layak diperiksa untuk praktik terbaik). Semua paket yang diterbitkan ke Galeri PowerShell akan dipindai menggunakan PSScriptAnalyzer, dan kesalahan apa pun akan dilaporkan kembali ke pemilik dan harus ditangani.

Praktik terbaik adalah menjalankan Invoke-ScriptAnalyzer dengan -Recurse dan -Severity Peringatan.

Tinjau hasilnya, dan pastikan bahwa:

  • Semua Kesalahan dikoreksi atau ditangani dalam dokumentasi Anda.
  • Semua Peringatan ditinjau, dan ditangani jika berlaku.

Pengguna yang mengunduh paket dari Galeri PowerShell sangat dianjurkan untuk menjalankan PSScriptAnalyzer dan mengevaluasi semua Kesalahan dan Peringatan. Pengguna sangat mungkin menghubungi pemilik paket jika mereka melihat ada kesalahan yang dilaporkan oleh PSScriptAnalyzer. Jika ada alasan yang menarik bagi paket Anda untuk menyimpan kode yang ditandai sebagai kesalahan, tambahkan informasi tersebut ke dokumentasi Anda untuk menghindari harus menjawab pertanyaan yang sama berkali-kali.

Sertakan dokumentasi dan contoh

Dokumentasi dan contoh adalah cara terbaik untuk memastikan pengguna dapat memanfaatkan kode bersama apa pun.

Dokumentasi adalah hal yang paling membantu untuk disertakan dalam paket yang diterbitkan ke Galeri PowerShell. Pengguna umumnya akan melewati paket tanpa dokumentasi, karena alternatifnya adalah membaca kode untuk memahami apa itu paket dan cara menggunakannya. Ada beberapa artikel yang tersedia tentang cara menyediakan dokumentasi dengan paket PowerShell, termasuk:

  • Panduan untuk memberikan bantuan ada di Cara Menulis Bantuan Cmdlet.
  • Membuat bantuan cmdlet, yang merupakan pendekatan terbaik untuk skrip, fungsi, atau cmdlet PowerShell apa pun. Untuk informasi tentang cara membuat bantuan cmdlet, mulailah dengan Cara Menulis Bantuan Cmdlet. Untuk menambahkan bantuan dalam skrip, lihat Tentang Bantuan Berbasis Komentar.
  • Banyak modul juga menyertakan dokumentasi dalam format teks, seperti file MarkDown. Ini bisa sangat membantu ketika ada situs proyek di GitHub, di mana Markdown adalah format yang sangat digunakan. Praktik terbaik adalah menggunakan Markdown rasa GitHub.

Contoh menunjukkan kepada pengguna bagaimana paket dimaksudkan untuk digunakan. Banyak pengembang akan mengatakan bahwa mereka melihat contoh sebelum dokumentasi untuk memahami cara menggunakan sesuatu. Jenis contoh terbaik menunjukkan penggunaan dasar, ditambah kasus penggunaan realistis yang disimulasikan, dan kode dikomentari dengan baik. Contoh untuk modul yang diterbitkan ke Galeri PowerShell harus berada di folder Contoh di bawah akar modul.

Pola yang baik untuk contoh dapat ditemukan di modul PSDscResource di Examples\RegistryResource bawah folder . Ada empat contoh kasus penggunaan dengan deskripsi singkat di bagian atas setiap file yang mendokumentasikan apa yang sedang ditunjukkan.

Mengelola Dependensi

Penting untuk menentukan modul yang bergantung pada modul Anda dalam Manifes Modul. Ini memungkinkan pengguna akhir untuk tidak perlu khawatir tentang menginstal versi modul yang tepat yang menjadi dependensi Anda. Untuk menentukan modul dependen, Anda harus menggunakan bidang modul yang diperlukan dalam manifes modul. Ini akan memuat modul yang tercantum ke lingkungan global sebelum mengimpor modul Anda kecuali modul telah dimuat. Misalnya, beberapa modul mungkin sudah dimuat oleh modul yang berbeda. Anda juga dapat menentukan versi tertentu untuk dimuat menggunakan bidang RequiredVersion daripada bidang ModuleVersion . Saat menggunakan ModuleVersion, moduleVersion akan memuat versi terbaru yang tersedia dengan minimal versi yang ditentukan. Saat tidak menggunakan bidang RequiredVersion , untuk menentukan versi tertentu, penting untuk memantau pembaruan versi ke modul yang diperlukan. Sangat penting untuk mengetahui setiap perubahan yang melanggar yang dapat memengaruhi pengalaman pengguna dengan modul Anda.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Menanggapi umpan balik

Pemilik paket yang merespons umpan balik dengan benar sangat dihargai oleh komunitas. Pengguna yang memberikan umpan balik konstruktif penting untuk ditanggapi, karena mereka cukup tertarik pada paket untuk mencoba membantu meningkatkannya.

Ada satu metode umpan balik yang tersedia di Galeri PowerShell:

  • Pemilik Kontak: Ini memungkinkan pengguna untuk mengirim email ke pemilik paket. Sebagai pemilik paket, penting untuk memantau alamat email yang digunakan dengan paket Galeri PowerShell, dan menanggapi masalah yang diangkat. Salah satu kerugian dari metode ini adalah bahwa hanya pengguna dan pemilik yang akan melihat komunikasi, sehingga pemilik mungkin harus menjawab pertanyaan yang sama berkali-kali.

Pemilik yang menanggapi umpan balik secara konstruktif dihargai oleh komunitas. Gunakan kesempatan dalam laporan untuk meminta informasi lebih lanjut. Jika diperlukan, berikan solusi sementara, atau identifikasi apakah pembaruan memperbaiki masalah.

Jika ada perilaku yang tidak pantas yang diamati dari salah satu saluran komunikasi ini, gunakan fitur Laporkan Penyalahgunaan Galeri PowerShell untuk menghubungi Administrator Galeri.

Modul Versus Skrip

Berbagi skrip dengan pengguna lain sangat bagus, dan memberi orang lain contoh cara menyelesaikan masalah yang mungkin mereka miliki. Masalahnya adalah bahwa skrip di Galeri PowerShell adalah file tunggal tanpa dokumentasi, contoh, dan pengujian terpisah.

Modul PowerShell memiliki struktur folder yang memungkinkan beberapa folder dan file disertakan dengan paket. Struktur modul memungkinkan termasuk paket lain yang kami cantumkan sebagai praktik terbaik: bantuan cmdlet, dokumentasi, contoh, dan pengujian. Kerugian terbesar adalah bahwa skrip di dalam modul harus diekspos dan digunakan sebagai fungsi. Untuk informasi tentang cara membuat modul, lihat Menulis Modul Windows PowerShell.

Ada situasi di mana skrip memberikan pengalaman yang lebih baik bagi pengguna, terutama dengan konfigurasi DSC. Praktik terbaik untuk konfigurasi DSC adalah menerbitkan konfigurasi sebagai skrip dengan modul yang menyertainya yang berisi dokumen, contoh, dan pengujian. Skrip mencantumkan modul yang menyertainya menggunakan RequiredModules = @(Name of the Module). Pendekatan ini dapat digunakan dengan skrip apa pun.

Skrip mandiri yang mengikuti praktik terbaik lainnya memberikan nilai nyata kepada pengguna lain. Menyediakan dokumentasi berbasis komentar dan tautan ke Situs Proyek sangat disarankan saat menerbitkan skrip ke Galeri PowerShell.

Situs Proyek adalah tempat penerbit dapat berinteraksi langsung dengan pengguna paket Galeri PowerShell mereka. Pengguna lebih suka paket yang menyediakan ini, karena memungkinkan mereka untuk mendapatkan informasi tentang paket dengan lebih mudah. Banyak paket di Galeri PowerShell dikembangkan di GitHub, yang lain disediakan oleh organisasi dengan kehadiran web khusus. Masing-masing dapat dianggap sebagai situs proyek.

Menambahkan tautan dilakukan dengan menyertakan ProjectURI di bagian PSData dari manifes sebagai berikut:

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

Saat ProjectURI disediakan, Galeri PowerShell akan menyertakan tautan ke Situs Proyek di sisi kiri halaman paket.

Tandai paket Anda dengan PSEdition dan platform yang kompatibel

Gunakan tag berikut untuk menunjukkan kepada pengguna paket mana yang akan bekerja dengan baik dengan lingkungan mereka:

  • PSEdition_Desktop: Paket yang kompatibel dengan Windows PowerShell
  • PSEdition_Core: Paket yang kompatibel dengan PowerShell 6 dan yang lebih tinggi
  • Windows: Paket yang kompatibel dengan Sistem Operasi Windows
  • Linux: Paket yang kompatibel dengan Sistem Operasi Linux
  • MacOS: Paket yang kompatibel dengan Sistem Operasi Mac

Dengan menandai paket Anda dengan platform yang kompatibel, paket tersebut akan disertakan dalam filter pencarian Galeri di panel kiri hasil pencarian. Jika Anda menghosting paket di GitHub, saat menandai paket, Anda juga dapat memanfaatkan contoh perisai kompatibilitas Perisai kompatibilitas Galeri PowerShell kami.

Sertakan pengujian

Termasuk pengujian dengan kode sumber terbuka penting bagi pengguna, karena memberi mereka jaminan tentang apa yang Anda validasi, dan memberikan informasi tentang cara kerja kode Anda. Ini juga memungkinkan pengguna untuk memastikan mereka tidak merusak fungsionalitas asli Anda jika mereka memodifikasi kode Anda agar sesuai dengan lingkungan mereka.

Sangat disarankan agar pengujian ditulis untuk memanfaatkan kerangka kerja pengujian Pester, yang telah dirancang khusus untuk PowerShell. Pester tersedia di GitHub, Galeri PowerShell, dan dikirim di Windows 10, Windows Server 2016, WMF 5.0 dan WMF 5.1.

Situs proyek Pester di GitHub mencakup dokumentasi yang baik tentang menulis tes Pester, mulai dari memulai hingga praktik terbaik.

Target untuk cakupan pengujian dipanggil dalam dokumentasi Modul Sumber Daya Berkualitas Tinggi, dengan cakupan kode pengujian unit 70% direkomendasikan.

Semua paket yang diterbitkan ke Galeri PowerShell harus menentukan persyaratan lisensi, atau terikat oleh lisensi yang disertakan dalam Ketentuan Penggunaan di bawah Pameran A. Pendekatan terbaik untuk menentukan lisensi yang berbeda adalah menyediakan tautan ke lisensi menggunakan LicenseURI di PSData. Untuk informasi selengkapnya, lihat Manifes paket dan UI Galeri.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Tanda tangani kode Anda

Penandatanganan kode memberi pengguna tingkat jaminan tertinggi untuk siapa yang menerbitkan paket, dan bahwa salinan kode yang mereka peroleh persis seperti yang dirilis penerbit. Untuk mempelajari selengkapnya tentang penandatanganan kode secara umum, lihat Pengantar Penandatanganan Kode. PowerShell mendukung validasi penandatanganan kode melalui dua pendekatan utama:

  • Menandatangani file skrip
  • Penandatanganan katalog modul

Menandatangani file PowerShell adalah pendekatan yang mapan untuk memastikan bahwa kode yang dijalankan diproduksi oleh sumber yang andal, dan belum dimodifikasi. Detail tentang cara menandatangani file skrip PowerShell tercakup dalam artikel Tentang Penandatanganan . Dalam gambaran umum, tanda tangan dapat ditambahkan ke file apa pun .PS1 yang divalidasi PowerShell saat skrip dimuat. PowerShell dapat dibatasi menggunakan cmdlet Kebijakan Eksekusi untuk memastikan penggunaan skrip yang ditandatangani.

Modul penandatanganan katalog adalah fitur yang ditambahkan ke PowerShell di versi 5.1. Cara menandatangani modul tercakup dalam artikel Cmdlet Katalog . Dalam gambaran umum, penandatanganan katalog dilakukan dengan membuat file katalog, yang berisi nilai hash untuk setiap file dalam modul, lalu menandatangani file tersebut.

Cmdlet PowerShellGetPublish-Module, Install-Module, dan Update-Module akan memeriksa tanda tangan untuk memastikannya valid, lalu mengonfirmasi bahwa nilai hash untuk setiap paket cocok dengan apa yang ada di katalog. Save-Module tidak memvalidasi tanda tangan. Jika versi modul sebelumnya diinstal pada sistem, Install-Module akan mengonfirmasi bahwa otoritas penandatanganan untuk versi baru cocok dengan apa yang sebelumnya diinstal. Install-Module dan Update-Module akan menggunakan tanda tangan pada .PSD1 file jika paket tidak ditandatangani katalog. Penandatanganan katalog berfungsi dengan, tetapi tidak menggantikan file skrip penandatanganan. PowerShell tidak memvalidasi tanda tangan katalog pada waktu pemuatan modul.

Ikuti panduan SemVer untuk penerapan versi

SemVer adalah konvensi publik yang menjelaskan cara menyusun dan mengubah versi untuk memungkinkan interpretasi perubahan yang mudah. Versi untuk paket Anda harus disertakan dalam data manifes.

  • Versi harus disusun sebagai tiga blok numerik yang dipisahkan oleh titik, seperti dalam 0.1.1 atau 4.11.192.
  • Versi yang dimulai dengan 0 menunjukkan bahwa paket belum siap produksi, dan angka pertama hanya boleh dimulai dengan 0 jika itu satu-satunya angka yang digunakan.
  • Perubahan pada angka pertama (1.9.9999 ke 2.0.0) menunjukkan perubahan besar dan memutus antara versi.
  • Perubahan pada angka kedua (1.1 ke 1.2) menunjukkan perubahan tingkat fitur, seperti menambahkan cmdlet baru ke modul.
  • Perubahan pada angka ketiga menunjukkan perubahan yang tidak melanggar, seperti parameter baru, sampel yang diperbarui, atau pengujian baru.
  • Saat mencantumkan versi, PowerShell akan mengurutkan versi sebagai string, sehingga 1.01.0 akan diperlakukan lebih besar dari 1.001.0.

PowerShell dibuat sebelum SemVer diterbitkan, sehingga memberikan dukungan untuk sebagian besar tetapi tidak semua elemen SemVer, khususnya:

  • Ini tidak mendukung string prarilis dalam nomor versi. Ini berguna ketika penerbit ingin memberikan rilis pratinjau versi utama baru setelah memberikan versi 1.0.0. Ini akan didukung dalam rilis powerShell Gallery dan cmdlet PowerShellGet di masa mendatang.
  • PowerShell dan Galeri PowerShell memungkinkan string versi dengan 1, 2, dan 4 segmen. Banyak modul awal tidak mengikuti panduan, dan rilis produk dari Microsoft menyertakan informasi build sebagai blok angka ke-4 (misalnya 5.1.14393.1066). Dari sudut pendapat penerapan versi, perbedaan ini diabaikan.

Uji menggunakan repositori lokal

Galeri PowerShell tidak dirancang untuk menjadi target untuk menguji proses penerbitan. Cara terbaik untuk menguji proses penerbitan end-to-end ke Galeri PowerShell adalah dengan menyiapkan dan menggunakan repositori lokal Anda sendiri. Ini dapat dilakukan dengan beberapa cara, termasuk:

  • Siapkan instans Galeri PowerShell lokal, menggunakan proyek Galeri Privat PS di GitHub. Proyek pratinjau ini akan membantu Anda menyiapkan instans Galeri PowerShell yang dapat Anda kontrol, dan gunakan untuk pengujian Anda.
  • Siapkan repositori Nuget internal. Ini akan memerlukan lebih banyak pekerjaan untuk disiapkan, tetapi akan memiliki keuntungan memvalidasi beberapa persyaratan lagi, terutama memvalidasi penggunaan kunci API, dan apakah dependensi ada di target saat Anda menerbitkan.
  • Siapkan berbagi file sebagai repositori pengujian. Ini mudah disiapkan, tetapi karena ini adalah berbagi file, validasi yang disebutkan di atas tidak akan berlangsung. Salah satu keuntungan potensial dalam hal ini adalah bahwa berbagi file tidak memeriksa kunci API yang diperlukan, sehingga Anda dapat menggunakan kunci yang sama dengan yang akan Anda gunakan untuk menerbitkan ke Galeri PowerShell.

Dengan salah satu solusi ini, gunakan Register-PSRepository untuk menentukan repositori baru, yang Anda gunakan dalam -Repository parameter untuk Publish-Module.

Satu poin tambahan tentang penerbitan pengujian: paket apa pun yang Anda terbitkan ke Galeri PowerShell tidak dapat dihapus tanpa bantuan dari tim operasi, yang akan mengonfirmasi bahwa tidak ada yang bergantung pada paket yang ingin Anda terbitkan. Untuk alasan itu, kami tidak mendukung Galeri PowerShell sebagai target pengujian, dan akan menghubungi penerbit mana pun yang melakukannya.

Menggunakan PowerShellGet untuk menerbitkan

Sangat disarankan agar penerbit menggunakan Publish-Module cmdlet dan Publish-Script saat bekerja dengan Galeri PowerShell. PowerShellGet dibuat untuk membantu Anda menghindari mengingat detail penting tentang menginstal dari dan menerbitkan ke Galeri PowerShell. Terkadang, penerbit telah memilih untuk melewati PowerShellGet dan menggunakan klien NuGet , atau cmdlet PackageManagement , bukan Publish-Module. Ada sejumlah detail yang mudah dilewatkan, yang menghasilkan berbagai permintaan dukungan.

Jika ada alasan bahwa Anda tidak dapat menggunakan Publish-Module atau Publish-Script, harap beri tahu kami. Ajukan masalah di repositori PowerShellGet GitHub, dan berikan detail yang menyebabkan Anda memilih NuGet atau PackageManagement.

Pendekatan paling sukses yang kami temukan untuk paket yang diterbitkan ke Galeri PowerShell adalah ini:

  • Lakukan pengembangan awal di situs proyek sumber terbuka. Tim PowerShell menggunakan GitHub.
  • Gunakan umpan balik dari peninjau dan PowerShell Script Analyzer untuk mendapatkan kode ke status stabil.
  • Sertakan dokumentasi, sehingga orang lain tahu cara menggunakan pekerjaan Anda.
  • Uji tindakan penerbitan menggunakan repositori lokal.
  • Terbitkan rilis stabil atau Alfa ke Galeri PowerShell, pastikan untuk menyertakan dokumentasi dan tautan ke situs proyek Anda.
  • Kumpulkan umpan balik dan ulangi kode di situs proyek Anda, lalu terbitkan pembaruan stabil ke Galeri PowerShell.
  • Tambahkan contoh dan pengujian Pester dalam proyek dan modul Anda.
  • Putuskan apakah Anda ingin menandatangani kode paket Anda.
  • Saat Anda merasa proyek siap digunakan di lingkungan produksi, terbitkan 1.0.0 versi ke Galeri PowerShell.
  • Terus kumpulkan umpan balik dan ulangi kode Anda berdasarkan input pengguna.