NuGet dan Pustaka

Memakai paket NuGet dan membuat pustaka kelas sendiri.

Daftar isi

NuGet adalah sistem manajemen paket (package manager) untuk .NET yang mengurus pencarian, pengunduhan, dan pembaruan pustaka dari repositori daring. Topik ini menggunakan NuGet dari dua arah, yaitu memasang paket yang sudah terbit di nuget.org dan membuat pustaka kelas (class library) sendiri yang dihubungkan ke aplikasi console melalui ProjectReference. Contoh yang dijalankan adalah pustaka Kalkulasi berisi perhitungan statistik sederhana beserta aplikasi console yang menggunakannya bersama paket Humanizer.

Peran NuGet dalam ekosistem .NET#

Sebuah paket NuGet adalah arsip yang memuat pustaka hasil kompilasi, metadatanya, dan nomor versinya. Repositori publik nuget.org menyimpan jutaan paket yang dapat dipasang ke proyek mana pun, dan perintah dotnet add package menambahkan baris PackageReference ke berkas proyek lalu mengunduh paketnya. Proses menyiapkan seluruh paket yang tersenarai disebut restore, dan langkah ini dijalankan secara otomatis setiap kali proyek dikompilasi atau dijalankan.

Manfaatnya terasa pada dua sisi. Kode yang sudah mapan, misalnya pemformatan angka menjadi kata atau pembacaan berkas CSV, tidak perlu ditulis ulang karena cukup dipasang dari repositori. Di sisi lain, daftar PackageReference pada berkas proyek mencatat persyaratan pustaka suatu proyek beserta versinya, sehingga proyek yang sama dapat dibangun ulang dengan komposisi pustaka yang konsisten di mesin lain. Pustaka buatan sendiri pun kelak dibagikan dalam bentuk paket yang sama.

Pada VB.NET, paket dipasang dengan PackageReference di dalam ItemGroup berkas proyek, tanpa berkas konfigurasi terpisah seperti pada ekosistem lain. Perintah dotnet add package, dotnet restore, dotnet build, dan dotnet run semuanya membaca daftar yang sama dari berkas proyek tersebut, sehingga tidak ada dua sumber kebenaran yang harus disamakan.

Pustaka kelas pertama#

Pustaka kelas adalah proyek yang hasil kompilasinya berupa berkas .dll tanpa titik masuk, sehingga tidak dijalankan sendiri melainkan digunakan aplikasi lain. Berkas proyeknya lebih pendek daripada proyek console karena tidak ada OutputType yang dinyatakan.

xml PustakaKalkulasi.vbproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <RootNamespace>Kalkulasi</RootNamespace>
  </PropertyGroup>

</Project>

Tanpa OutputType, proyek bergaya SDK bawaannya adalah pustaka, dan TargetFramework menentukan versi .NET tempat pustaka itu ditujukan. Properti RootNamespace bernilai Kalkulasi memiliki peran khusus pada VB.NET, yaitu namespace dasar yang mengawali seluruh tipe di dalam proyek. Karena itu kelas StatistikDasar tanpa deklarasi Namespace apa pun otomatis berada di namespace Kalkulasi, dan kode yang menggunakannya cukup menuliskan Imports Kalkulasi.

vb KalkulasiSederhana.vb

' pustaka kelas tanpa deklarasi Namespace eksplisit:
' namespace Kalkulasi berasal dari RootNamespace pada PustakaKalkulasi.vbproj
Public Class StatistikDasar

    Public Function RataRata(nilai As Double()) As Double
        If nilai Is Nothing OrElse nilai.Length = 0 Then
            Throw New ArgumentException("Kumpulan nilai tidak boleh kosong.")
        End If

        Return nilai.Average()
    End Function

    Public Function NilaiTertinggi(nilai As Double()) As Double
        If nilai Is Nothing OrElse nilai.Length = 0 Then
            Throw New ArgumentException("Kumpulan nilai tidak boleh kosong.")
        End If

        Return nilai.Max()
    End Function

End Class

Kedua fungsinya menjaga argumennya dengan melempar ArgumentException apabila kumpulan nilai kosong, kemudian mendelegasikan perhitungan ke Average dan Max. Kelas ini tidak mengenal Console sebagaimana prinsip pemisahan logika pada topik pengujian unit, sehingga pustaka yang sama dapat digunakan dari aplikasi console, form, maupun uji.

Aplikasi console yang menggunakan pustaka#

Dua proyek ini berada pada dua folder bersebelahan, yaitu PustakaKalkulasi dan AplikasiKalkulasi. Hubungan keduanya dinyatakan di berkas proyek aplikasi melalui elemen ProjectReference yang menunjuk berkas .vbproj pustaka dengan jalur relatif.

