.NET 도구 사용 문제 해결

전역 도구 또는 로컬 도구일 수 있는 .NET 도구를 설치하거나 실행하려고 할 때 문제가 발생할 수 있습니다. 이 문서에서는 일반적인 근본 원인 및 몇 가지 가능한 해결에 대해 설명합니다.

설치된 .NET 도구가 실행되지 않습니다.

.NET 도구를 실행하지 못하면 다음 문제 중 하나가 발생할 가능성이 큽니다.

• 도구의 실행 파일을 찾을 수 없습니다.
• .NET 런타임의 올바른 버전을 찾을 수 없습니다.

실행 파일을 찾을 수 없음

실행 파일을 찾을 수 없는 경우 다음과 유사한 메시지가 표시됩니다.

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

실행 파일의 이름은 도구를 호출하는 방법을 결정합니다. 다음 표에서는 형식에 대해 설명합니다.

실행 파일 이름 형식	호출 형식
dotnet-<toolName>.exe	dotnet <toolName>
<toolName>.exe	<toolName>

전역 도구

전역 도구는 기본 디렉터리 또는 특정 위치에 설치할 수 있습니다. 기본 디렉터리:

운영 체제	길
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

전역 도구를 실행하려는 경우 컴퓨터의 PATH 환경 변수에 전역 도구를 설치한 경로와 실행 파일이 해당 경로에 있는지 확인합니다.

.NET CLI는 첫 번째 사용 시 PATH 환경 변수에 기본 위치를 추가하려고 합니다. 그러나 위치가 PATH에 자동으로 추가되지 않을 수 있는 몇 가지 시나리오가 있습니다.

• Linux를 사용 중이고 apt-get 또는 rpm이 아닌 .tar.gz 파일을 사용하여 .NET SDK를 설치한 경우
• macOS 10.15 "Catalina" 이상 버전을 사용하는 경우
• macOS 10.14 "Mojave" 또는 이전 버전을 사용 중이고 .pkg아닌 .tar.gz 파일을 사용하여 .NET SDK를 설치한 경우.
• .NET Core 3.0 SDK를 설치하고 DOTNET_ADD_GLOBAL_TOOLS_TO_PATH 환경 변수를 false로 설정한 경우.
• .NET Core 2.2 SDK 또는 이전 버전을 설치했으며, DOTNET_SKIP_FIRST_TIME_EXPERIENCE 환경 변수를 true로 설정한 경우.

이러한 시나리오에서 또는 dotnet 도구 설치하는 동안--tool-path 옵션을 지정한 경우 컴퓨터의 PATH 환경 변수에 전역 도구를 설치한 경로가 자동으로 포함되지 않습니다. 이 경우 셸에서 환경 변수를 업데이트하기 위해 제공하는 방법을 사용하여 도구 위치(예: $HOME/.dotnet/tools)를 PATH 환경 변수에 추가합니다. 자세한 내용은 .NET 도구 참조하세요.

로컬 도구

로컬 도구를 실행하려는 경우 현재 디렉터리 또는 부모 디렉터리에 dotnet-tools.json 매니페스트 파일이 있는지 확인합니다. 이 파일은 루트 폴더가 아닌 프로젝트 폴더 계층 구조에서 .config 폴더 아래에 저장됩니다. dotnet-tools.json 있는 경우 열고 실행하려는 도구를 확인합니다. 파일에 "isRoot": true대한 항목이 없는 경우 추가 도구 매니페스트 파일에 대한 파일 계층 구조도 추가로 확인합니다.

지정된 경로와 함께 설치된 .NET 도구를 실행하려는 경우 도구를 사용할 때 해당 경로를 포함해야 합니다. 도구 경로 설치 도구를 사용하는 예는 다음과 같습니다.

..\<toolDirectory>\dotnet-<toolName>

런타임을 찾을 수 없음

.NET 도구는 프레임워크 종속 애플리케이션 . 즉, 머신에 설치된 .NET 런타임에 의존합니다. 예상 런타임을 찾을 수 없는 경우 다음과 같은 일반적인 .NET 런타임 롤 포워드 규칙을 따릅니다.

