Mengatasi Masalah Lingkungan

Masalah lingkungan biasanya mengikuti pola yang sama, sehingga gejala yang familiar dapat dipetakan langsung ke solusinya. Bab ini mengumpulkan masalah yang paling sering dialami pemula, menjelaskan penyebabnya, dan memberi langkah perbaikan yang teruji. Prinsip utamanya satu: baca pesan galat dari baris teratas sebelum mencoba perbaikan apa pun.

Tabel Diagnosis Cepat #

Masalah 1: Perintah dotnet Tidak Dikenali #

Gejala di terminal:

dotnet: command not found

Penyebab: shell mencari perintah di daftar folder pada variabel PATH. Proses instalasi menambahkan folder .NET ke PATH, tetapi terminal yang sudah terbuka tidak membaca ulang pembaruan tersebut.

Solusi:

1. Tutup seluruh jendela terminal, lalu buka terminal baru.
2. Jalankan dotnet --version untuk memastikan perintah dikenali.
3. Bila masih gagal, periksa lokasi instalasi: ~/.dotnet pada Linux/macOS (hasil script dotnet-install.sh) atau C:\Program Files\dotnet pada Windows.
4. Tambahkan folder tersebut ke PATH secara manual, lalu buka ulang terminal.

Masalah 2: Beberapa Versi SDK Terpasang #

Instalasi SDK tidak menimpa versi sebelumnya, sehingga beberapa SDK dapat terpasang berdampingan. Contoh tampilan dotnet --list-sdks ketika dua SDK terpasang:

8.0.412 [~/.dotnet/sdk]
9.0.319 [~/.dotnet/sdk]

Kondisi tersebut normal dan tidak merusak apa pun. CLI memilihkan SDK yang sesuai dengan <TargetFramework> di file .csproj. Bila kita ingin mengunci versi SDK untuk satu project, buat file global.json di folder root project:

{
  "sdk": {
    "version": "9.0.319",
    "rollForward": "latestFeature"
  }
}

Dengan konfigurasi tersebut, CLI memakai SDK 9.0.319 atau versi patch lebih baru pada feature band yang sama, dan mengabaikan SDK 8.x.

Masalah 3: TargetFramework Tidak Didukung SDK #

File .csproj menuntut target framework tertentu. Bila SDK yang terpasang lebih lama dari target — misalnya project menyebut net9.0 tetapi SDK 8.x yang aktif — build gagal dengan galat keluarga NETSDK (umumnya NETSDK1045 yang menyatakan SDK saat ini tidak mendukung target tersebut).

Solusi:

1. Periksa nilai <TargetFramework> di file .csproj, misalnya net9.0.
2. Jalankan dotnet --list-sdks untuk melihat SDK yang terpasang.
3. Bila SDK lebih lama dari target: perbarui SDK ke versi yang sesuai.
4. Bila pembaruan tidak memungkinkan: turunkan <TargetFramework> ke versi yang didukung SDK terpasang, misalnya net8.0.

Perhatikan bahwa menurunkan target dapat memengaruhi fitur bahasa C# yang tersedia, karena setiap versi .NET membawa versi compiler dan API pustaka yang berbeda.

Masalah 4: Restore NuGet Terblokir Firewall atau Proxy #

Saat restore berjalan, NuGet mengunduh package dari nuget.org. Firewall komputer atau proxy jaringan kantor dapat memblokir koneksi tersebut, sehingga perintah dotnet new maupun dotnet build berakhir dengan galat restore.

Solusi:

1. Pastikan browser pada komputer yang sama dapat membuka nuget.org.
2. Bila jaringan memakai proxy, set variabel lingkungan HTTP_PROXY dan HTTPS_PROXY sebelum menjalankan perintah dotnet.
3. Bila organisasi menyediakan mirror internal NuGet, daftarkan sumber tersebut di file nuget.config pada folder project.
4. Sebagai langkah terakhir, minta file .nupkg dari anggota tim lain dan pasang dari cache lokal.

Langkah Diagnosis Sistematis #

Ketika gejala tidak ada di daftar di atas, periksa lingkungan secara berurutan:

1. Baca pesan galat dari baris teratas. Pesan build .NET menampilkan target yang gagal dan alasan utamanya di bagian awal.
2. Jalankan dotnet --info. Perintah ini menampilkan versi SDK, versi runtime, dan lokasi instalasi dalam satu output — ringkasan lingkungan yang paling lengkap.
3. Jalankan dotnet --list-sdks. Bandingkan hasilnya dengan <TargetFramework> di file .csproj.
4. Hapus folder bin/ dan obj/, lalu build ulang. File cache yang usang kadang membuat build berperilaku aneh; build dari nol menghapus faktor tersebut.
5. Uji dari terminal bersih. Editor yang memuat versi SDK berbeda dapat menyembunyikan galat yang justru terlihat di terminal.