Bagikan melalui

Praktik terbaik untuk penulisan paket

  • Artikel

Panduan ini dimaksudkan untuk memberi penulis paket NuGet referensi ringan untuk membuat dan menerbitkan paket berkualitas tinggi. Ini terutama akan berfokus pada praktik terbaik khusus paket seperti metadata dan pengemasan. Untuk saran yang lebih mendalam untuk membangun pustaka berkualitas tinggi, lihat panduan pustaka sumber terbuka .NET.

Jenis rekomendasi

Setiap artikel menyajikan empat jenis rekomendasi: Lakukan, Pertimbangkan, Hindari, dan Jangan. Jenis rekomendasi menunjukkan seberapa dekat rekomendasi tersebut harus diikuti.

Anda hampir selalu harus mengikuti rekomendasi Lakukan. Contohnya:

✔️ DO menyertakan deskripsi singkat untuk paket Anda yang menjelaskan tujuannya.

Di sisi lain, Pertimbangkan rekomendasi umumnya harus diikuti, tetapi ada pengecualian yang sah untuk aturan:

✔️ PERTIMBANGKAN untuk memilih nama paket NuGet dengan awalan yang memenuhi kriteria reservasi awalan NuGet.

Rekomendasi Hindari yang menyebutkan hal-hal yang umumnya bukan ide yang baik, tetapi melanggar aturan tersebut terkadang masuk akal:

❌ HINDARI referensi paket NuGet yang menuntut versi yang spesifik.

Dan akhirnya, rekomendasi Jangan menunjukkan sesuatu yang hampir tidak boleh Anda lakukan:

❌ JANGAN gunakan LicenseUrl properti metadata.

Membuat paket NuGet

Cara terbaru yang direkomendasikan untuk membuat paket NuGet adalah dari proyek bergaya SDK. Properti proyek bergaya SDK, termasuk kerangka kerja target dan metadata paket, didefinisikan dalam file proyek.

Buat paket dari proyek gaya SDK Anda dengan menentukan properti dan pengemasan yang diperlukan di Visual Studio atau dotnet CLI.

✔️ BUAT proyek gaya SDK dan buat (paket) paket Anda menggunakan Visual Studio atau CLI dotnet.

Untuk panduan lebih rinci mengenai pembuatan paket termasuk alat klien yang diperlukan, contoh file proyek, dan perintah, lihat Membuat paket NuGet menggunakan dotnet CLI.

Untuk membantu memutuskan kerangka kerja .NET mana yang akan ditargetkan, lihat panduan terbaru kami untuk penargetan lintas platform.

Metadata paket

Metadata adalah komponen dasar dari paket NuGet apa pun. Kualitas metadata Anda dapat sangat memengaruhi ketercarian, kegunaan, dan kepercayaan paket Anda.

Di Visual Studio, cara yang disarankan untuk menentukan metadata paket adalah dengan menggunakan Paket Properti > Proyek > [Nama Proyek].

Elemen metadata paket juga dapat ditentukan langsung dalam file proyek.

Di bawah ini adalah pemetaan tabel dan menjelaskan elemen metadata paket yang tersedia:

Nama properti Visual Studio Nama properti file proyek/MSBuild Nama properti Nuspec Deskripsi
Package id PackageId id Nama paket atau pengidentifikasi.
Package version PackageVersion version Versi paket NuGet.
Authors Authors authors Daftar penulis paket yang dipisahkan koma, sering menggunakan "nama cantik" individu atau organisasi.
Description Description description Deskripsi paket.
Copyright Copyright copyright Detail hak cipta untuk paket.
Project URL PackageProjectUrl projectUrl URL untuk beranda proyek.
Icon File PackageIcon icon Jalur ke file gambar ikon paket.
README PackageReadmeFile readme Jalur ke file markdown README paket.
Repository URL RepositoryUrl repository url URL ke repositori tempat paket dibuat.
Repository type RepositoryType repository type Jenis repositori yang ditujukan ke URL repositori (yaitu "git").
Tags PackageTags tags Daftar tag dan kata kunci yang dibatasi spasi yang menjelaskan paket. Tag digunakan saat mencari paket.
Release notes PackageReleaseNotes releaseNotes Deskripsi perubahan yang dilakukan dalam rilis paket ini.
Licensing - Expression PackageLicenseExpression license type="expression" Ekspresi lisensi SPDX.
Licensing - File PackageLicenseFile license type="file" Jalur ke file lisensi kustom.

ID Paket

Jika Anda menerbitkan paket yang benar-benar baru:

✔️ DO memilih ID paket yang unik dan jelas berbeda dari paket yang ada pada NuGet.org.

Anda dapat memeriksa apakah ID paket unik dan dapat dibedakan dengan mencari ID di NuGet.org atau memeriksa apakah tautan berikut ada: https://www.nuget.org/packages/<nama> paket.

✔️ PERTIMBANGKAN untuk memilih nama paket NuGet dengan awalan yang memenuhi kriteria reservasi awalan NuGet.

Menyimpan ID awalan untuk paket Anda akan memungkinkan Anda mendapatkan tanda centang terverifikasi: image

Lihat dokumen reservasi awalan ID Paket untuk mempelajari lebih lanjut.

Versi Paket

✔️ PERTIMBANGKAN untuk menggunakan SemVer untuk membuat versi paket NuGet Anda.

Pada dasarnya, ini berarti menggunakan format Major.Minor.Patch[-prerelease].

✔️ DO menerbitkan paket sebagai paket pra-rilis jika tidak stabil atau pratinjau.

Lihat panduan penerapan versi pustaka .NET untuk panduan lebih lanjut.

Penulis

✔️ DO menggunakan bidang penulis untuk "nama cantik" organisasi Anda atau Anda.

