KAL
Menu

Publikasi Package

Membuat dan membagikan pustaka sendiri.

Daftar isi

Membagikan pustaka buatan sendiri sebagai package NuGet melibatkan tiga langkah, yaitu menulis pustaka bertipe class library, mengemasnya menjadi arsip .nupkg dengan dotnet pack, dan mengirim arsip itu ke repositori package dengan dotnet nuget push. Topik ini membangun pustaka kecil bernama KalkulatorPaket dari nol, melengkapi metadata package-nya, lalu mengemas dan mengirimkannya ke sumber lokal di folder. Langkah pengiriman ke nuget.org dijelaskan pada bagian akhir karena membutuhkan akun dan kunci API yang tidak tersedia di lingkungan latihan.

Membuat pustaka class library#

Class library adalah proyek yang tidak punya titik masuk Main, sehingga pustaka ini tidak dijalankan sendiri melainkan dimuat oleh aplikasi lain yang membutuhkannya. Proyek semacam itu dibuat dengan dotnet new classlib, dan pustaka contoh pada topik ini berisi satu kelas statis dengan satu fungsi penghitung kata. Kedua berkas yang menyusun proyeknya ditunjukkan di bawah, yaitu satu berkas kode dan satu berkas proyek, sehingga pustaka sekecil apa pun tetap berdiri sebagai proyek lengkap yang dapat dikompilasi.

csharp PenghitungKalkulator.cs 
namespace KalkulatorPaket;

public static class PenghitungKata
{
    public static int Hitung(string teks) =>
        teks.Split(' ', System.StringSplitOptions.RemoveEmptyEntries).Length;
}

Kata kunci public pada kelas dan metodenya menentukan bagian pustaka yang terlihat oleh pemakainya. Anggota yang tidak diberi public tetap terkompilasi ke dalam pustaka, tetapi tidak dapat dipanggil dari proyek lain, sehingga penempatan kata kunci ini adalah cara menata batas antarmuka pustaka. Nama namespace menyesuaikan nama package agar pencarian tipe oleh pemakai tetap alami, dan pemakai yang mengimpor KalkulatorPaket langsung menemukan kelas yang ditawarkan tanpa pembelajaran tambahan.

Metadata package pada berkas proyek#

Sifat package yang terbit dinyatakan sebagai properti pada berkas .csproj, dan properti-properti itu diteruskan menjadi manifest di dalam arsip .nupkg. Empat properti menentukan identitas package, yaitu PackageId sebagai nama uniknya, Version sebagai nomor rilisnya, Authors sebagai pembuatnya, dan Description sebagai penjelasan singkat yang tampil pada halaman package.

xml KalkulatorPaket.csproj 
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <PackageId>KalkulatorPaket</PackageId>
    <Version>1.0.0</Version>
    <Authors>Ali</Authors>
    <Description>Kumpulan fungsi penghitung kata untuk latihan publikasi package NuGet.</Description>
  </PropertyGroup>

</Project>

Apabila PackageId tidak dituliskan, nama berkas proyek dipakai sebagai gantinya, sedangkan Version bawaan bernilai 1.0.0. Identitas PackageId bersifat unik pada repositori tempat package diterbitkan, sehingga package dengan nama yang sudah diambil di nuget.org ditolak saat pengiriman. Deskripsi yang jelas membantu calon pemakai memahami isi package tanpa membuka kode sumbernya, dan nilai-nilai ini dapat diubah setiap rilis tanpa menyentuh kode pustaka sama sekali. Properti lain seperti RepositoryUrl dan License melengkapi halaman package pada repositori publik, tetapi keempat properti di ataslah yang menentukan identitas dasarnya.

Mengemas dengan dotnet pack#

Perintah dotnet pack mengompilasi pustaka lalu membungkus hasil kompilasi bersama manifestnya menjadi arsip .nupkg. Konfigurasi build yang dipakai adalah Release secara default, sehingga arsip yang dihasilkan sudah dioptimalkan. Contoh berikut menyalin proyek pustaka ke folder kerja sementara terlebih dahulu agar artefak build tidak menempel pada folder topik.

bash 
# aktifkan .NET yang terpasang di sandbox
export DOTNET_ROOT=/home/kal/.dotnet PATH=/home/kal/.dotnet:$PATH DOTNET_CLI_TELEMETRY_OPTOUT=1 DOTNET_NOLOGO=1
# siapkan folder kerja sementara dan salin proyek pustaka dari folder topik
rm -rf /tmp/cs-eko/publikasi
mkdir -p /tmp/cs-eko/publikasi
cp KalkulatorPaket.csproj PenghitungKalkulator.cs /tmp/cs-eko/publikasi/
# kemas pustaka menjadi package NuGet, hanya baris deterministik yang ditampilkan
dotnet pack /tmp/cs-eko/publikasi/KalkulatorPaket.csproj -o /tmp/cs-eko/publikasi/nupkg 2>&1 | grep "Successfully created package"
text Keluaran 
  Successfully created package '/tmp/cs-eko/publikasi/nupkg/KalkulatorPaket.1.0.0.nupkg'.