• 애플리케이션은 지정된 주 버전 및 부 버전의 가장 높은 패치 릴리스로 롤아웃합니다.
• 일치하는 주 버전 및 부 버전 번호와 일치하는 런타임이 없는 경우 다음 상위 부 버전이 사용됩니다.
• 롤 포워드는 런타임의 미리 보기 버전 간에 또는 미리 보기 버전과 릴리스 버전 간에 발생하지 않습니다. 따라서 미리 보기 버전을 사용하여 만든 .NET 도구는 작성자가 다시 빌드하고 다시 게시하고 다시 설치해야 합니다.

롤 포워드는 두 가지 일반적인 시나리오에서 기본적으로 발생하지 않습니다.

• 런타임의 하위 버전만 사용할 수 있습니다. 롤 포워드는 런타임의 이후 버전만 선택합니다.
• 더 높은 주 버전의 런타임만 사용할 수 있습니다. 롤 포워드는 주 버전 경계를 넘지 않습니다.

애플리케이션이 적절한 런타임을 찾을 수 없는 경우 실행되지 못하고 오류를 보고합니다.

다음 명령 중 하나를 사용하여 컴퓨터에 설치된 .NET 런타임을 확인할 수 있습니다.

dotnet --list-runtimes
dotnet --info

도구가 현재 설치한 런타임 버전을 지원해야 한다고 생각되면 도구 작성자에게 문의하여 버전 번호 또는 다중 대상을 업데이트할 수 있는지 확인할 수 있습니다. 업데이트된 버전 번호로 도구 패키지를 다시 컴파일하고 NuGet에 다시 게시한 후에는 복사본을 업데이트할 수 있습니다. 이러한 문제가 발생하지는 않지만 가장 빠른 해결 방법은 실행하려는 도구에서 작동하는 런타임 버전을 설치하는 것입니다. 특정 .NET 런타임 버전을 다운로드하려면 .NET 다운로드 페이지방문하세요.

.NET SDK를 기본이 아닌 위치에 설치하는 경우 환경 변수 DOTNET_ROOTdotnet 실행 파일이 포함된 디렉터리로 설정해야 합니다.

.NET 도구 설치 실패

.NET 전역 또는 로컬 도구 설치에 실패할 수 있는 여러 가지 이유가 있습니다. 도구 설치에 실패하면 다음과 유사한 메시지가 표시됩니다.

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

이러한 오류를 진단하기 위해 NuGet 메시지는 이전 메시지와 함께 사용자에게 직접 표시됩니다. NuGet 메시지는 문제를 식별하는 데 도움이 될 수 있습니다.

• 패키지 명명 강화
• 미리 보기 릴리스
• 패키지는 .NET 도구 아닙니다.
• NuGet 피드에 액세스할 수 없습니다
• 패키지 ID 잘못된
• 401(권한 없음)

패키지 명명 적용

Microsoft는 도구용 패키지 ID에 대한 지침을 변경하여 예측된 이름으로 여러 도구를 찾을 수 없습니다. 새로운 지침은 모든 Microsoft 도구에 "Microsoft"라는 접두사를 갖습니다. 이 접두사는 예약되어 있으며 Microsoft 권한 있는 인증서로 서명된 패키지에만 사용할 수 있습니다.

전환 중에 일부 Microsoft 도구는 이전 형식의 패키지 ID를 가지지만 다른 도구는 새 형식을 갖습니다.

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

패키지 ID가 업데이트되면 새 패키지 ID로 변경하여 최신 업데이트를 받아야 합니다. 간소화된 도구 이름을 가진 패키지는 더 이상 사용되지 않습니다.

미리 보기 릴리스

• 미리 보기 릴리스를 설치하려고 하고 --version 옵션을 사용하여 버전을 지정하지 않았습니다.

미리 보기에 있는 .NET 도구는 미리 보기 상태임을 나타내기 위해 이름의 일부로 지정해야 합니다. 전체 미리 보기를 포함할 필요는 없습니다. 버전 번호가 예상 형식이라고 가정하면 다음 예제와 같이 사용할 수 있습니다.

