Memecahkan masalah kegagalan peluncuran aplikasi

Artikel ini menjelaskan beberapa alasan umum dan kemungkinan solusi untuk kegagalan peluncuran aplikasi. Ini berkaitan dengan aplikasi yang bergantung pada kerangka kerja, yang mengandalkan penginstalan .NET pada komputer Anda.

Jika Anda sudah tahu versi .NET mana yang Anda butuhkan, Anda dapat mengunduhnya dari unduhan .NET.

Penginstalan .NET tidak ditemukan

Jika penginstalan .NET tidak ditemukan, aplikasi gagal diluncurkan dengan pesan yang mirip dengan:

You must install .NET to run this application.

App: C:\repos\myapp\myapp.exe
Architecture: x64
Host version: 7.0.0
.NET location: Not found

You must install .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Host version: 7.0.0
.NET location: Not found

Ini mungkin karena mix-up paket.

Penginstalan global terdaftar di lokasi berikut: /etc/dotnet/install_location. Untuk informasi selengkapnya, lihat lokasi penginstalan.

You must install .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Host version: 7.0.0
.NET location: Not found

Penginstalan global terdaftar di lokasi berikut: /etc/dotnet/install_location. Untuk informasi selengkapnya, lihat lokasi penginstalan.

Pesan kesalahan menyertakan tautan untuk mengunduh .NET. Anda dapat mengikuti tautan tersebut untuk masuk ke halaman unduhan yang sesuai. Anda juga dapat memilih versi .NET (ditentukan oleh Host version) dari unduhan .NET.

Pada halaman unduhan untuk versi .NET yang diperlukan, temukan unduhan .NET Runtime yang cocok dengan arsitektur yang tercantum dalam pesan kesalahan. Anda kemudian dapat menginstalnya dengan mengunduh dan menjalankan Alat Penginstal.

.NET tersedia melalui berbagai manajer paket Linux. Untuk informasi selengkapnya, lihat Menginstal .NET di Linux. (Versi pratinjau .NET biasanya tidak tersedia melalui manajer paket.)

Anda perlu menginstal paket .NET Runtime untuk versi yang sesuai, seperti dotnet-runtime6.

Atau, pada halaman unduhan untuk versi .NET yang diperlukan, Anda dapat mengunduh Biner untuk arsitektur yang ditentukan.

Kerangka kerja yang diperlukan tidak ditemukan

Jika kerangka kerja yang diperlukan atau versi yang kompatibel tidak ditemukan, aplikasi gagal diluncurkan dengan pesan yang mirip dengan:

You must install or update .NET to run this application.

App: C:\repos\myapp\myapp.exe
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: C:\Program Files\dotnet\

The following frameworks were found:
  6.0.2 at [c:\Program Files\dotnet\shared\Microsoft.NETCore.App]

You must install or update .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: /usr/share/dotnet/

The following frameworks were found:
  6.0.2 at [/usr/share/dotnet/shared/Microsoft.NETCore.App]

You must install or update .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: /usr/local/share/dotnet/

The following frameworks were found:
  6.0.2 at [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]

Kesalahan menunjukkan nama, versi, dan arsitektur kerangka kerja yang hilang dan lokasi yang diharapkan untuk diinstal. Untuk menjalankan aplikasi, Anda dapat menginstal runtime yang kompatibel di ".NET location" yang ditentukan. Jika aplikasi menargetkan versi yang lebih rendah dari versi yang telah Anda instal dan Anda ingin menjalankannya pada versi yang lebih tinggi, Anda juga dapat mengonfigurasi perilaku roll-forward untuk aplikasi.

Menginstal runtime yang kompatibel

Pesan kesalahan menyertakan tautan untuk mengunduh kerangka kerja yang hilang. Anda dapat mengikuti tautan ini untuk masuk ke halaman unduhan yang sesuai.

Secara bergantian, Anda dapat mengunduh runtime dari halaman unduhan .NET . Ada beberapa unduhan runtime .NET.

Tabel berikut ini memperlihatkan kerangka kerja yang dimuat setiap runtime.

Unduhan runtime bahasa umum Kerangka kerja yang disertakan
ASP.NET Core Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
Runtime Desktop .NET Microsoft.NETCore.App
Microsoft.WindowsDesktop.App
Runtime .NET Microsoft.NETCore.App
Unduhan runtime bahasa umum Kerangka kerja yang disertakan
ASP.NET Core Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
Runtime .NET Microsoft.NETCore.App

Pilih unduhan runtime yang berisi kerangka kerja yang hilang, lalu instal.

Pada halaman unduhan untuk versi .NET yang diperlukan, temukan unduhan runtime yang cocok dengan arsitektur yang tercantum dalam pesan kesalahan. Anda mungkin ingin mengunduh Alat Penginstal.

.NET tersedia melalui berbagai manajer paket Linux. Lihat Menginstal .NET di Linux untuk detailnya. (Versi pratinjau .NET biasanya tidak tersedia melalui manajer paket.)

Anda perlu menginstal paket runtime .NET untuk versi yang sesuai, seperti dotnet-runtime6 atau dotnet-aspnet6.

Atau, pada halaman unduhan untuk versi .NET yang diperlukan, Anda dapat mengunduh Biner untuk arsitektur yang ditentukan.

Dalam kebanyakan kasus, ketika aplikasi yang gagal diluncurkan menggunakan penginstalan seperti itu, ".NET location" dalam pesan kesalahan menunjuk ke:

%ProgramFiles%\dotnet

/usr/share/dotnet/

/usr/local/share/dotnet/