Opsi -o menentukan folder keluaran arsipnya, dan nama berkasnya menggabungkan PackageId dengan Version, sehingga setiap rilis menghasilkan arsip dengan nama yang berbeda. Proses pack juga menuliskan folder obj dan bin di sebelah berkas proyeknya, dan itulah alasan contoh ini menyalin proyek ke folder sementara terlebih dahulu, yaitu agar folder topik tetap bersih dari artefak build.

bash 
# perlihatkan isi folder keluaran pack
ls /tmp/cs-eko/publikasi/nupkg
text Keluaran 
KalkulatorPaket.1.0.0.nupkg

Arsip .nupkg berbentuk zip yang berisi pustaka terkompilasi beserta manifest .nuspec, sehingga isinya dapat diperiksa dengan alat arsip apa pun sebelum diterbitkan. Pemeriksaan ini berguna untuk memastikan DLL yang ikut sudah benar dan manifestnya memuat deskripsi yang diharapkan.

Mengirim package ke repositori#

Perintah dotnet nuget push mengirim arsip ke sebuah sumber (source), yaitu lokasi penyimpanan package yang dapat berupa folder lokal, feed privat organisasi, atau nuget.org. Sumber lokal berupa folder adalah sarana latihan yang paling ringan karena tidak membutuhkan jaringan maupun kredensial, dan perilakunya sama dengan sumber daring dari sisi perintahnya.

bash 
# buat folder sumber lokal, lalu kirim package ke sumber tersebut
mkdir -p /tmp/cs-eko/publikasi/repo
dotnet nuget push /tmp/cs-eko/publikasi/nupkg/KalkulatorPaket.1.0.0.nupkg --source /tmp/cs-eko/publikasi/repo 2>&1 | grep "pushed"
text Keluaran 
Your package was pushed.

Pengiriman ke nuget.org mengikuti langkah yang sama dengan sumber dan kredensial yang berbeda. Akun dibuat terlebih dahulu di situs nuget.org, kunci API (API key) dibuat dari halaman akun itu dengan hak publikasi yang diizinkan, lalu kunci tersebut dilewatkan pada perintah pengiriman. Kunci API menggantikan kata sandi agar perintahnya dapat dijalankan dari sistem otomatis tanpa menyimpan kredensial akun.

bash 
# tidak-dijalankan
# pengiriman ke nuget.org membutuhkan kunci API pribadi dan layanan daring yang eksternal
dotnet nuget push /tmp/cs-eko/publikasi/nupkg/KalkulatorPaket.1.0.0.nupkg --source https://api.nuget.org/v3/index.json --api-key KUNCI_API

Setelah pengiriman diterima, package memasuki antrean validasi dan halamannya tampil di nuget.org dalam beberapa menit, kemudian package itu dapat dipasang oleh siapa pun dengan dotnet add package.

Kesalahan umum#

  • Mengirim ulang versi yang sudah terbit. Repositori menolak arsip dengan PackageId dan Version yang sama, sehingga setiap rilis menuntut kenaikan Version pada berkas proyek terlebih dahulu.
  • Memilih PackageId tanpa pemeriksaan. Nama yang sudah dipakai package lain di nuget.org menyebabkan penolakan saat pengiriman, sehingga ketersediaan nama diperiksa di situs repositori sebelum pengemasan.
  • Melupakan public pada kelas pustaka. Proses pack tetap berhasil, tetapi pemakai tidak dapat melihat kelasnya karena hanya anggota public yang terekspos, dan perbaikannya adalah menambahkan kata kunci itu lalu mengemas ulang dengan versi baru.

Ringkasan#

  • Pustaka yang dibagikan berbentuk class library tanpa titik masuk, dan bagian yang terekspos ditentukan oleh kata kunci public.
  • Metadata package dinyatakan sebagai properti .csproj berupa PackageId, Version, Authors, dan Description, lalu diteruskan ke manifest .nuspec di dalam arsip.
  • dotnet pack mengompilasi pustaka dalam konfigurasi Release dan menghasilkan arsip .nupkg yang namanya menggabungkan identitas dengan versi.
  • dotnet nuget push --source mengirim arsip ke folder lokal maupun nuget.org, dan pengiriman ulang versi yang sama ditolak repositori.

Referensi#