Skip to content

Commit fab5d8a

Browse files
elinor-fungelinor-fung
committed
Add basic page for app launch failures
1 parent 1eac009 commit fab5d8a

File tree

2 files changed

+159
-0
lines changed

2 files changed

+159
-0
lines changed

‎docs/core/runtime-discovery/troubleshoot-app-launch.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: Troubleshoot app launch failures
3+
description: Learn about common reasons for app launch failures and possible solutions.
4+
ms.topic: troubleshooting
5+
ms.date: 03/24/2022
6+
zone_pivot_groups: operating-systems-set-one
7+
---
8+
9+
# Troubleshoot app launch failures
10+
11+
This article describes some common reasons and possible solutions for application launch failures.
12+
13+
## Required framework not found
14+
15+
[Framework-dependent applications](../deploying/index.md#publish-framework-dependent) rely on a .NET installation on your machine. If a required framework is not found or is not compatible with the required version, the application will fail to launch with a message similar to:
16+
17+
::: zone pivot="os-windows"
18+
19+
```console
20+
You must install or update .NET to run this application.
21+
22+
App: C:\repos\myapp\myapp.exe
23+
Architecture: x64
24+
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
25+
.NET location: C:\Program Files\dotnet\
26+
27+
The following frameworks were found:
28+
6.0.2 at [c:\Program Files\dotnet\shared\Microsoft.NETCore.App]
29+
```
30+
31+
::: zone-end
32+
33+
::: zone pivot="os-linux"
34+
35+
```bash
36+
You must install or update .NET to run this application.
37+
38+
App: /home/user/repos/myapp/myapp
39+
Architecture: x64
40+
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
41+
.NET location: /usr/share/dotnet/
42+
43+
The following frameworks were found:
44+
6.0.2 at [/usr/share/dotnet/shared/Microsoft.NETCore.App]
45+
```
46+
47+
::: zone-end
48+
49+
::: zone pivot="os-macos"
50+
51+
```bash
52+
You must install or update .NET to run this application.
53+
54+
App: /home/user/repos/myapp/myapp
55+
Architecture: x64
56+
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
57+
.NET location: /usr/local/share/dotnet/
58+
59+
The following frameworks were found:
60+
6.0.2 at [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
61+
```
62+
63+
::: zone-end
64+
65+
The error indicates the name, version, and architecture of the missing framework and the location at which it is expected to be installed. In order to run the application, you can [install a compatible framework](#install-a-compatible-framework) at the specified ".NET location". If the application is targeting a lower version than one you have installed and you would like to run it on a higher version, you can also [configure roll-forward behavior](#configure-roll-forward-behavior) for the application.
66+
67+
### Install a compatible framework
68+
69+
The error message includes a link to download the missing framework. You can follow this link to get the appropriate download page. Alternately, the [.NET downloads](https://dotnet.microsoft.com/download/dotnet) page offers all available versions of .NET. Select the version matching the one listed in the error message.
70+
71+
Every version of .NET offers three different runtime downloads. The table below shows the frameworks contained by each of them.
72+
73+
| Download name | Included frameworks |
74+
| -------------------- | ------------------- |
75+
| ASP.NET Core Runtime | Microsoft.AspNetCore.App<br/>Microsoft.NETCore.App |
76+
| .NET Desktop Runtime | Microsoft.NETCore.App<br/>Microsoft.WindowsDesktop.App |
77+
| .NET Runtime | Microsoft.NETCore.App |
78+
79+
To install a compatible framework, on the download page for the required .NET version, find a runtime download containing the missing framework. Once you have found the appropriate runtime download, you can then either install it using an [installer](#run-an-installer) or [download the binaries](#download-binaries) and extract them to the desired location.
80+
81+
#### Run an installer
82+
83+
If your existing installation of .NET was installed through an installer or package manager, then also installing the required framework through an installer or package manager is likely the simpler option. Otherwise, you can [download binaries](#download-binaries) instead of using an installer.
84+
85+
In most cases, when the application that failed to launch is using such an installation, the ".NET location" in the error message would point to
86+
::: zone pivot="os-windows"
87+
`%ProgramFiles%\dotnet`
88+
::: zone-end
89+
::: zone pivot="os-linux"
90+
`/usr/share/dotnet/`
91+
::: zone-end
92+
::: zone pivot="os-macos"
93+
`/usr/local/share/dotnet/`
94+
::: zone-end
95+
96+
::: zone pivot="os-windows,os-macos"
97+
Download the installer matching the required architecture from the **Installers** column of the runtime download. Run the downloaded installer.
98+
::: zone-end
99+
::: zone pivot="os-linux"
100+
Different Linux distributions provide .NET through different package managers. See [Install .NET on Linux](../install/linux.md) for details. Note that preview versions of .NET are not available through package managers.
101+
::: zone-end
102+
103+
#### Download binaries
104+
105+
Download a binary release matching the required architecture from the **Binaries** column of the runtime download. Extract the downloaded archive to the ".NET location" specified in the error message.
106+
107+
::: zone pivot="os-windows"
108+
For more details on manual installation, see [Install .NET on Windows](../install/windows.md#download-and-manually-install)
109+
::: zone-end
110+
111+
::: zone pivot="os-linux"
112+
For more details on manual installation, see [Install .NET on Linux](../install/linux.md#manual-installation)
113+
::: zone-end
114+
115+
::: zone pivot="os-macos"
116+
For more details on manual installation, see [Install .NET on macOS](../install/macos.md#download-and-manually-install)
117+
::: zone-end
118+
119+
### Configure roll-forward behavior
120+
121+
If you already have a higher version of the required framework installed, you can make the application ron on that higher version by configuring its roll-forward behavior.
122+
123+
When running the application, you can specify the [`--roll-forward` command line option](../tools/dotnet.md#runtime-options) or setting the [`DOTNET_ROLL_FORWARD` environment variable](../tools/dotnet-environment-variables.md#dotnet_roll_forward).
124+
By default, an application will require a framework matching the same major version that the application targets, but can use a higher minor or patch version. However, application developers may have specified a different behavior. For more details, see [Framework-dependent apps roll-forward](../versions/selection.md#framework-dependent-apps-roll-forward).
125+
126+
Note that, since using this option can let the application run on a different framework version than the one for which it was designed, it may result in unintended behavior in the application due to changes between versions of a framework.
127+
128+
::: zone pivot="os-windows"
129+
130+
## Breaking changes
131+
132+
### Multi-level lookup disabled for .NET 7.0 and later
133+
134+
On Windows, before .NET 7.0, the application could search for frameworks in multiple [install locations](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md).
135+
136+
1. Subdirectories relative to:
137+
138+
- `dotnet` executable when running the application through `dotnet`
139+
- `DOTNET_ROOT` environment variable (if set) when running the application through its executable (`apphost`)
140+
141+
2. Globally registered install location (if set) in `HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation`
142+
3. Default install location of `%ProgramFiles%\dotnet` (or `%ProgramFiles(x86)%\dotnet` for 32-bit processes on 64-bit Windows)
143+
144+
This behavior&mdash;multi-level lookup&mdash;was enabled by default, but could be disabled by setting the environment variable `DOTNET_MULTILEVEL_LOOKUP=0`.
145+
146+
For applications targeting .NET 7.0 and later, multi-level lookup is completely disabled and only one location&mdash;the first location where a .NET installation is found&mdash;is searched. When running an application through `dotnet`, frameworks are only searched for in subdirectories relative to `dotnet`. When running an application through its executable (`apphost`), frameworks are only searched for in the first of the above locations where .NET is found.
147+
148+
For more details, see [Disable multi-level lookup by default](https://github.com/dotnet/designs/blob/main/accepted/2022/disable-multi-level-lookup-by-default.md).
149+
150+
::: zone-end
151+
152+
## See also
153+
154+
- [Install .NET](../install/index.yml)
155+
- [.NET install locations](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md)
156+
- [Check installed .NET versions](../install/how-to-detect-installed-versions.md)
157+
- [Framework-dependent applications](../deploying/index.md#publish-framework-dependent)

‎docs/fundamentals/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1655,6 +1655,8 @@ items:
16551655
href: ../core/runtime-config/networking.md
16561656
- name: Threading settings
16571657
href: ../core/runtime-config/threading.md
1658+
- name: Troubleshoot app launch failures
1659+
href: ../core/runtime-discovery/troubleshoot-app-launch.md
16581660
- name: Deployment models
16591661
items:
16601662
- name: Overview

0 commit comments

Comments
 (0)