Membuat dan menerbitkan item

  • Artikel

Galeri PowerShell adalah tempat untuk menerbitkan dan berbagi sumber daya modul PowerShell, skrip, dan Desired State Configuration (DSC) yang stabil dengan komunitas pengguna PowerShell yang lebih luas.

Artikel ini membahas mekanisme dan langkah-langkah penting untuk menyiapkan skrip atau modul, dan menerbitkannya ke Galeri PowerShell. Kami sangat mendorong Anda meninjau Panduan Penerbitan untuk memahami cara memastikan bahwa item yang Anda terbitkan akan lebih diterima secara luas oleh pengguna Galeri PowerShell.

Persyaratan minimum untuk menerbitkan item ke Galeri PowerShell adalah:

  • Memiliki akun Galeri PowerShell, dan Kunci API yang terkait dengannya
  • Pastikan Metadata yang Diperlukan ada di item Anda
  • Gunakan alat pra-validasi untuk memastikan item Anda siap diterbitkan
  • Menerbitkan item ke Galeri PowerShell menggunakan perintah Publish-Module dan Publish-Script
  • Menanggapi pertanyaan atau kekhawatiran tentang item Anda

Galeri PowerShell menerima modul PowerShell dan skrip PowerShell. Ketika kita merujuk ke skrip, kita berarti skrip PowerShell yang merupakan satu file, dan bukan bagian dari modul yang lebih besar.

Lihat Membuat Akun Galeri PowerShell untuk cara menyiapkan akun Galeri PowerShell Anda.

Setelah membuat akun, Anda bisa mendapatkan Kunci API yang diperlukan untuk menerbitkan item. Setelah Anda masuk dengan akun, nama pengguna Anda akan ditampilkan di bagian atas halaman Galeri PowerShell alih-alih Daftar. Mengklik nama pengguna Anda akan membawa Anda ke halaman Akun Saya, tempat Anda akan menemukan Kunci API.

Penting

Kunci API harus diperlakukan seaman login dan kata sandi Anda. Dengan kunci ini, Anda, atau orang lain, dapat memperbarui item apa pun yang Anda miliki di Galeri PowerShell. Sebaiknya perbarui kunci secara teratur, yang dapat dilakukan menggunakan Kunci Reset di halaman Akun Saya.

Galeri PowerShell menyediakan informasi kepada pengguna galeri yang diambil dari bidang metadata yang disertakan dalam manifes skrip atau modul. Membuat atau memodifikasi item untuk publikasi ke Galeri PowerShell memiliki seperangkat persyaratan kecil untuk informasi yang disediakan dalam manifes item. Kami sangat mendorong Anda meninjau bagian Metadata Item dari Panduan Penerbitan untuk mempelajari cara memberikan informasi terbaik kepada pengguna dengan item Anda.

Cmdlet New-ModuleManifest dan New-ScriptFileInfo akan membuat templat manifes untuk Anda, dengan tempat penampung untuk semua elemen manifes.

Kedua manifes memiliki dua bagian yang penting untuk penerbitan, data kunci primer dan area PSData PrivateData. Data kunci utama dalam manifes modul PowerShell adalah semuanya di luar bagian PrivateData. Kumpulan kunci primer terkait dengan versi PowerShell yang digunakan, dan tidak terdefinisi tidak didukung. PrivateData mendukung penambahan kunci baru, sehingga elemen khusus untuk Galeri PowerShell ada di PSData.

Elemen manifes yang paling penting untuk diisi untuk item yang Anda terbitkan ke Galeri PowerShell adalah:

  • Nama Skrip atau Modul - Nama tersebut diambil dari nama .PS1 untuk skrip, atau . PSD1 untuk modul.
  • Versi - ini adalah kunci primer yang diperlukan, format harus mengikuti panduan SemVer. Lihat Praktik Terbaik untuk detailnya.
  • Penulis - ini adalah kunci primer yang diperlukan, dan berisi nama yang akan dikaitkan dengan item. Lihat Penulis dan Pemilik di bawah ini.
  • Deskripsi - ini adalah kunci primer yang diperlukan, digunakan untuk menjelaskan secara singkat apa yang dilakukan item ini dan persyaratan apa pun untuk menggunakannya
  • ProjectURI - ini adalah bidang URI yang sangat direkomendasikan di PSData yang menyediakan tautan ke repositori GitHub atau lokasi serupa tempat Anda melakukan pengembangan pada item
  • Tag - ini adalah rekomendasi yang kuat untuk menandai paket Anda berdasarkan kompatibilitasnya dengan PSEditions dan platform. Untuk detailnya, lihat Panduan Penerbitan.

