通过

排查应用启动失败问题

  • 项目

本文介绍了应用程序启动失败的一些常见原因和可能的解决方案。 它与依赖于框架的应用程序有关，这些应用程序依赖于计算机上的 .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 的链接。 可以通过此链接来访问相应的下载页面。 此外，还可以从 Host version.NET 下载中选取 .NET 版本（由 指定）。

在所需的 .NET 版本的下载页面上，找到与错误消息中列出的体系结构匹配的 .NET 运行时下载。 然后，可以通过下载并运行安装程序来安装它。

.NET 可以通过各种 Linux 包管理器获得。 有关详细信息，请参阅在 Linux 上安装 .NET。 （预览版 .NET 通常无法通过包管理器获取。）

需要为相应的版本安装 .NET 运行时包，比如 dotnet-runtime6。

或者，在所需的 .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 通常无法通过包管理器获取。）

需要为相应的版本安装 .NET 运行时包，比如 dotnet-runtime6 或 dotnet-aspnet6。

或者，在所需的 .NET 版本的下载页面上，可以下载指定体系结构的二进制文件。

在大多数情况下，当无法启动的应用程序使用此类安装时，错误消息中的“.NET 位置”指向：

%ProgramFiles%\dotnet

/usr/share/dotnet/

/usr/local/share/dotnet/

其他选项

还需要考虑一些其他安装和解决方法选项。

运行 dotnet-install 脚本

下载适用于你的操作系统的 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（或 %ProgramFiles(x86)%\dotnet，对于 64 位 Windows 上的 32 位进程而言）的默认安装位置。

此多级别查找行为是默认启用的，但可以通过设置环境变量 DOTNET_MULTILEVEL_LOOKUP=0 来禁用。

对于面向 .NET 7 和更高版本的应用程序，将完全禁用多级别查找，并且仅搜索一个位置（在其中找到 .NET 安装的第一个位置）。 通过 dotnet 运行应用程序时，只会在与 dotnet 相对的子目录中搜索框架。 通过应用程序的可执行文件 (apphost) 运行该应用程序时，只会在找到 .NET 的上述第一个位置中搜索框架。

有关详细信息，请参阅禁用多级别查找。

请参阅