Misalnya, jika nama pengguna NuGet.org saya adalah "jdoe" maka menggunakan "Jane Doe" untuk bidang penulis dapat membantu konsumen mengenali saya sebagai penulis. Jika nama pengguna NuGet.org organisasi saya adalah "ContosoToolkit" maka menggunakan "Contoso Corporation" mungkin lebih dikenali dan menginspirasi lebih banyak kepercayaan konsumen.

Deskripsi

✔️ DO menyertakan deskripsi singkat (hingga 4000 karakter) untuk menjelaskan paket Anda.

Deskripsi paket adalah salah satu bidang paling menonjol yang muncul dalam pencarian NuGet dan kemungkinan akan menjadi hal pertama yang dilihat konsumen potensial untuk menentukan apakah paket tepat untuk mereka.

✔️ DO menambahkan pemberitahuan hak cipta ke paket Anda dengan "Hak Cipta (c) <nama/tahun> perusahaan><."

Pemberitahuan hak cipta pada dasarnya menunjukkan bahwa pekerjaan Anda tidak dapat disalin tanpa izin Anda. Termasuk pemberitahuan hak cipta dalam paket Anda mudah dan tidak akan membahayakan!

Contoh: Hak Cipta (c) Contoso 2020

URL Proyek

✔️ DO menyertakan tautan ke proyek, repositori, atau situs web perusahaan terkait.

Situs proyek Anda harus memiliki semua yang perlu diketahui pengguna tentang paket Anda dan kemungkinan akan menjadi tempat pengguna mencari dokumentasi.

Ikon

✔️ PERTIMBANGKAN menyertakan ikon dengan paket Anda untuk membantu membedakannya secara visual. Ini adalah tambahan yang relatif kecil yang dapat meningkatkan persepsi kualitas paket.

Ikon dapat dikhususkan untuk paket individual atau menjadi logo merek.

✔️ DO menggunakan gambar 128x128 dan memiliki latar belakang transparan (PNG) untuk melihat hasil terbaik.

NuGet akan secara otomatis menskalakan gambar Anda ke klien tempat gambar ditampilkan.

❌ JANGAN gunakan properti metadata yang tidak digunakan IconUrl lagi.

README

✔️ DO menambahkan file markdown README yang memberikan gambaran umum tentang apa yang dilakukan paket Anda dan cara memulai.

README paket akan secara signifikan meningkatkan persepsi kualitas paket Anda serta onboarding pengguna baru. Pertimbangkan juga untuk mempratinjau README Anda sebelum mengunggahnya! Lihat cara menyertakan file README dalam paket NuGet Anda untuk detail selengkapnya.

Jenis repositori dan URL

✔️ PERTIMBANGKAN untuk menyiapkan Source Link untuk menambahkan metadata kontrol sumber secara otomatis ke paket NuGet Anda dan membuat pustaka Anda lebih mudah di-debug.

Tautan Sumber secara otomatis menambahkan Repository URL dan Repository Type ke metadata paket. Ini juga menambahkan penerapan spesifik yang terkait dengan versi paket Anda.

Tag

✔️ DO menyertakan beberapa tag dengan istilah utama yang terkait dengan paket Anda untuk meningkatkan penemuan.

Tag diperhitungkan dalam algoritma pencarian NuGet.org dan sangat membantu untuk istilah yang tidak ada dalam ID Paket tetapi relevan.

Misalnya, jika saya menerbitkan paket untuk mencatat string ke konsol, saya akan menyertakan: "pengelogan, log, konsol, string, output"

Catatan rilis

✔️ DO menyertakan catatan rilis dengan setiap pembaruan yang menjelaskan perubahan apa yang dibuat.

Meskipun tidak ada format khusus yang diperlukan untuk catatan rilis, kami sarankan termasuk:

  1. Perubahan mencolok
  2. Fitur baru
  3. Perbaikan bug

Jika Anda sudah melacak catatan rilis atau changelog di repositori, Anda juga dapat menyertakan tautan ke file yang relevan.

Pelisensian

✔️ DO menyertakan ekspresi lisensi atau file lisensi dalam paket Anda.

Penting

Proyek tanpa lisensi default untuk hak cipta eksklusif, yang berarti Anda belum memberikan izin kepada siapa pun untuk menggunakan proyek Anda.

❌ JANGAN gunakan properti metadata yang tidak digunakan LicenseUrl lagi.

Ini menyajikan ambiguitas hukum karena perubahan lisensi di URL akan secara surut mengubah lisensi yang ditampilkan untuk versi paket sebelumnya.

Jika paket Anda sumber terbuka

✔️ PILIH lisensi sumber terbuka untuk membuat paket Anda sumber terbuka.

"Lisensi sumber terbuka adalah lisensi yang mematuhi Definisi Sumber Terbuka — secara singkat, lisensi tersebut memungkinkan perangkat lunak untuk digunakan, dimodifikasi, dan dibagikan secara bebas." - Inisiatif Sumber Terbuka. Untuk mempelajari selengkapnya tentang perangkat lunak sumber terbuka dan Inisiatif Sumber Terbuka, lihat https://opensource.org/.

✔️ PERTIMBANGKAN menyertakan ekspresi lisensi dalam paket Anda.

Ekspresi lisensi muncul dengan paling jelas dan membuatnya lebih jelas bagi konsumen jika mereka dapat menggunakan paket Anda atau jika lisensi telah berubah.

Catatan

NuGet.org hanya menerima ekspresi lisensi untuk lisensi yang disetujui oleh Open Source Initiative atau Free Software Foundation.

Jika paket Anda tidak sumber terbuka

✔️ DO menyertakan file lisensi dalam paket Anda.

File lisensi apa pun (.txt atau .md) dapat ditambahkan ke paket Anda, termasuk lisensi non-standar.