xml AplikasiKalkulasi.vbproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\PustakaKalkulasi\PustakaKalkulasi.vbproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Humanizer" Version="3.0.10" />
  </ItemGroup>

</Project>

Saat aplikasi dikompilasi, ProjectReference membuat pustaka dikompilasi lebih dahulu lalu hasilnya ikut disertakan ke aplikasi. Baris PackageReference yang menyertakan Humanizer dibahas pada bagian berikutnya, karena baris tersebut justru ditambahkan secara otomatis oleh perintah pemasangan paket. Diagram berikut merangkum dua jalur kode yang masuk ke aplikasi, yaitu pustaka lokal melalui ProjectReference dan paket dari nuget.org melalui PackageReference.

Dua jalur suplai kode ke aplikasi console

bash

# tidak-dijalankan
# masuk ke folder aplikasi console
cd AplikasiKalkulasi
# mengompilasi pustaka beserta aplikasinya, lalu menjalankan program
dotnet run

Program berikut menggunakan pustaka dan paket sekaligus. Dua baris terakhirnya berasal dari paket Humanizer yang pemasangannya dijelaskan pada bagian berikutnya, sehingga kedua baris itu baru dapat berjalan setelah paket tersebut terpasang.

vb Program.vb

Imports Humanizer
Imports Kalkulasi

Module Program

    Sub Main()
        Dim statistik As New StatistikDasar()
        Dim nilaiUjian() As Double = {70, 80, 90}

        Console.WriteLine($"Rata-rata: {statistik.RataRata(nilaiUjian)}")
        Console.WriteLine($"Nilai tertinggi: {statistik.NilaiTertinggi(nilaiUjian)}")

        Dim jumlahSiswa As Integer = 123
        Console.WriteLine($"123 dalam huruf: {jumlahSiswa.ToWords()}")
        Console.WriteLine($"Ukuran data: {ByteSize.FromKilobytes(1.5)}")
    End Sub

End Module

text Keluaran

Rata-rata: 80
Nilai tertinggi: 90
123 dalam huruf: one hundred and twenty-three
Ukuran data: 1.5 KB

Dua baris pertama memanggil StatistikDasar dari pustaka melalui Imports Kalkulasi, sedangkan dua baris terakhir berasal dari paket Humanizer. Metode ToWords mengubah bilangan menjadi tulisan dalam bahasa Inggris, dan tipe ByteSize memformat ukuran data menjadi satuan yang mudah dibaca. Kedua kemampuan itu tidak ditulis satu baris pun, cukup dipasang sebagai paket.

Memasang paket dari nuget.org#

Perintah dotnet add package Humanizer dijalankan dari dalam folder AplikasiKalkulasi. Perintah ini mencari paket di nuget.org, memilih versi stabil terbarunya, menambahkan baris PackageReference, lalu melakukan restore pada proyek.

bash

# tidak-dijalankan
# dijalankan dari dalam folder AplikasiKalkulasi
cd AplikasiKalkulasi
# memasang paket Humanizer dari nuget.org
dotnet add package Humanizer

text Transkrip terminal

