針對應用程式啟動失敗進行疑難排解

  • 發行項

本文說明應用程式啟動失敗的常見原因和可能的解決方案。 這與依賴您機器上 .NET 安裝的架構相依應用程式有關。

如果您已經知道您需要哪一個 .NET 版本，您可以從 .NET 下載進行下載。

找不到 .NET 安裝

如果找不到 .NET 安裝，應用程式將無法啟動，並會顯示類似下列的訊息：

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

這可能是由套件混合所致。

全域安裝會在下列位置註冊：/etc/dotnet/install_location。 如需詳細資訊，請參閱安裝位置。

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

全域安裝會在下列位置註冊：/etc/dotnet/install_location。 如需詳細資訊，請參閱安裝位置。

錯誤訊息包含下載 .NET 的連結。 您可以遵循該連結來存取適當的下載頁面。 您也可以從 .NET 下載選擇 .NET 版本 (由 Host version 指定)。

在必要 .NET 版本的下載頁面上，尋找符合錯誤訊息中所列架構的 .NET 執行階段下載。 接著，您可以下載並執行安裝程式來安裝。

.NET 可透過各種 Linux 套件管理員取得。 如需詳細資訊，請參閱在 Linus 上安裝 .NET。 (.NET 預覽版通常無法透過套件管理員取得。)

您需要為適當的版本 (例如 dotnet-runtime6) 安裝 .NET 執行階段套件。

或者，在必要 .NET 版本的下載頁面上，您可以下載指定架構的二進位檔。

找不到必要的架構

如果找不到必要的架構或相容版本，應用程式將無法啟動，並顯示類似下列的訊息：

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]

此錯誤指出遺漏架構的名稱、版本和架構，以及預期要安裝的位置。 若要執行應用程式，您可以在指定的「.NET 位置」安裝相容的執行階段。 如果應用程式的目標版本低於您已安裝的版本，而且您想要在較高版本上執行它，您也可以為應用程式設定向前復原行為 。

安裝相容的執行階段

錯誤訊息包含下載遺漏架構的連結。 您可以遵循該連結來存取適當的下載頁面。

或者，您可以從.NET 下載頁面下載執行階段。 有多個 .NET 執行階段下載。

下表顯示每個執行階段所包含的架構。

執行階段下載 包含的架構
ASP.NET Core 執行階段 Microsoft.NETCore.App
Microsoft.AspNetCore.App
.NET 桌面執行階段 Microsoft.NETCore.App
Microsoft.WindowsDesktop.App
.NET 執行階段 Microsoft.NETCore.App
執行階段下載 包含的架構
ASP.NET Core 執行階段 Microsoft.NETCore.App
Microsoft.AspNetCore.App
.NET 執行階段 Microsoft.NETCore.App

選取包含遺漏架構的執行階段下載，然後加以安裝。

在必要 .NET 版本的下載頁面上，尋找符合錯誤訊息中所列架構的執行階段下載。 您可能想要下載安裝程式。

.NET 可透過各種 Linux 套件管理員取得。 如需詳細資料，請參閱在 Linux 上安裝 .NET。 (.NET 預覽版通常無法透過套件管理員取得。)

您需要為適當的版本 (例如 dotnet-runtime6 或 dotnet-aspnet6) 安裝 .NET 執行階段套件。

或者，在必要 .NET 版本的下載頁面上，您可以下載指定架構的二進位檔。

在大部分情況下，當無法啟動的應用程式使用這類安裝時，錯誤訊息中的「.NET 位置」會指向：

%ProgramFiles%\dotnet

/usr/share/dotnet/

/usr/local/share/dotnet/

其他選項

還有其他安裝和因應措施選項需要考慮。

執行 dotnet 安裝指令碼

下載適用於您作業系統的 dotnet-install 指令碼。 根據錯誤訊息中的資訊，以選項執行指令碼。 dotnet-install 指令碼參考頁面會顯示所有可用的選項。

啟動 PowerShell 並執行：

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

例如，上一區段中的錯誤訊息會對應至：

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

如果您遇到錯誤，指出執行中的指令碼已停用，您可能需要設定執行原則以允許指令碼執行：

Set-ExecutionPolicy Bypass -Scope Process

如需使用指令碼安裝的詳細資訊，請參閱使用 PowerShell 自動化安裝。

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

例如，上一區段中的錯誤訊息會對應至：

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

如需使用指令碼安裝的詳細資訊，請參閱指令碼安裝。

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

例如，上一區段中的錯誤訊息會對應至：

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

如需使用指令碼安裝的詳細資訊，請參閱使用 Bash 自動化安裝。

下載二進位檔

您可以從下載頁面下載 .NET 的二進位檔封存。 從執行階段下載的二進位資料行，下載符合所需架構的二進位版本。 將下載的封存解壓縮到錯誤訊息中指定的「.NET 位置」。

如需手動安裝的詳細資訊，請參閱在 Windows 上安裝 .NET

如需手動安裝的詳細資訊，請參閱在 Linux 上安裝 .NET

如需手動安裝的詳細資訊，請參閱在 macOS 上安裝 .NET

設定向前復原行為

如果您已安裝較高版本的必要架構，您可以藉由設定向前復原行為，讓應用程式在該較高版本上執行。

執行應用程式時，您可以指定--roll-forward 命令列選項或設定DOTNET_ROLL_FORWARD 環境變數。 根據預設，應用程式需要符合應用程式目標相同主要版本的架構，但可以使用較高的次要或修補程式版本。 不過，應用程式開發人員可能已指定不同的行為。 如需詳細資訊，請參閱向前復原架構相依的應用程式。

注意

由於使用此選項可讓應用程式在與設計架構版本不同的架構版本上執行，因此可能會因為架構版本之間的變更而造成非預期的行為。

重大變更

已停用 .NET 7 和更新版本的多層級查閱

在 Windows 上，在 .NET 7 之前，應用程式可以在多個安裝位置中搜尋架構。

  1. 子目錄相對於：

    • dotnet 透過 dotnet 執行應用程式時的可執行檔。
    • 透過其可執行檔 (apphost) 執行應用程式時的 DOTNET_ROOT 環境變數 (若有設定)。

  2. 在 HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation 全域註冊的安裝位置 (若有設定)。

  3. %ProgramFiles%\dotnet 的預設安裝位置 (或 64 位元 Windows 上 32 位元處理序的 %ProgramFiles(x86)%\dotnet)。

預設會啟用此多層級查閱行為，但可藉由設定環境變數 DOTNET_MULTILEVEL_LOOKUP=0 來停用。

針對以 .NET 7 和更新版本為目標的應用程式，會完全停用多層級查閱且只會搜尋一個位置，也就是找到 .NET 安裝的第一個位置。 當應用程式透過 dotnet 執行時，架構只會在相對於 dotnet 的子目錄中搜尋。 當應用程式透過其可執行檔 (apphost) 執行時，則只會在先前列出找到 .NET 位置中的第一個位置搜尋架構。

如需詳細資訊，請參閱已停用多層級查閱。

另請參閱