dotnet tool install -g --version 1.1.0-pre <toolName>

패키지가 .NET 도구가 아닙니다.

• 이 이름으로 된 NuGet 패키지를 찾았지만 .NET 도구는 아닙니다.

.NET 도구가 아닌 일반 NuGet 패키지인 NuGet 패키지를 설치하려고 하면 다음과 유사한 오류가 표시됩니다.

NU1212: <toolName>대한 프로젝트 패키지 조합이 잘못되었습니다. DotnetToolReference 프로젝트 스타일은 DotnetTool 형식의 참조만 포함할 수 있습니다.

NuGet 피드에 액세스할 수 없습니다.

• 인터넷 연결 문제로 인해 필요한 NuGet 피드에 액세스할 수 없습니다.

도구를 설치하려면 도구 패키지가 포함된 NuGet 피드에 액세스해야 합니다. 피드를 사용할 수 없는 경우 실패합니다. nuget.config사용하여 피드를 변경하거나, 특정 nuget.config 파일을 요청하거나, --add-source 스위치를 사용하여 추가 피드를 지정할 수 있습니다. 기본적으로 NuGet은 연결할 수 없는 모든 피드에 대한 오류를 발생시킵니다. 플래그 --ignore-failed-sources는 접근할 수 없는 소스를 건너뛸 수 있습니다.

패키지 ID가 잘못되었습니다.

• 도구의 이름을 잘못 입력했습니다.

일반적으로 오류가 발생하는 이유는 도구 이름이 올바르지 않기 때문입니다. 이 문제는 오작동으로 인해 또는 도구가 이동되었거나 더 이상 사용되지 않아 발생할 수 있습니다. NuGet.org 도구의 경우 이름이 올바른지 확인하는 한 가지 방법은 NuGet.org 도구를 검색하고 설치 명령을 복사하는 것입니다.

401(권한 없음)

대체 NuGet 피드를 지정했을 가능성이 높으며 해당 피드에는 인증이 필요합니다. 이 문제를 해결하는 방법에는 몇 가지가 있습니다.

• --ignore-failed-sources 매개 변수를 추가하여 프라이빗 피드의 오류를 무시하고 공용 Microsoft 피드를 사용합니다.

  Microsoft NuGet 피드에서 도구를 설치하는 경우 Microsoft의 NuGet 피드가 결과를 반환하기 전에 사용자 지정 피드가 이 오류를 반환합니다. 이 오류는 요청을 종료하고 Microsoft의 NuGet 피드일 수 있는 보류 중인 다른 피드 요청을 취소합니다. --ignore-failed-sources 옵션을 추가하면 명령에서 이 오류를 경고로 처리하고 다른 피드에서 요청을 처리할 수 있습니다.

  dotnet tool install -g --ignore-failed-sources <toolName>
  

• --add-source 매개 변수를 사용하여 Microsoft NuGet 피드를 강제로 적용합니다.

  전역 또는 로컬 NuGet 구성 파일에 공용 Microsoft NuGet 피드가 누락된 것일 수 있습니다. 잘못된 피드를 방지하고 공용 Microsoft 피드를 사용하려면 --add-source 및 --ignore-failed-sources 매개 변수의 조합을 사용합니다.

  dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>
  

• 사용자 지정 NuGet 구성, --configfile <FILE> 매개 변수를 사용합니다.

  공용 Microsoft NuGet 피드만 사용하여 로컬 nuget.config 파일을 만들고 --configfile 매개 변수를 사용하여 참조합니다.

  dotnet tool install -g --configfile "./nuget.config" <toolName>
  

  다음은 구성 파일의 예입니다.

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <packageSources>
      <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    </packageSources>
  </configuration>
  

  자세한 내용은 nuget.config을 참조하세요.

• 구성 파일에 필요한 자격 증명을 추가합니다.

  패키지가 구성된 피드에 있다는 것을 알고 있는 경우 NuGet 구성 파일에 로그인 자격 증명을 제공합니다. nuget 구성 파일의 자격 증명에 대한 자세한 내용은 nuget.config 참조의 packageSourceCredentials 섹션참조하세요.

참조하십시오

• .NET 도구