Behandeln von App-Startfehlern

  • Artikel

In diesem Artikel werden einige häufige Ursachen und mögliche Lösungen für Fehler beim Starten von Anwendungen beschrieben. Der Artikel bezieht sich auf frameworkabhängige Anwendungen, die eine .NET-Installation auf Ihrem Computer erfordern.

Wenn Sie bereits wissen, welche .NET-Version Sie benötigen, können Sie sie unter .NET-Downloads herunterladen.

.NET-Installation nicht gefunden

Wenn keine .NET-Installation gefunden wird, kann die Anwendung nicht gestartet werden, und es wird eine Meldung wie die folgende angezeigt:

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

Dies kann auf eine Paketverwechslung zurückzuführen sein.

Globale Installationen werden am folgenden Speicherort registriert: /etc/dotnet/install_location. Weitere Informationen finden Sie unter Installationsspeicherorte.

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

Globale Installationen werden am folgenden Speicherort registriert: /etc/dotnet/install_location. Weitere Informationen finden Sie unter Installationsspeicherorte.

Die Fehlermeldung enthält einen Link zum Herunterladen von .NET. Sie können diesem Link folgen, um zur entsprechenden Downloadseite zu gelangen. Sie können die .NET-Version (angegeben durch Host version) auch unter .NET-Downloads auswählen.

Suchen Sie auf der Downloadseite für die erforderliche .NET-Version nach dem .NET-Runtime-Download für die in der Fehlermeldung angegebene Architektur. Anschließend können Sie die Runtime installieren, indem Sie ein Installationsprogramm herunterladen und ausführen.

.NET ist über verschiedene Linux-Paket-Manager verfügbar. Weitere Informationen finden Sie unter Installieren von .NET unter Linux. (Vorschauversionen von .NET sind in der Regel nicht über Paket-Manager verfügbar.)

Sie müssen das .NET-Runtimepaket für die entsprechende Version installieren (z. B dotnet-runtime6).

Alternativ können Sie auf der Downloadseite für die erforderliche .NET-Version Binärdateien für die angegebene Architektur herunterladen.

Erforderliches Framework nicht gefunden

Wenn ein erforderliches Framework oder eine kompatible Version nicht gefunden wird, kann die Anwendung nicht gestartet werden, und es wird eine Meldung wie die folgende angezeigt:

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]

Die Fehlermeldung enthält den Namen, die Version und die Architektur des fehlenden Frameworks sowie den erwarteten Installationsspeicherort. Zum Ausführen der Anwendung können Sie am angegebenen .NET-Speicherort eine kompatible Runtime installieren. Wenn die Anwendung auf eine niedrigere Version als Ihre installierte Version ausgerichtet ist und Sie die Anwendung unter einer höheren Version ausführen möchten, können Sie für die Anwendung auch das Rollforwardverhalten konfigurieren.

Installieren einer kompatiblen Runtime

Die Fehlermeldung enthält einen Link zum Herunterladen des fehlenden Frameworks. Sie können diesem Link folgen, um zur entsprechenden Downloadseite zu gelangen.

Alternativ können Sie eine Runtime von der .NET-Downloadseite herunterladen. Es gibt mehrere Downloads der .NET-Runtime.

In der folgenden Tabelle sind die Frameworks aufgeführt, die in jeder Runtime enthalten sind.

Runtimedownload Enthaltene Frameworks
ASP.NET Core-Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
.NET-Desktopruntime Microsoft.NETCore.App
Microsoft.WindowsDesktop.App
.Net-Runtime Microsoft.NETCore.App
Runtimedownload Enthaltene Frameworks
ASP.NET Core-Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
.Net-Runtime Microsoft.NETCore.App

Wählen Sie einen Runtimedownload aus, der das fehlende Framework enthält, und installieren Sie es.

Suchen Sie auf der Downloadseite für die erforderliche .NET-Version nach dem Runtimedownload für die in der Fehlermeldung angegebene Architektur. Wahrscheinlich möchten Sie ein Installationsprogramm herunterladen.

.NET ist über verschiedene Linux-Paket-Manager verfügbar. Weitere Informationen finden Sie unter Installieren von .NET unter Linux. (Vorschauversionen von .NET sind in der Regel nicht über Paket-Manager verfügbar.)

Sie müssen das .NET-Runtimepaket für die entsprechende Version installieren (z. B dotnet-runtime6 oder dotnet-aspnet6).

Alternativ können Sie auf der Downloadseite für die erforderliche .NET-Version Binärdateien für die angegebene Architektur herunterladen.

Wenn die Anwendung, die nicht gestartet werden konnte, eine solche Installation verwendet, verweist der .NET-Speicherort in der Fehlermeldung meist auf den folgenden Speicherort:

%ProgramFiles%\dotnet

/usr/share/dotnet/

/usr/local/share/dotnet/

Weitere Optionen

Es gibt weitere Installations- und Problemumgehungsoptionen, die Sie berücksichtigen sollten.

Ausführen des dotnet-install-Skripts

