Rozwiązywanie problemów z błędami uruchamiania aplikacji
W tym artykule opisano niektóre typowe przyczyny i możliwe rozwiązania błędów uruchamiania aplikacji. Dotyczy to aplikacji zależnych od platformy, które opierają się na instalacji platformy .NET na maszynie.
Jeśli wiesz już, której wersji platformy .NET potrzebujesz, możesz pobrać ją z plików do pobrania platformy .NET.
Nie można odnaleźć instalacji platformy .NET
Jeśli instalacja platformy .NET nie zostanie znaleziona, uruchomienie aplikacji nie powiedzie się z komunikatem podobnym do następującego:
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
Może to być spowodowane mieszaniem pakietów.
Instalacje globalne są rejestrowane w następującej lokalizacji: /etc/dotnet/install_location. Aby uzyskać więcej informacji, zobacz lokalizacje instalacji.
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
Instalacje globalne są rejestrowane w następującej lokalizacji: /etc/dotnet/install_location. Aby uzyskać więcej informacji, zobacz lokalizacje instalacji.
Komunikat o błędzie zawiera link do pobrania platformy .NET. Możesz skorzystać z tego linku, aby przejść do odpowiedniej strony pobierania. Możesz również wybrać wersję platformy .NET (określoną przez Host version) z plików do pobrania platformy .NET.
Na stronie pobierania wymaganej wersji platformy .NET znajdź pobieranie środowiska uruchomieniowego platformy .NET zgodne z architekturą wymienioną w komunikacie o błędzie. Następnie można go zainstalować, pobierając i uruchamiając Instalatora.
Platforma .NET jest dostępna za pośrednictwem różnych menedżerów pakietów systemu Linux. Aby uzyskać więcej informacji, zobacz Instalowanie platformy .NET w systemie Linux. (Wersje zapoznawcza platformy .NET nie są zwykle dostępne za pośrednictwem menedżerów pakietów).
Należy zainstalować pakiet środowiska uruchomieniowego platformy .NET dla odpowiedniej wersji, na przykład dotnet-runtime6.
Alternatywnie na stronie pobierania dla wymaganej wersji platformy .NET można pobrać pliki binarne dla określonej architektury.
Nie znaleziono wymaganej platformy
Jeśli nie można odnaleźć wymaganej platformy lub zgodnej wersji, uruchomienie aplikacji nie powiedzie się z komunikatem podobnym do następującego:
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]
Błąd wskazuje nazwę, wersję i architekturę brakującej platformy oraz lokalizację, w której ma zostać zainstalowana. Aby uruchomić aplikację, możesz zainstalować zgodne środowisko uruchomieniowe w określonej lokalizacji .NET. Jeśli aplikacja jest przeznaczona dla starszej wersji niż zainstalowana i chcesz ją uruchomić w nowszej wersji, możesz również skonfigurować zachowanie wycofywania dla aplikacji.
Instalowanie zgodnego środowiska uruchomieniowego
Komunikat o błędzie zawiera link umożliwiający pobranie brakującej platformy. Możesz skorzystać z tego linku, aby przejść do odpowiedniej strony pobierania.
Alternatywnie możesz pobrać środowisko uruchomieniowe ze strony pobierania platformy .NET. Istnieje wiele plików do pobrania środowiska uruchomieniowego platformy .NET.
W poniższej tabeli przedstawiono struktury, które zawiera każde środowisko uruchomieniowe.
| Pobieranie środowiska uruchomieniowego | Uwzględnione struktury |
|---|---|
| ASP.NET Core Runtime | Microsoft.NETCore.App Microsoft.AspNetCore.App |
| Środowisko uruchomieniowe programu .NET Desktop | Microsoft.NETCore.App Microsoft.WindowsDesktop.App |
| Środowisko uruchomieniowe platformy .NET | Microsoft.NETCore.App |
| Pobieranie środowiska uruchomieniowego | Uwzględnione struktury |
|---|---|
| ASP.NET Core Runtime | Microsoft.NETCore.App Microsoft.AspNetCore.App |
| Środowisko uruchomieniowe platformy .NET | Microsoft.NETCore.App |
Wybierz pobieranie środowiska uruchomieniowego zawierającego brakującą strukturę, a następnie zainstaluj ją.
Na stronie pobierania wymaganej wersji platformy .NET znajdź pobieranie środowiska uruchomieniowego zgodne z architekturą wymienioną w komunikacie o błędzie. Prawdopodobnie chcesz pobrać Instalatora.
Platforma .NET jest dostępna za pośrednictwem różnych menedżerów pakietów systemu Linux. Aby uzyskać szczegółowe informacje, zobacz Instalowanie platformy .NET w systemie Linux . (Wersje zapoznawcza platformy .NET nie są zwykle dostępne za pośrednictwem menedżerów pakietów).
Należy zainstalować pakiet środowiska uruchomieniowego platformy .NET dla odpowiedniej wersji, takiej jak dotnet-runtime6 lub dotnet-aspnet6.
Alternatywnie na stronie pobierania dla wymaganej wersji platformy .NET można pobrać pliki binarne dla określonej architektury.
W większości przypadków, gdy uruchomienie aplikacji, która nie powiodła się, korzysta z takiej instalacji, lokalizacja ".NET" w komunikacie o błędzie wskazuje:
%ProgramFiles%\dotnet
/usr/share/dotnet/
/usr/local/share/dotnet/
Inne opcje
Istnieją inne opcje instalacji i obejścia, które należy wziąć pod uwagę.
Uruchamianie skryptu dotnet-install
Pobierz skrypt dotnet-install dla systemu operacyjnego. Uruchom skrypt z opcjami na podstawie informacji w komunikacie o błędzie. Na stronie dokumentacji skryptu dotnet-install są wyświetlane wszystkie dostępne opcje.
Uruchom program PowerShell i uruchom polecenie:
dotnet-install.ps1 -Architecture <architecture> -InstallDir <directory> -Runtime <runtime> -Version <version>
Na przykład komunikat o błędzie w poprzedniej sekcji będzie odpowiadać:
dotnet-install.ps1 -Architecture x64 -InstallDir "C:\Program Files\dotnet\" -Runtime dotnet -Version 5.0.15
Jeśli wystąpi błąd z informacją, że uruchamianie skryptów jest wyłączone, może być konieczne ustawienie zasad wykonywania, aby umożliwić uruchamianie skryptu:
Set-ExecutionPolicy Bypass -Scope Process
Aby uzyskać więcej informacji na temat instalacji przy użyciu skryptu, zobacz Instalowanie przy użyciu automatyzacji programu PowerShell.
./dotnet-install.sh --architecture <architecture> --install-dir <directory> --runtime <runtime> --version <version>
Na przykład komunikat o błędzie w poprzedniej sekcji będzie odpowiadać:
./dotnet-install.sh --architecture x64 --install-dir /usr/share/dotnet/ --runtime dotnet --version 5.0.15
Aby uzyskać więcej informacji na temat instalacji przy użyciu skryptu, zobacz Skrypt instalacji.
./dotnet-install.sh --architecture <architecture> --install-dir <directory> --runtime <runtime> --version <version>
Na przykład komunikat o błędzie w poprzedniej sekcji będzie odpowiadać:
./dotnet-install.sh --architecture x64 --install-dir /usr/local/share/dotnet/ --runtime dotnet --version 5.0.15
Aby uzyskać więcej informacji na temat instalacji przy użyciu skryptu, zobacz Instalowanie za pomocą automatyzacji powłoki bash.
Pobieranie plików binarnych
Możesz pobrać archiwum binarne platformy .NET ze strony pobierania. W kolumnie Pliki binarne pobranego środowiska uruchomieniowego pobierz wersję binarną zgodną z wymaganą architekturą. Wyodrębnij pobrane archiwum do lokalizacji .NET określonej w komunikacie o błędzie.
Aby uzyskać więcej informacji na temat instalacji ręcznej, zobacz Instalowanie platformy .NET w systemie Windows
Aby uzyskać więcej informacji na temat instalacji ręcznej, zobacz Instalowanie platformy .NET w systemie Linux
Aby uzyskać więcej informacji na temat instalacji ręcznej, zobacz Instalowanie platformy .NET w systemie macOS
Konfigurowanie zachowania wycofywania
Jeśli masz już zainstalowaną wyższą wersję wymaganej platformy, możesz ją uruchomić w tej wyższej wersji, konfigurując zachowanie wycofywania.
Podczas uruchamiania aplikacji można określić --roll-forward opcję wiersza polecenia lub ustawić zmiennąDOTNET_ROLL_FORWARDśrodowiskową.
Domyślnie aplikacja wymaga platformy zgodnej z tą samą wersją główną, która jest przeznaczona dla aplikacji, ale może używać nowszej wersji pomocniczej lub poprawkowej. Jednak deweloperzy aplikacji mogą określić inne zachowanie. Aby uzyskać więcej informacji, zobacz Wdrażanie aplikacji zależnych od platformy.
Uwaga
Ponieważ użycie tej opcji umożliwia uruchamianie aplikacji w innej wersji struktury niż ta, dla której została zaprojektowana, może to spowodować niezamierzone zachowanie ze względu na zmiany między wersjami struktury.
Zmiany powodujące niezgodność
Wyszukiwanie wielowarstwowe jest wyłączone dla platformy .NET 7 lub nowszej
W systemie Windows przed platformą .NET 7 aplikacja może wyszukiwać struktury w wielu lokalizacjach instalacji.
Podkatalogi względem:
dotnetplik wykonywalny podczas uruchamiania aplikacji za pomocą poleceniadotnet.DOTNET_ROOTzmienna środowiskowa (jeśli jest ustawiona) podczas uruchamiania aplikacji za pośrednictwem jej pliku wykonywalnego (apphost).
Globalnie zarejestrowana lokalizacja instalacji (jeśli jest ustawiona) w programie
HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation.Domyślna
%ProgramFiles%\dotnetlokalizacja instalacji (lub%ProgramFiles(x86)%\dotnetdla procesów 32-bitowych w 64-bitowym systemie Windows).
To zachowanie wyszukiwania wielostopniowego zostało domyślnie włączone, ale można je wyłączyć, ustawiając zmienną środowiskową DOTNET_MULTILEVEL_LOOKUP=0.
W przypadku aplikacji przeznaczonych dla platformy .NET 7 i nowszych wyszukiwanie wielowarstwowe jest całkowicie wyłączone i tylko jedna lokalizacja — pierwsza lokalizacja, w której znaleziono instalację platformy .NET — jest przeszukiwana. Gdy aplikacja jest uruchamiana przez dotnetprogram , struktury są wyszukiwane tylko w podkatalogach względem dotnet. Gdy aplikacja jest uruchamiana za pośrednictwem pliku wykonywalnego (apphost), struktury są wyszukiwane tylko w pierwszej z wcześniej wymienionych lokalizacji, w których znaleziono platformę .NET.
Aby uzyskać więcej informacji, zobacz Wyszukiwanie wieloeziomowe jest wyłączone.