Penulis dan Pemilik item Galeri PowerShell adalah konsep terkait, tetapi tidak selalu cocok. Pemilik Item adalah pengguna dengan akun Galeri PowerShell yang memiliki izin untuk mempertahankan item. Mungkin ada banyak Pemilik yang dapat memperbarui item apa pun. Pemilik hanya tersedia dari Galeri PowerShell, dan hilang jika item disalin dari satu sistem ke sistem lainnya. Penulis adalah string yang dibangun ke dalam data manifes, sehingga selalu menjadi bagian dari item. Rekomendasi untuk item dari produk Microsoft adalah:

  • Memiliki beberapa pemilik, dengan setidaknya satu menjadi nama tim yang menghasilkan item
  • Minta Penulis menjadi nama tim terkenal (seperti Tim Azure SDK), atau Microsoft Corporation

Pra-validasi item Anda

Ada beberapa alat yang perlu Anda jalankan terhadap kode Anda sebelum menerbitkan item Anda ke Galeri PowerShell:

  • PowerShell Script Analyzer, yang ada di Galeri PowerShell
  • Untuk modul, Test-ModuleManifest yang merupakan bagian dari PowerShell
  • Untuk skrip, Test-ScriptFileInfo yang dilengkapi dengan PowerShell Get

PowerShell Script Analyzer adalah alat analisis kode statis yang akan memindai kode Anda untuk memastikan kode tersebut memenuhi panduan pengodean PowerShell dasar. Alat ini akan mengidentifikasi masalah umum dan kritis dalam kode Anda, dan harus dijalankan secara teratur selama pengembangan untuk membantu Anda menyiapkan item Anda untuk diterbitkan. PowerShell Script Analyzer akan menyediakan daftar masalah yang diidentifikasi sebagai Kesalahan, Peringatan, dan Informasi. Semua kesalahan harus diatasi sebelum Anda menerbitkan ke Galeri PowerShell. Peringatan perlu ditinjau, dan sebagian besar harus ditangani. PowerShell Script Analyzer dijalankan setiap kali item diterbitkan atau diperbarui di Galeri PowerShell. Tim Operasi Galeri akan menghubungi pemilik item untuk mengatasi kesalahan yang ditemukan.

Jika informasi manifes dalam item Anda tidak dapat dibaca oleh infrastruktur Galeri PowerShell, Anda tidak akan dapat menerbitkan. Test-ModuleManifest akan menangkap masalah umum yang akan menyebabkan modul tidak dapat digunakan saat diinstal. Ini harus dijalankan untuk setiap modul sebelum menerbitkannya ke Galeri PowerShell.

Demikian juga, Test-ScriptFileInfo memvalidasi metadata dalam skrip, dan harus dijalankan pada setiap skrip (diterbitkan terpisah dari modul) sebelum menerbitkannya ke Galeri PowerShell.

Menerbitkan Item

Anda harus menggunakan Publish-Script atau Publish-Module untuk menerbitkan item ke Galeri PowerShell. Perintah ini memerlukan:

  • Jalur ke item yang akan Anda terbitkan. Untuk modul, gunakan folder bernama untuk modul Anda. Jika Anda menentukan folder yang berisi beberapa versi modul yang sama, Anda harus menentukan RequiredVersion.
  • Kunci API Nuget. Ini adalah kunci API yang ditemukan di halaman Akun Saya di Galeri PowerShell.

Sebagian besar opsi lain di baris perintah harus berada dalam data manifes untuk item yang Anda terbitkan, jadi Anda tidak perlu menentukannya dalam perintah.

Untuk menghindari kesalahan, sangat disarankan agar Anda mencoba perintah menggunakan -WhatIf -Verbose, sebelum menerbitkan. Ini akan menghemat banyak waktu, karena setiap kali Anda menerbitkan ke Galeri PowerShell, Anda harus memperbarui nomor versi di bagian manifes item.

Contohnya adalah:

  • Publish-Module -Path ".\MyModule" -NugetAPIKey "GUID" -WhatIf -Verbose
  • Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -WhatIf -Verbose

Tinjau output dengan hati-hati, dan jika Anda tidak melihat kesalahan atau peringatan, ulangi perintah tanpa -WhatIf.

Semua item yang diterbitkan ke Galeri PowerShell akan dipindai untuk virus, dan akan dianalisis menggunakan PowerShell Script Analyzer. Setiap masalah yang muncul pada saat itu akan dikirim kembali ke penerbit untuk resolusi.

Setelah menerbitkan item ke Galeri PowerShell, Anda harus watch untuk umpan balik tentang item Anda.

  • Pastikan Anda memantau alamat email yang terkait dengan akun yang digunakan untuk menerbitkan. Pengguna, dan tim Operasi Galeri PowerShell akan memberikan umpan balik melalui akun tersebut, termasuk masalah dari pemindaian PSSA atau antivirus. Jika akun email tidak valid, atau jika masalah serius dilaporkan ke akun dan dibiarkan tidak terselesaikan untuk waktu yang lama, item dapat dianggap ditinggalkan dan akan dihapus dari Galeri PowerShell seperti yang dijelaskan dalam Ketentuan Penggunaan kami.