Memecahkan masalah penggunaan alat .NET

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:

OS	Jalur
Linux/macOS	$HOME/.dotnet/tools
Jendela	%USERPROFILE%\.dotnet\tools

Jika Anda mencoba menjalankan alat global, periksa apakah PATH variabel lingkungan 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 bukan .pkg.
• Jika Anda telah menginstal .NET Core 3.0 SDK dan Anda telah mengatur DOTNET_ADD_GLOBAL_TOOLS_TO_PATH variabel lingkungan ke false.
• Jika Anda telah menginstal .NET Core 2.2 SDK atau versi yang lebih lama, dan Anda telah mengatur DOTNET_SKIP_FIRST_TIME_EXPERIENCE variabel lingkungan ke true.

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

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 diinstal jalur alat adalah:

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

Runtime tidak ditemukan

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

• Aplikasi diteruskan ke rilis patch tertinggi dari versi utama dan minor yang ditentukan.
• Jika tidak ada runtime yang cocok dengan nomor versi utama dan minor yang cocok, 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.

Roll-forward 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 telah Anda instal, Anda dapat menghubungi pembuat alat dan melihat apakah mereka dapat memperbarui nomor versi atau multi-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 non-default, Anda perlu mengatur variabel DOTNET_ROOT lingkungan ke direktori yang berisi dotnet yang dapat dieksekusi.

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.

• Penegakan penamaan paket
• Rilis pratinjau
• Paket bukan alat .NET
• Umpan NuGet tidak dapat diakses
• ID paket salah
• 401 (Tidak Sah)

Penegakan 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 diawali dengan "Microsoft." Awalan ini dicadangkan 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 --version opsi untuk menentukan versi.

Alat .NET yang ada dalam pratinjau harus ditentukan dengan sebagian nama untuk menunjukkan bahwa mereka 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 tertentu nuget.config , 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 (TidakDiizinkan)

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

• --ignore-failed-sources Tambahkan parameter 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 mengakhiri permintaan, membatalkan permintaan umpan lain yang tertunda, yang bisa menjadi umpan NuGet Microsoft. --ignore-failed-sources Menambahkan opsi 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 --add-source parameter .

  Ada kemungkinan bahwa file konfigurasi NuGet global atau lokal tidak memiliki umpan Microsoft NuGet publik. Gunakan kombinasi --add-source parameter 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, --configfile <FILE> parameter.

  Buat file nuget.config lokal hanya dengan umpan Microsoft NuGet publik, dan referensikan dengan --configfile parameter :

  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 info masuk masuk dalam file konfigurasi NuGet. Untuk informasi selengkapnya tentang kredensial dalam file konfigurasi nuget, lihat bagian packageSourceCredentials referensi nuget.config.

Baca juga

• Alat .NET