KAL
Menu

NuGet

Mencari, memasang, dan memberi versi package.

Daftar isi

NuGet adalah sistem package untuk .NET, yaitu mekanisme yang membungkus pustaka siap pakai beserta metadatanya ke dalam satu arsip sehingga dapat dipasang ke proyek apa pun dengan satu perintah. Topik ini membahas cara mencari package di repositori publik nuget.org, memasangnya ke proyek console, mengatur versi yang dipinjam, serta memeriksa dan melepas package yang sudah tercatat. Setelah topik ini diselesaikan, pengelolaan dependensi pihak ketiga pada proyek C# dapat dilakukan sepenuhnya dari dotnet CLI.

Package dan nuget.org#

Package NuGet berbentuk arsip zip berakhiran .nupkg yang berisi pustaka terkompilasi, berkas pendukung, dan sebuah manifest berisi metadata seperti nama, versi, pembuat, dan daftar dependensi. nuget.org adalah repositori publik yang menjadi sumber package paling umum untuk .NET, dan SDK .NET sudah mengonfigurasikannya sebagai sumber default sehingga tidak ada penyiapan tambahan. Pencarian dilakukan dari kotak pencarian nuget.org yang menampilkan halaman tiap package beserta jumlah unduhannya, atau dari terminal dengan dotnet package search yang menampilkan kolom Package ID, Version, Owners, dan Total Downloads.

Penilaian kualitas package dilakukan sebelum pemasangan. Jumlah unduhan yang tinggi menunjukkan pemakaian yang luas, sedangkan tanggal versi terbaru menunjukkan pemeliharaan yang masih berjalan. Halaman package pada nuget.org juga merangkum informasi yang menentukan keputusan, yaitu daftar dependensi yang dibawanya, riwayat versi yang pernah terbit, dan tautan repositori kode sumbernya. Package prarilis ditandai akhiran seperti -beta atau -rc pada versinya, dan jenis package seperti itu sengaja tidak dipilih oleh perintah pemasangan kecuali versinya disebutkan secara eksplisit. Kebiasaan ini melindungi proyek dari dependensi yang belum stabil tanpa perlu pengaturan khusus.

Memasang package ke proyek#

Pemasangan dilakukan pada sebuah proyek, sehingga contoh berikut dimulai dari proyek console kosong yang dibuat di folder latihan sementara. Opsi --no-restore mempercepat pembuatan proyek karena pemulihan (restore) dijalankan terpisah pada langkah berikutnya.

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 proyek console contoh di folder sementara /tmp
rm -rf /tmp/cs-eko/demo-nuget
dotnet new console -o /tmp/cs-eko/demo-nuget --no-restore | grep "created successfully"
text Keluaran 
The template "Console App" was created successfully.

Perintah dotnet add package mengunduh package yang diminta, mencatatnya pada berkas proyek, dan menjalankan pemulihan agar pustakanya langsung dapat dipakai. Perintah berikut memasang Newtonsoft.Json, yaitu package pengolah JSON yang luas digunakan, dengan versi yang dipatok secara eksplisit.

bash 
# pasang package Newtonsoft.Json versi 13.0.3 ke proyek contoh
dotnet add /tmp/cs-eko/demo-nuget package Newtonsoft.Json --version 13.0.3 2>&1 | grep "version '13.0.3' added"
text Keluaran 
info : PackageReference for package 'Newtonsoft.Json' version '13.0.3' added to file '/tmp/cs-eko/demo-nuget/demo-nuget.csproj'.

Hasil pemasangan tercatat sebagai elemen PackageReference pada berkas .csproj, sehingga dependensi ikut terekam bersama kode sumber dan dapat dipulihkan kapan pun.

xml Contoh: PackageReference pada berkas proyek 
<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
</ItemGroup>

Pemulihan menyusun grafik dependensi dari seluruh PackageReference, termasuk dependensi tidak langsung yang dibawa package yang dipasang, lalu mencatat hasilnya pada berkas obj/project.assets.json. Berkas itulah yang dibaca proses build untuk menentukan pustaka mana yang dirangkai ke program, sehingga dua langkah pemulihan pada proyek yang sama tidak mengunduh apa pun lagi selama cache masih lengkap.

Memberi versi package#

Versi package mengikuti format semantic versioning, yaitu tiga bilangan mayor.minor.patch yang menunjukkan sifat perubahannya. Kenaikan mayor menandakan perubahan yang dapat merusak kode pemakai (breaking change), kenaikan minor menandakan fitur baru yang tetap kompatibel, sedangkan kenaikan patch menandakan perbaikan tanpa perubahan cara pakai. Default dotnet add package memilih versi stabil tertinggi dan mematoknya persis, sehingga hasil build tidak berubah tanpa sepengetahuan pengembangnya.

Pola versi lain dituliskan langsung pada atribut Version. Versi mengambang (floating version) menggunakan karakter wildcard seperti 13.0.* untuk selalu mengikuti patch terbaru, sedangkan rentang versi (version range) menetapkan batas bawah dan batas atas secara eksplisit. Notasi rentang mengikuti konvensi interval matematika, misalnya kurung siku berarti batas disertakan dan kurung biasa berarti batas dikecualikan.

xml Contoh: pola versi pada atribut Version 
<!-- mengambang: selalu pakai patch 13.0.x tertinggi -->
<PackageReference Include="Newtonsoft.Json" Version="13.0.*" />
<!-- rentang: minimal 13.0.0, di bawah 14.0.0 -->
<PackageReference Include="Newtonsoft.Json" Version="[13.0.0, 14.0.0)" />

