Skip to content

Update app-launch topic #29738

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
richlander merged 3 commits into from
Jun 7, 2022
Merged

Update app-launch topic #29738

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e3b97e
Update app-launch topic
richlander Jun 6, 2022
e6a9d8c
Streamline content
richlander Jun 6, 2022
a2e2260
Apply suggestions from code review
richlander Jun 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 45 additions & 21 deletions docs/core/runtime-discovery/troubleshoot-app-launch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,13 @@ zone_pivot_groups: operating-systems-set-one

# Troubleshoot app launch failures

This article describes some common reasons and possible solutions for application launch failures.
This article describes some common reasons and possible solutions for application launch failures. It relates to [framework-dependent applications](../deploying/index.md#publish-framework-dependent), which rely on a .NET installation on your machine.

If you already know which .NET version you need, you can download it from [.NET downloads](https://dotnet.microsoft.com/download/dotnet).

## .NET installation not found

[Framework-dependent applications](../deploying/index.md#publish-framework-dependent) rely on a .NET installation on your machine. If a .NET installation is not found, the application will fail to launch with a message similar to:
If a .NET installation is not found, the application fails to launch with a message similar to:

::: zone pivot="os-windows"

Expand Down Expand Up @@ -40,17 +42,23 @@ Host version: 7.0.0

::: zone-end

The error indicates the required architecture and host version. To run the application, you must [install the corresponding version of the .NET Runtime](#install-net).
The error message includes a link to download .NET. You can follow this link to get to the appropriate download page. You can also pick the .NET version (specified by `Host version`) from [.NET downloads](https://dotnet.microsoft.com/download/dotnet).

### Install .NET
::: zone pivot="os-windows,os-macos"
On the [download page](https://dotnet.microsoft.com/download/dotnet) for the required .NET version, find the **.NET Runtime** download that matches the architecture listed in the error message. You can then install it by downloading and running an **Installer**.
::: zone-end

The error message includes a link to download .NET. You can follow this link to get to the appropriate download page. Alternately, the [.NET downloads](https://dotnet.microsoft.com/download/dotnet) page offers all available versions of .NET. Select the version that matches the host version listed in the error message.
::: zone pivot="os-linux"
.NET is available through various Linux package managers. See [Install .NET on Linux](../install/linux.md) for details. Note that preview versions of .NET are typically not available through package managers.

On the download page for the required .NET version, find the **.NET Runtime** download that matches the architecture listed in the error message. You can then install it by [running an installer](#run-an-installer).
You need to install the .NET Runtime package for the appropriate version, like `dotnet-runtime6`.
::: zone-end

Alternatively, on the [download page](https://dotnet.microsoft.com/download/dotnet) for the required .NET version, you can download [**Binaries**](#download-binaries) for the specified architecture.

## Required framework not found

[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:
If a required framework or compatible version is not found, the application fails to launch with a message similar to:

::: zone pivot="os-windows"

Expand Down Expand Up @@ -102,21 +110,42 @@ The following frameworks were found:

The error indicates the name, version, and architecture of the missing framework and the location at which it is expected to be installed. 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.

### Install a compatible framework
### Install a compatible runtime

The error message includes a link to download the missing framework. You can follow this link to get to the appropriate download page.
Comment thread
vitek-karas marked this conversation as resolved.

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.
Alternately, you can download a runtime from the [.NET downloads](https://dotnet.microsoft.com/download/dotnet) page. There are multiple .NET runtime downloads.

Every version of .NET offers three different runtime downloads. The following table shows the frameworks that each contains.
The following table shows the frameworks that each runtime contains.

| Download name | Included frameworks |
::: zone pivot="os-windows"
| Runtime download | Included frameworks |
| -------------------- | ------------------- |
| ASP.NET Core Runtime | Microsoft.NETCore.App<br/>Microsoft.AspNetCore.App |
| .NET Desktop Runtime | Microsoft.NETCore.App<br/>Microsoft.WindowsDesktop.App |
| .NET Runtime | Microsoft.NETCore.App |
::: zone-end

::: zone pivot="os-linux,os-macos"
| Runtime download | Included frameworks |
| -------------------- | ------------------- |
| ASP.NET Core Runtime | Microsoft.NETCore.App<br/>Microsoft.AspNetCore.App |
| .NET Runtime | Microsoft.NETCore.App |
::: zone-end

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 [script](#run-the-dotnet-install-script). You can also [download the binaries](#download-binaries) and extract them to the desired location.
Select a runtime download containing the missing framework, and install it.

If your existing installation of .NET was installed through an installer or package manager, then the recommended option is to also install the required framework [through an installer](#run-an-installer) or package manager. Otherwise, you can [run the install script](#run-the-dotnet-install-script) or [download the binaries](#download-binaries).
::: zone pivot="os-windows,os-macos"
On the [download page](https://dotnet.microsoft.com/download/dotnet) for the required .NET version, find the runtime download that matches the architecture listed in the error message. You likely want to download an **Installer**.
::: zone-end

::: zone pivot="os-linux"
.NET is available through various Linux package managers. See [Install .NET on Linux](../install/linux.md) for details. Note that preview versions of .NET are typically not available through package managers.

You need to install the .NET runtime package for the appropriate version, like `dotnet-runtime6` or `dotnet-aspnet6`.
::: zone-end

Alternatively, on the [download page](https://dotnet.microsoft.com/download/dotnet) for the required .NET version, you can download [**Binaries**](#download-binaries) for the specified architecture.

In most cases, when the application that failed to launch is using such an installation, the ".NET location" in the error message points to:
::: zone pivot="os-windows"
Expand All @@ -129,14 +158,9 @@ In most cases, when the application that failed to launch is using such an insta
`/usr/local/share/dotnet/`
::: zone-end

#### Run an installer
## Other options

::: zone pivot="os-windows,os-macos"
From the **Installers** column of the runtime download, download the installer matching the required architecture. Run the downloaded installer.
::: zone-end
::: zone pivot="os-linux"
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.
::: zone-end
There are other installation and workaround options to consider.

#### Run the dotnet-install script

Expand Down Expand Up @@ -196,7 +220,7 @@ For more details on installation using the script, see [Install with bash automa

#### Download binaries

From the **Binaries** column of the runtime download, download the binary release matching the required architecture. Extract the downloaded archive to the ".NET location" specified in the error message.
You can download a binary archive of .NET from the [download page](https://dotnet.microsoft.com/download/dotnet). From the **Binaries** column of the runtime download, download the binary release matching the required architecture. Extract the downloaded archive to the ".NET location" specified in the error message.

::: zone pivot="os-windows"
For more details on manual installation, see [Install .NET on Windows](../install/windows.md#download-and-manually-install)
Expand Down