Memecahkan masalah penggunaan alat .NET

Artikel
01/29/2025

Anda mungkin menemukan masalah saat mencoba menginstal atau menjalankan alat .NET, yang dapat menjadi alat global atau alat lokal. Artikel ini menjelaskan akar penyebab umum dan beberapa solusi yang mungkin.

Alat .NET yang terinstal gagal dijalankan

Ketika alat .NET gagal dijalankan, kemungkinan besar Anda mengalami salah satu masalah berikut:

File yang dapat dieksekusi untuk alat tidak ditemukan.
Versi runtime .NET yang benar tidak ditemukan.

File yang dapat dieksekusi tidak ditemukan

Jika file yang dapat dieksekusi tidak ditemukan, Anda akan melihat pesan yang mirip dengan yang berikut ini:

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

Nama executable menentukan cara Anda memanggil alat. Tabel berikut ini menjelaskan formatnya:

Format nama yang dapat dieksekusi	Format pemanggilan
`dotnet-<toolName>.exe`	`dotnet <toolName>`
`<toolName>.exe`	`<toolName>`

Alat global

Alat global dapat diinstal di direktori default atau di lokasi tertentu. Direktori defaultnya adalah:

Sistem operasi	Jalan
Linux/macOS	`$HOME/.dotnet/tools`
Windows	`%USERPROFILE%\.dotnet\tools`

Jika Anda mencoba menjalankan alat global, periksa apakah variabel lingkungan PATH pada komputer Anda berisi jalur tempat Anda menginstal alat global dan bahwa executable berada di jalur tersebut.

.NET CLI mencoba menambahkan lokasi default ke variabel lingkungan PATH pada penggunaan pertamanya. Namun, ada beberapa skenario di mana lokasi mungkin tidak ditambahkan ke PATH secara otomatis:

Jika Anda menggunakan Linux dan Anda telah menginstal .NET SDK menggunakan file .tar.gz dan bukan apt-get atau rpm.
Jika Anda menggunakan macOS 10.15 "Catalina" atau versi yang lebih baru.
Jika Anda menggunakan macOS 10.14 "Mojave" atau versi yang lebih lama, dan Anda telah menginstal .NET SDK menggunakan file .tar.gz dan tidak .pkg.
Jika Anda telah menginstal .NET Core 3.0 SDK dan Anda telah mengatur variabel lingkungan DOTNET_ADD_GLOBAL_TOOLS_TO_PATH ke false.
Jika Anda telah menginstal .NET Core 2.2 SDK atau versi yang lebih lama, dan Anda telah mengatur variabel lingkungan DOTNET_SKIP_FIRST_TIME_EXPERIENCE ke true.

Dalam skenario ini atau jika Anda menentukan opsi --tool-pathsaat menginstal alat dotnet, variabel lingkungan PATH pada komputer Anda tidak secara otomatis berisi jalur tempat Anda menginstal alat global. Dalam hal ini, tambahkan lokasi alat (misalnya, $HOME/.dotnet/tools) ke variabel lingkungan PATH dengan menggunakan metode apa pun yang disediakan shell Anda untuk memperbarui variabel lingkungan. Untuk informasi selengkapnya, lihat alat .NET di .

Alat lokal

Jika Anda mencoba menjalankan alat lokal, verifikasi bahwa ada file manifes yang disebut dotnet-tools.json di direktori saat ini atau direktori induknya. File ini juga dapat hidup di bawah folder bernama .config di mana saja dalam hierarki folder proyek, bukan folder akar. Jika dotnet-tools.json ada, buka dan periksa alat yang coba Anda jalankan. Jika file tidak berisi entri untuk "isRoot": true, maka periksa juga hierarki file lebih lanjut untuk file manifes alat tambahan.

Jika Anda mencoba menjalankan alat .NET yang diinstal dengan jalur tertentu, Anda perlu menyertakan jalur tersebut saat menggunakan alat tersebut. Contoh penggunaan alat yang terpasang pada jalur alat adalah:

..\<toolDirectory>\dotnet-<toolName>

