다음을 통해 공유

앱 시작 실패 문제 해결

  • 아티클

이 문서에서는 애플리케이션 시작 실패에 대한 몇 가지 일반적인 이유와 가능한 솔루션을 설명합니다. 이는 컴퓨터에 설치된 .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을 다운로드할 수 있는 링크가 포함되어 있습니다. 해당 링크를 따라가면 해당 다운로드 페이지로 이동할 수 있습니다. .NET 다운로드에서 .NET 버전(Host version으로 지정)을 선택할 수도 있습니다.

필수 .NET 버전의 다운로드 페이지에서 오류 메시지에 나열된 아키텍처와 일치하는 .NET 런타임 다운로드를 찾습니다. 그런 다음 설치 프로그램을 다운로드하고 실행하여 설치할 수 있습니다.

.NET은 다양한 Linux 패키지 관리자를 통해 사용할 수 있습니다. 자세한 내용은 Linux에 .NET 설치를 참조하세요. (.NET의 미리 보기 버전은 일반적으로 패키지 관리자를 통해 사용할 수 없습니다.)

dotnet-runtime6과 같은 적절한 버전에 대한 .NET 런타임 패키지를 설치해야 합니다.

또는 필수 .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의 미리 보기 버전은 일반적으로 패키지 관리자를 통해 사용할 수 없습니다.)

dotnet-runtime6 또는 dotnet-aspnet6과 같은 적절한 버전에 대한 .NET 런타임 패키지를 설치해야 합니다.

또는 필수 .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 이상에서는 다중 수준 조회가 사용하지 않도록 설정되었습니다.

.NET 7 이전 Windows에서는 애플리케이션이 여러 설치 위치에서 프레임워크를 검색할 수 있었습니다.

  1. 다음과 관련된 하위 디렉터리:

    • dotnet을 통해 애플리케이션을 실행할 때 dotnet 실행 파일입니다.
    • 실행 파일(apphost)을 통해 애플리케이션을 실행할 때 DOTNET_ROOT 환경 변수(설정한 경우)입니다.

  2. HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation에 전역적으로 등록된 설치 위치(설정한 경우)입니다.

  3. 기본 설치 위치는 %ProgramFiles%\dotnet(또는 64비트 Windows에서 32비트 프로세스의 경우 %ProgramFiles(x86)%\dotnet)입니다.

이 다중 수준 조회 동작은 기본적으로 사용하도록 설정되어 있지만 환경 변수 DOTNET_MULTILEVEL_LOOKUP=0을 설정하여 사용하지 않도록 설정할 수 있습니다.

.NET 7 이상을 대상으로 하는 애플리케이션의 경우 다중 수준 조회가 완전히 사용하지 않도록 설정되고 하나의 위치(.NET 설치가 발견된 첫 번째 위치)만 검색됩니다. 애플리케이션이 dotnet을 통해 실행되면 프레임워크는 dotnet과 관련된 하위 디렉터리에서만 검색됩니다. 애플리케이션이 실행 파일(apphost)을 통해 실행되면 프레임워크는 .NET이 있는 이전에 나열된 위치 중 첫 번째 위치에서만 검색됩니다.

자세한 내용은 다단계 조회가 사용하지 않도록 설정됨을 참조하세요.

참고 항목