Memeriksa dan melepas package#

Kondisi package pada sebuah proyek diperiksa dengan dotnet list package, yang menampilkan setiap package yang dipinjam beserta versi yang diminta dan versi yang diselesaikan. Kolom Requested dan Resolved berbeda hanya bila rentang atau versi mengambang dipakai, sehingga kesamaan keduanya menandakan pematokan yang ketat. Kepala tabel bertanda [net10.0] menunjukkan kelompok kerangka sasaran yang dimaksud, karena proyek yang menargetkan lebih dari satu kerangka menampilkan satu kelompok untuk masing-masingnya.

bash 
# periksa daftar package yang tercatat pada proyek contoh
dotnet list /tmp/cs-eko/demo-nuget package
text Keluaran 
  Determining projects to restore...
  All projects are up-to-date for restore.
Project 'demo-nuget' has the following package references
   [net10.0]:
   Top-level Package      Requested   Resolved
   > Newtonsoft.Json      13.0.3      13.0.3

Daftar tersebut baru memuat package tingkat atas, yaitu yang direferensikan langsung oleh proyek. Dependensi tidak langsung yang dibawa package tingkat atas ditampilkan dengan opsi --include-transitive, sedangkan opsi --outdated membandingkan versi terpasang dengan versi terbaru yang tersedia di sumber untuk membantu perencanaan peningkatan.

Pelepasan memakai dotnet remove package, yang menghapus elemen PackageReference dari berkas proyek tanpa menyentuh cache. Pustaka yang sudah diunduh tetap tersimpan di cache global agar proyek lain yang meminjam versi sama tidak mengunduh ulang.

bash 
# melepas package dari proyek contoh
dotnet remove /tmp/cs-eko/demo-nuget package Newtonsoft.Json 2>&1 | grep "Removing"
text Keluaran 
info : Removing PackageReference for package 'Newtonsoft.Json' from project '/tmp/cs-eko/demo-nuget/demo-nuget.csproj'.

Package pada program satu berkas#

Program satu berkas pada .NET 10 memasang package tanpa berkas proyek sama sekali. Arahan #:package ditulis di bagian atas berkas program, dan package yang disebut diunduh serta dirangkai secara otomatis saat program pertama kali dijalankan. Cara ini menghilangkan dua perintah di atas untuk kebutuhan eksperimen cepat, dengan catatan pencatatan dependensinya berada di dalam berkas program itu sendiri dan bukan pada .csproj.

csharp Program.cs 
#:package Newtonsoft.Json@13.0.3

// Program: menukar objek catatan pengukuran menjadi teks JSON dengan package NuGet
using Newtonsoft.Json;

List<Catatan> catatan = new()
{
    new Catatan("Lab", 24.5),
    new Catatan("Kantor", 26.0)
};

Console.WriteLine(JsonConvert.SerializeObject(catatan, Formatting.Indented));

record Catatan(string Ruang, double Suhu);

Jalankan program tersebut dari folder topik dengan perintah berikut.

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
# jalankan program contoh dari folder topik
dotnet run --file Program.cs
text Keluaran 
[
  {
    "Ruang": "Lab",
    "Suhu": 24.5
  },
  {
    "Ruang": "Kantor",
    "Suhu": 26.0
  }
]

Keluaran JSON tersebut dihasilkan oleh JsonConvert.SerializeObject dari package yang baru dipasang, dan perhatikan bahwa sintaks arahannya memakai tanda @ di antara nama package dan versinya. Arsip yang diunduh tetap masuk ke cache global yang sama dengan proyek biasa, sehingga package yang sama tidak diunduh dua kali oleh dua cara pemasangan yang berbeda. Pemisahan tanggung jawabnya tetap jelas, yaitu program satu berkas cocok untuk latihan dan eksperimen, sedangkan proyek dengan berkas .csproj menjadi pilihan untuk aplikasi yang berkembang karena dependensinya tercatat terpisah dari kode.

Kesalahan umum#

  • Mengasumsikan package langsung terpakai setelah dipasang. Pemasangan hanya merangkai pustakanya, sedangkan tipe di dalamnya baru terlihat setelah using atas namespace package ditambahkan ke berkas kode.
  • Menggunakan versi mengambang pada proyek yang dibangun oleh sistem otomatis. Hasil build bergeser mengikuti versi terbaru yang terbit, sehingga kegagalan yang muncul tidak dapat dihubungkan dengan perubahan kode apa pun.
  • Memindahkan proyek ke komputer lain tanpa pemulihan. Berkas obj dan cache lokal tidak ikut dipindahkan, sehingga dotnet restore perlu dijalankan untuk merakit ulang dependensi dari catatan PackageReference.

Ringkasan#

  • Package NuGet berupa arsip .nupkg berisi pustaka dan manifest, dicatat ke proyek sebagai PackageReference, dan dipulihkan menjadi grafik dependensi pada obj/project.assets.json.
  • dotnet add package memasang dan memulihkan, dotnet list package menampilkan versi yang diminta dan yang diselesaikan, sedangkan dotnet remove package mencatatnya keluar.
  • Versi memakai format mayor.minor.patch, dan pola mengambang atau rentang ditulis pada atribut Version dengan konsekuensi reproduktivitas yang perlu ditimbang.
  • Program satu berkas memasang package dengan arahan #:package di bagian atas berkasnya, tanpa berkas proyek.

Referensi#