Laden Sie das dotnet-install-Skript für Ihr Betriebssystem herunter. Führen Sie das Skript mit Optionen aus, die auf den Informationen in der Fehlermeldung basieren. Auf der Referenzseite zum dotnet-install-Skript sind alle verfügbaren Optionen aufgeführt.

Starten Sie PowerShell, und führen Sie Folgendes aus:

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

Die Fehlermeldung im vorherigen Abschnitt würde z. B. der folgenden Ausgabe entsprechen:

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

Wenn ein Fehler auftritt, der besagt, dass die Ausführung von Skripts deaktiviert ist, müssen Sie möglicherweise die Ausführungsrichtlinie festlegen, damit das Skript ausgeführt werden kann:

Set-ExecutionPolicy Bypass -Scope Process

Weitere Informationen zur Installation mithilfe des Skripts finden Sie unter Installieren mit PowerShell-Automatisierung.

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

Die Fehlermeldung im vorherigen Abschnitt würde z. B. der folgenden Ausgabe entsprechen:

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

Weitere Informationen zur Installation mithilfe des Skripts finden Sie unter Per Skript gesteuerte Installation.

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

Die Fehlermeldung im vorherigen Abschnitt würde z. B. der folgenden Ausgabe entsprechen:

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

Weitere Informationen zur Installation mithilfe des Skripts finden Sie unter Installieren mit Bash-Automatisierung.

Herunterladen von Binärdateien

Sie können ein Binärarchiv von .NET von der Downloadseite herunterladen. Laden Sie in der Spalte Binärdateien des Runtimedownloads das Binärrelease für die benötigte Architektur herunter. Extrahieren Sie das heruntergeladene Archiv an dem .NET-Speicherort, der in der Fehlermeldung angegeben ist.

Weitere Informationen zur manuellen Installation finden Sie unter Installieren von .NET unter Windows.

Weitere Informationen zur manuellen Installation finden Sie unter Installieren von .NET unter Linux.

Weitere Informationen zur manuellen Installation finden Sie unter Installieren von .NET unter macOS.

Konfigurieren des Rollforwardverhaltens

Wenn Sie bereits eine höhere Version des erforderlichen Frameworks installiert haben, können Sie die Anwendung unter dieser höheren Version ausführen, indem Sie das Rollforwardverhalten der Anwendung konfigurieren.

Beim Ausführen der Anwendung können Sie die Befehlszeilenoption „--roll-forward“ angeben oder die Umgebungsvariable DOTNET_ROLL_FORWARD festlegen. Standardmäßig erfordert eine Anwendung ein Framework, das der vorgesehenen Hauptversion der Anwendung entspricht, es kann jedoch eine höhere Neben- oder Patchversion verwendet werden. Es ist allerdings möglich, dass die Anwendungsentwickler*innen ein anderes Verhalten angegeben haben. Weitere Informationen finden Sie unter Von Frameworks abhängige Apps führen einen Rollforward aus.

Hinweis

Da die Anwendung bei Verwendung dieser Option unter einer anderen Frameworkversion ausgeführt werden kann als der Version, für die sie entworfen wurde, kann es aufgrund von Änderungen zwischen Versionen eines Frameworks zu unbeabsichtigtem Verhalten kommen.

Aktuelle Änderungen

Lookup auf mehreren Ebenen für .NET 7 und höher deaktiviert

Unter Windows konnte die Anwendung vor .NET 7 an mehreren Installationsspeicherorten nach Frameworks suchen.

  1. Unterverzeichnisse relativ zu:

    • Ausführbare dotnet-Datei bei Ausführung der Anwendung über dotnet
    • DOTNET_ROOT-Umgebungsvariable (sofern festgelegt) bei Ausführung der Anwendung über die ausführbare Datei (apphost)

  2. Global registrierter Installationsspeicherort (sofern festgelegt) in HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation

  3. Standardinstallationsspeicherort von %ProgramFiles%\dotnet (oder %ProgramFiles(x86)%\dotnet für 32-Bit-Prozesse unter 64-Bit-Windows)

Dieses Verhalten für das Lookup auf mehreren Ebenen war standardmäßig aktiviert, konnte aber durch Festlegen der Umgebungsvariable DOTNET_MULTILEVEL_LOOKUP=0 deaktiviert werden.

Bei Anwendungen für .NET 7 und höher ist das Lookup auf mehreren Ebenen vollständig deaktiviert, und es wird nur ein Speicherort durchsucht – der erste Speicherort, an dem eine .NET-Installation gefunden wird. Wenn eine Anwendung über dotnet ausgeführt wird, wird nur in Unterverzeichnissen relativ zu dotnet nach Frameworks gesucht. Wenn eine Anwendung über ihre ausführbare Datei (apphost) ausgeführt wird, wird nur am ersten der zuvor genannten Speicherorte, an denen .NET gefunden wird, nach Frameworks gesucht.

Weitere Informationen finden Sie unter Suche mit mehreren Ebenen ist deaktiviert.

Siehe auch