$ dotnet add package Humanizer
info : X.509 certificate chain validation will use the fallback certificate bundle at '/home/kal/my-project/tools/dotnet/sdk/10.0.403/trustedroots/codesignctl.pem'.
info : X.509 certificate chain validation will use the fallback certificate bundle at '/home/kal/my-project/tools/dotnet/sdk/10.0.403/trustedroots/timestampctl.pem'.
info : Adding PackageReference for package 'Humanizer' into project '/home/kal/my-project/build-scratch/vb-profesional__nuget-dan-pustaka/AplikasiKalkulasi/AplikasiKalkulasi.vbproj'.
info :   GET https://api.nuget.org/v3/registration5-gz-semver2/humanizer/index.json
info :   OK https://api.nuget.org/v3/registration5-gz-semver2/humanizer/index.json 320ms
info : Restoring packages for /home/kal/my-project/build-scratch/vb-profesional__nuget-dan-pustaka/AplikasiKalkulasi/AplikasiKalkulasi.vbproj...
info :   GET https://api.nuget.org/v3-flatcontainer/humanizer/index.json
info :   OK https://api.nuget.org/v3-flatcontainer/humanizer/index.json 252ms
info :   GET https://api.nuget.org/v3-flatcontainer/humanizer/3.0.10/humanizer.3.0.10.nupkg
info :   OK https://api.nuget.org/v3-flatcontainer/humanizer/3.0.10/humanizer.3.0.10.nupkg 13ms
...
info :   CACHE https://api.nuget.org/v3/vulnerabilities/index.json
info : Package 'Humanizer' is compatible with all the specified frameworks in project '/home/kal/my-project/build-scratch/vb-profesional__nuget-dan-pustaka/AplikasiKalkulasi/AplikasiKalkulasi.vbproj'.
info : PackageReference for package 'Humanizer' version '3.0.10' added to file '/home/kal/my-project/build-scratch/vb-profesional__nuget-dan-pustaka/AplikasiKalkulasi/AplikasiKalkulasi.vbproj'.
info : Generating MSBuild file /home/kal/my-project/build-scratch/vb-profesional__nuget-dan-pustaka/AplikasiKalkulasi/obj/AplikasiKalkulasi.vbproj.nuget.g.props.
info : Generating MSBuild file /home/kal/my-project/build-scratch/vb-profesional__nuget-dan-pustaka/AplikasiKalkulasi/obj/AplikasiKalkulasi.vbproj.nuget.g.targets.
info : Writing assets file to disk. Path: /home/kal/my-project/build-scratch/vb-profesional__nuget-dan-pustaka/AplikasiKalkulasi/obj/project.assets.json
log  : Restored /home/kal/my-project/build-scratch/vb-profesional__nuget-dan-pustaka/AplikasiKalkulasi/AplikasiKalkulasi.vbproj (in 3.22 sec).

Bagian tengah transkrip yang diringkas memuat ratusan baris Installed untuk paket-paket pendamping Humanizer, yaitu paket bahasa bernama Humanizer.Core untuk setiap bahasa yang didukungnya. Baris-baris yang ditampilkan sudah cukup untuk membaca alurnya, yaitu kontak ke api.nuget.org, pemilihan versi 3.0.10, penyambungan PackageReference ke berkas proyek, dan restore yang menyusul. Setelah perintah ini, berkas AplikasiKalkulasi.vbproj bertambah satu ItemGroup berisi PackageReference, sehingga isinya sama persis dengan berkas yang ditampilkan pada bagian sebelumnya.

Penggunaan paketnya hanya memerlukan Imports Humanizer di kepala Program.vb sebagaimana terlihat pada program di atas. Mengenai versi, dotnet add package tanpa argumen tambahan memilih versi stabil terbaru pada saat perintah dijalankan, dan angka itu lalu tertulis pada berkas proyek.

Kesalahan umum#

Kesalahan pertama adalah melihat pesan NETSDK1004 yang menyatakan berkas project.assets.json tidak ditemukan. Pesan ini muncul ketika restore belum pernah dijalankan untuk isi berkas proyek yang baru, misalnya setelah berkas proyek disalin dari tempat lain. Perbaikannya adalah menjalankan dotnet restore, atau cukup dotnet build karena restore berjalan otomatis di dalamnya.

Kesalahan kedua adalah memasang paket yang tidak mendukung TargetFramework proyek, yang dilaporkan sebagai error NU1202. Paket menyatakan daftar target yang didukungnya di metadatanya, dan paket lama yang hanya menyediakan aset untuk kerangka lawas tidak dapat dipasang ke proyek net10.0. Pilih versi paket yang lebih baru atau paket penggantinya.

Kesalahan ketiga adalah menuliskan jalur ProjectReference yang tidak sesuai tata letak folder, sehingga kompilasi berhenti dengan pesan berkas proyek tidak ditemukan. Jalur pada ProjectReference adalah jalur relatif dari berkas proyek aplikasi, dan bentuk ..\PustakaKalkulasi\PustakaKalkulasi.vbproj sesuai tata letak dua folder bersebelahan pada topik ini.

Ringkasan#

NuGet mengelola pustaka luar melalui PackageReference pada berkas proyek dan restore yang berjalan otomatis, dengan nuget.org sebagai repositori publiknya.
Pustaka kelas adalah proyek tanpa OutputType yang menghasilkan .dll, dan pada VB.NET RootNamespace menentukan namespace dasar seluruh tipenya.
Aplikasi menggunakan pustaka sendiri melalui ProjectReference, sedangkan dotnet add package memasang paket dari nuget.org dengan menambahkan baris PackageReference secara otomatis.

Referensi#

What is NuGet? — Microsoft Learn — Definisi paket NuGet, formatnya, dan peran repositori.
dotnet add package — Microsoft Learn — Opsi perintah pemasangan paket beserta perilaku versinya.
Class library overview — Microsoft Learn — Konsep pustaka kelas .NET dan penggunaannya antarproyek.