Runtime tidak ditemukan

Alat .NET aplikasi yang bergantung pada kerangka kerja, yang berarti mereka mengandalkan runtime .NET yang diinstal pada komputer Anda. Jika runtime yang diharapkan tidak ditemukan, mereka mengikuti aturan roll-forward runtime .NET normal seperti:

Aplikasi terus berlanjut ke rilis patch tertinggi dari versi utama dan minor yang ditentukan.
Jika tidak ada runtime dengan nomor versi mayor dan minor yang cocok, maka versi minor yang lebih tinggi berikutnya akan digunakan.
Roll forward tidak terjadi antara versi pratinjau runtime atau antara versi pratinjau dan versi rilis. Jadi, alat .NET yang dibuat menggunakan versi pratinjau harus dibangun ulang dan diterbitkan ulang oleh penulis dan diinstal ulang.

Lanjutan ke depan tidak akan terjadi secara default dalam dua skenario umum:

Hanya versi runtime yang lebih rendah yang tersedia. Roll-forward hanya memilih versi runtime yang lebih baru.
Hanya versi utama runtime yang lebih tinggi yang tersedia. Roll-forward tidak melewati batas versi utama.

Jika aplikasi tidak dapat menemukan runtime yang sesuai, aplikasi gagal dijalankan dan melaporkan kesalahan.

Anda dapat mengetahui runtime .NET mana yang diinstal pada komputer Anda menggunakan salah satu perintah berikut:

dotnet --list-runtimes
dotnet --info

Jika menurut Anda alat tersebut harus mendukung versi runtime yang saat ini Anda instal, Anda dapat menghubungi pembuat alat dan memastikan apakah mereka dapat memperbarui nomor versi atau mendukung beberapa target. Setelah mereka mengkompilasi ulang dan menerbitkan ulang paket alat mereka ke NuGet dengan nomor versi yang diperbarui, Anda dapat memperbarui salinan Anda. Meskipun itu tidak terjadi, solusi tercepat bagi Anda adalah menginstal versi runtime yang akan berfungsi dengan alat yang anda coba jalankan. Untuk mengunduh versi runtime .NET tertentu, kunjungi halaman unduhan .NET .

Jika Anda menginstal .NET SDK ke lokasi tidak default, Anda perlu mengatur variabel lingkungan DOTNET_ROOT ke direktori yang berisi berkas eksekusi dotnet.

Penginstalan alat .NET gagal

Ada sejumlah alasan penginstalan alat global atau lokal .NET mungkin gagal. Saat penginstalan alat gagal, Anda akan melihat pesan yang mirip dengan yang berikut ini:

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

Untuk membantu mendiagnosis kegagalan ini, pesan NuGet ditampilkan langsung kepada pengguna, bersama dengan pesan sebelumnya. Pesan NuGet dapat membantu Anda mengidentifikasi masalah.

Penerapan penamaan Paket
Rilis Pratinjau
Paket bukan alat .NET
umpan NuGet tidak dapat diakses
ID Paket salah
401 (Tidak diizinkan)

Penerapan aturan penamaan paket

Microsoft telah mengubah panduannya tentang ID Paket untuk alat, sehingga sejumlah alat tidak ditemukan dengan nama yang diprediksi. Panduan baru adalah bahwa semua alat Microsoft harus diawali dengan "Microsoft." Prefiks ini khusus dan hanya dapat digunakan untuk paket yang ditandatangani dengan sertifikat resmi Microsoft.

Selama transisi, beberapa alat Microsoft akan memiliki bentuk lama ID paket, sementara yang lain akan memiliki formulir baru:

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

Saat ID paket diperbarui, Anda harus mengubah ke ID paket baru untuk mendapatkan pembaruan terbaru. Paket dengan nama alat yang disederhanakan tidak akan digunakan lagi.

Rilis pratinjau

Anda mencoba menginstal rilis pratinjau dan tidak menggunakan opsi --version untuk menentukan versi.