Opsi lainnya

Ada opsi penginstalan dan solusi lain yang perlu dipertimbangkan.

Jalankan skrip dotnet-install

Unduh skrip dotnet-install untuk sistem operasi Anda. Jalankan skrip dengan opsi berdasarkan informasi dalam pesan kesalahan. Halaman referensi skrip dotnet-install menunjukkan semua opsi yang tersedia.

Luncurkan PowerShell dan jalankan:

dotnet-install.ps1 -Architecture <architecture> -InstallDir <directory> -Runtime <runtime> -Version <version>

Misalnya, pesan kesalahan di bagian sebelumnya akan sesuai dengan:

dotnet-install.ps1 -Architecture x64 -InstallDir "C:\Program Files\dotnet\" -Runtime dotnet -Version 5.0.15

Jika Anda mengalami kesalahan yang menyatakan bahwa menjalankan skrip dinonaktifkan, Anda mungkin perlu mengatur kebijakan eksekusi untuk memungkinkan skrip berjalan:

Set-ExecutionPolicy Bypass -Scope Process

Untuk informasi selengkapnya tentang penginstalan menggunakan skrip, lihat Menginstal dengan otomatisasi PowerShell.

./dotnet-install.sh --architecture <architecture> --install-dir <directory> --runtime <runtime> --version <version>

Misalnya, pesan kesalahan di bagian sebelumnya akan sesuai dengan:

./dotnet-install.sh --architecture x64 --install-dir /usr/share/dotnet/ --runtime dotnet --version 5.0.15

Untuk informasi selengkapnya tentang penginstalan menggunakan skrip, lihat Penginstalan skrip.

./dotnet-install.sh --architecture <architecture> --install-dir <directory> --runtime <runtime> --version <version>

Misalnya, pesan kesalahan di bagian sebelumnya akan sesuai dengan:

./dotnet-install.sh --architecture x64 --install-dir /usr/local/share/dotnet/ --runtime dotnet --version 5.0.15

Untuk informasi selengkapnya tentang penginstalan menggunakan skrip, lihat Menginstal .NET dengan skrip.

Mengunduh biner

Anda dapat mengunduh arsip biner .NET dari halaman unduhan. Dari kolom Biner dari unduhan runtime, unduh rilis biner yang cocok dengan arsitektur yang diperlukan. Ekstrak arsip yang diunduh ke ".NET location" yang ditentukan dalam pesan kesalahan.

Untuk informasi selengkapnya tentang penginstalan manual, lihat Menginstal .NET di Windows

Untuk informasi selengkapnya tentang penginstalan manual, lihat Menginstal .NET di Linux

Untuk informasi selengkapnya tentang penginstalan manual, lihat Menginstal .NET di macOS

Mengonfigurasi perilaku roll-forward

Jika Anda sudah memiliki versi kerangka kerja yang diperlukan yang lebih tinggi yang diinstal, Anda dapat membuat aplikasi berjalan pada versi yang lebih tinggi dengan mengonfigurasi perilaku roll-forward-nya.

Saat menjalankan aplikasi, Anda dapat menentukan --roll-forward opsi baris perintah atau mengatur DOTNET_ROLL_FORWARD variabel lingkungan. Secara default, aplikasi memerlukan kerangka kerja yang cocok dengan versi utama yang sama dengan yang ditargetkan aplikasi, tetapi dapat menggunakan versi minor atau patch yang lebih tinggi. Namun, pengembang aplikasi mungkin telah menentukan perilaku yang berbeda. Untuk informasi selengkapnya, lihat Roll-forward aplikasi yang bergantung pada kerangka kerja.

Nota

Karena menggunakan opsi ini memungkinkan aplikasi berjalan pada versi kerangka kerja yang berbeda dari yang dirancang, ini dapat mengakibatkan perilaku yang tidak diinginkan karena perubahan antar versi kerangka kerja.

Perubahan mendasar

Pencarian multi-tingkat dinonaktifkan untuk .NET 7 dan yang lebih baru

Di Windows, sebelum .NET 7, aplikasi dapat mencari kerangka kerja di beberapa lokasi penginstalan.

  1. Subdirektori relatif terhadap:

    • dotnet dapat dieksekusi saat menjalankan aplikasi melalui dotnet.
    • DOTNET_ROOT variabel lingkungan (jika diatur) saat menjalankan aplikasi melalui executable -nya (apphost).

  2. Lokasi penginstalan terdaftar secara global (jika diatur) di HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation.

  3. Lokasi %ProgramFiles%\dotnet penginstalan default (atau %ProgramFiles(x86)%\dotnet untuk proses 32-bit pada Windows 64-bit).

Perilaku pencarian multi-tingkat ini diaktifkan secara default tetapi dapat dinonaktifkan dengan mengatur variabel DOTNET_MULTILEVEL_LOOKUP=0lingkungan .

Untuk aplikasi yang menargetkan .NET 7 dan yang lebih baru, pencarian multi-tingkat sepenuhnya dinonaktifkan dan hanya satu lokasi—lokasi pertama tempat penginstalan .NET ditemukan—dicari. Ketika aplikasi dijalankan melalui dotnet, kerangka kerja hanya dicari dalam subdirektori relatif terhadap dotnet. Ketika aplikasi dijalankan melalui executable (apphost), kerangka kerja hanya dicari di lokasi pertama yang tercantum sebelumnya di mana .NET ditemukan.

Untuk informasi selengkapnya, lihat Pencarian multi-tingkat dinonaktifkan.

Lihat juga

  • Last updated on