Alat .NET yang sedang dalam pratinjau harus ditentukan menggunakan bagian dari nama untuk menunjukkan bahwa mereka sedang dalam pratinjau. Anda tidak perlu menyertakan seluruh pratinjau. Dengan asumsi nomor versi dalam format yang diharapkan, Anda dapat menggunakan sesuatu seperti contoh berikut:

dotnet tool install -g --version 1.1.0-pre <toolName>

Paket bukan alat .NET

Paket NuGet dengan nama ini ditemukan, tetapi bukan alat .NET.

Jika Anda mencoba menginstal paket NuGet yang merupakan paket NuGet biasa dan bukan alat .NET, Anda akan melihat kesalahan yang mirip dengan yang berikut ini:

NU1212: Kombinasi paket proyek tidak valid untuk <toolName>. Gaya proyek DotnetToolReference hanya dapat berisi referensi jenis DotnetTool.

Umpan NuGet tidak dapat diakses

Umpan NuGet yang diperlukan tidak dapat diakses, mungkin karena masalah koneksi Internet.

Penginstalan alat memerlukan akses ke umpan NuGet yang berisi paket alat. Gagal jika umpan tidak tersedia. Anda dapat mengubah umpan dengan nuget.config, meminta file nuget.config tertentu, atau menentukan umpan tambahan dengan sakelar --add-source. Secara default, NuGet melemparkan kesalahan untuk umpan apa pun yang tidak dapat tersambung. Bendera --ignore-failed-sources dapat melewati sumber yang tidak dapat dijangkau ini.

ID paket salah

Anda salah ketik nama alat.

Alasan umum kegagalan adalah bahwa nama alat tidak benar. Ini dapat terjadi karena salah ketik, atau karena alat telah dipindahkan atau tidak digunakan lagi. Untuk alat di NuGet.org, salah satu cara untuk memastikan nama Anda benar adalah dengan mencari alat di NuGet.org dan menyalin perintah penginstalan.

401 (Tidak Sah)

Kemungkinan besar Anda telah menentukan umpan NuGet alternatif, dan umpan tersebut memerlukan autentikasi. Ada beberapa cara berbeda untuk menyelesaikan ini:

Tambahkan parameter --ignore-failed-sources untuk melewati kesalahan dari umpan privat dan gunakan umpan Microsoft publik.

Jika Anda menginstal alat dari umpan Microsoft NuGet, umpan kustom Anda mengembalikan kesalahan ini sebelum umpan NuGet Microsoft mengembalikan hasilnya. Kesalahan ini mengakhiri permintaan, membatalkan permintaan umpan lain yang tertunda, yang mungkin adalah umpan NuGet dari Microsoft. Menambahkan opsi --ignore-failed-sources menyebabkan perintah memperlakukan kesalahan ini sebagai peringatan dan memungkinkan umpan lain memproses permintaan.
```
dotnet tool install -g --ignore-failed-sources <toolName>
```
Paksa umpan Microsoft NuGet dengan parameter --add-source.

Ada kemungkinan bahwa file konfigurasi NuGet global atau lokal tidak memiliki umpan Microsoft NuGet publik. Gunakan kombinasi parameter --add-source dan --ignore-failed-sources untuk menghindari umpan yang salah dan mengandalkan umpan Microsoft publik.
```
dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>
```
Gunakan konfigurasi NuGet kustom, parameter --configfile <FILE>.

Buat file nuget.config lokal hanya dengan umpan Microsoft NuGet publik, dan referensikan dengan parameter --configfile:
```
dotnet tool install -g --configfile "./nuget.config" <toolName>
```
Berikut adalah contoh file konfigurasi:
```
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>
```
Untuk informasi selengkapnya, lihat referensi nuget.config.
Tambahkan kredensial yang diperlukan ke file konfigurasi.

Jika Anda tahu paket ada di umpan yang dikonfigurasi, berikan kredensial login dalam file konfigurasi NuGet. Untuk informasi selengkapnya tentang kredensial dalam file konfigurasi nuget, lihat referensi bagian packageSourceCredentials nuget.config.

Lihat juga

perangkat .NET

Bagikan melalui