Solucionar problemas de uso da ferramenta .NET

Você pode encontrar problemas ao tentar instalar ou executar uma ferramenta .NET, que pode ser uma ferramenta global ou uma ferramenta local. Este artigo descreve as causas raiz comuns e algumas soluções possíveis.

Falha na execução da ferramenta .NET instalada

Quando uma ferramenta .NET falha ao ser executada, provavelmente você encontrou um dos seguintes problemas:

• O arquivo executável da ferramenta não foi encontrado.
• A versão correta do runtime do .NET não foi encontrada.

Arquivo executável não encontrado

Se o arquivo executável não for encontrado, você verá uma mensagem semelhante à seguinte:

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.

O nome do executável determina como você invoca a ferramenta. A tabela a seguir descreve o formato:

Formato de nome do executável	Formato de invocação
dotnet-<toolName>.exe	dotnet <toolName>
<toolName>.exe	<toolName>

Ferramentas globais

As ferramentas globais podem ser instaladas no diretório padrão ou em um local específico. Os diretórios padrão são:

SO	Caminho
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

Se você estiver tentando executar uma ferramenta global, verifique se a variável de ambiente PATH em seu computador contém o caminho onde você instalou a ferramenta global e se o executável está nesse caminho.

A CLI do .NET tenta adicionar o local padrão à variável de ambiente PATH em seu primeiro uso. No entanto, há alguns cenários em que o local pode não ser adicionado ao PATH automaticamente:

• Se você estiver usando o Linux e tiver instalado o SDK do .NET usando arquivos .tar.gz e não apt-get ou rpm.
• Se você estiver usando o macOS 10.15 "Catalina" ou versões posteriores.
• Se você estiver usando o macOS 10.14 "Mojave" ou versões anteriores, e tiver instalado o SDK do .NET usando arquivos .tar.gz e não .pkg.
• Se você instalou o SDK do .NET Core 3.0 e definiu a variável de ambiente DOTNET_ADD_GLOBAL_TOOLS_TO_PATH como false.
• Se você instalou o SDK do .NET Core 2.2 ou versões anteriores e definiu a variável de ambiente DOTNET_SKIP_FIRST_TIME_EXPERIENCE como true.

Nesses cenários ou se você especificou a opção --tool-pathao instalar uma ferramenta dotnet, a variável de ambiente PATH em seu computador não contém automaticamente o caminho em que você instalou a ferramenta global. Nesse caso, acrescente o local da ferramenta (por exemplo, $HOME/.dotnet/tools) à variável de ambiente PATH usando qualquer método que seu shell forneça para atualizar variáveis de ambiente. Para obter mais informações, consulte as ferramentas do .NET .

Ferramentas locais

Se você estiver tentando executar uma ferramenta local, verifique se há um arquivo de manifesto chamado dotnet-tools.json no diretório atual ou em qualquer um de seus diretórios pai. Esse arquivo também pode residir em uma pasta chamada .config em qualquer lugar na hierarquia de pastas do projeto, em vez da pasta raiz. Se o arquivo dotnet-tools.json existir, abra-o e verifique a ferramenta que você está tentando executar. Se o arquivo não contiver uma entrada para "isRoot": true, verifique o restante da hierarquia de arquivos em busca de arquivos de manifesto de ferramenta adicionais.

Se você estiver tentando executar uma ferramenta .NET que foi instalada com um caminho especificado, será necessário incluir esse caminho ao usar a ferramenta. Um exemplo de como usar uma ferramenta instalada de caminho de ferramenta é o seguinte:

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

Runtime não encontrado

As ferramentas do .NET são aplicativos dependentes do framework , o que significa que elas dependem de um ambiente de execução .NET instalado em seu computador. Se o runtime esperado não for encontrado, seguem as regras normais de avanço de runtime do .NET, como:

• Um aplicativo efetua roll forward até a versão de patch mais recente da versão principal e secundária especificadas.
• Se não houver nenhum runtime correspondente com um número de versão principal e secundária correspondente, a próxima versão secundária mais alta será usada.
• O roll forward não ocorre entre versões prévias do runtime ou entre versões prévias e versões de lançamento. Portanto, as ferramentas do .NET criadas usando versões de visualização devem ser recriadas e republicadas pelo autor e reinstaladas.

O roll forward não ocorrerá por padrão em dois cenários comuns:

• Somente versões inferiores do runtime estão disponíveis. O roll-forward seleciona apenas versões posteriores do runtime.
• Somente as versões principais mais recentes do runtime estão disponíveis. O roll-forward não ultrapassa os limites da versão principal.

Se um aplicativo não conseguir encontrar um runtime apropriado, ele falhará ao executar e relatará um erro.

Você pode descobrir quais runtimes do .NET estão instalados em seu computador usando um dos seguintes comandos:

dotnet --list-runtimes
dotnet --info

Se você achar que a ferramenta deve dar suporte à versão de runtime que você tem instalada atualmente, entre em contato com o autor da ferramenta e veja se eles podem atualizar o número de versão ou adicionar suporte para múltiplos alvos. Depois de recompilar e republicar seu pacote de ferramentas no NuGet com um número de versão atualizado, você poderá atualizar sua cópia. Embora isso não aconteça, a solução mais rápida para você é instalar uma versão do runtime que funcionaria com a ferramenta que você está tentando executar. Para baixar uma versão específica do runtime do .NET, visite a página de download do .NET.

Se você instalar o SDK do .NET em um local não padrão, precisará definir a variável de ambiente DOTNET_ROOT para o diretório que contém o dotnet executável.

Falha na instalação da ferramenta .NET

Há vários motivos pelos quais a instalação de uma ferramenta global ou local do .NET pode falhar. Quando a instalação da ferramenta falhar, você verá uma mensagem semelhante à seguinte:

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

Para ajudar a diagnosticar essas falhas, as mensagens do NuGet são mostradas diretamente ao usuário, juntamente com a mensagem anterior. A mensagem do NuGet pode ajudá-lo a identificar o problema.

• Imposição de nomenclatura de pacote
• Versões preliminares
• Package não é uma ferramenta .NET
• O feed do NuGet não pode ser acessado
• ID do Pacote incorreta
• 401 (não autorizado)

Imposição de nomenclatura de pacote

A Microsoft alterou suas diretrizes sobre a ID do Pacote para ferramentas, resultando em várias ferramentas que não foram encontradas com o nome previsto. A nova orientação é que todas as ferramentas da Microsoft sejam prefixadas com "Microsoft". Esse prefixo é reservado e só pode ser usado para pacotes assinados com um certificado autorizado da Microsoft.

Durante a transição, algumas ferramentas da Microsoft terão a forma antiga da ID do pacote, enquanto outras terão o novo formulário:

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

À medida que as IDs do pacote forem atualizadas, você precisará alterar para a nova ID do pacote para obter as atualizações mais recentes. Pacotes com o nome da ferramenta simplificada serão preteridos.

Versões prévias

• Você está tentando instalar uma versão prévia e não usou a opção --version para especificar a versão.

As ferramentas .NET que estão em versão prévia devem ser especificadas com uma parte do nome para indicar que estão em versão prévia. Você não precisa incluir a versão prévia inteira. Supondo que os números de versão estejam no formato esperado, você pode usar algo semelhante ao exemplo a seguir:

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

O pacote não é uma ferramenta .NET

• Um pacote NuGet com esse nome foi encontrado, mas não era uma ferramenta .NET.

Se você tentar instalar um pacote NuGet que seja um pacote NuGet regular e não uma ferramenta .NET, verá um erro semelhante ao seguinte:

NU1212: combinação de pacote e projeto inválida para <toolName>. O estilo de projeto DotnetToolReference só pode conter referências do tipo DotnetTool.

O feed do NuGet não pode ser acessado

• O feed NuGet necessário não pode ser acessado, talvez devido a um problema de conexão com a Internet.

A instalação da ferramenta requer acesso ao feed do NuGet que contém o pacote de ferramentas. Ele falhará se o feed não estiver disponível. Você pode alterar feeds com nuget.config, solicitar um arquivo nuget.config específico ou especificar feeds adicionais com a opção --add-source. Por padrão, o NuGet gera um erro para qualquer feed que não possa se conectar. O sinalizador --ignore-failed-sources pode ignorar essas fontes não acessíveis.

ID do pacote incorreta

• Você digitou incorretamente o nome da ferramenta.

Um motivo comum para a falha é que o nome da ferramenta não está correto. Isso pode acontecer por causa de um erro de digitação ou porque a ferramenta foi movida ou obsoleta. Para ferramentas no NuGet.org, uma maneira de garantir que o nome esteja correto é pesquisar a ferramenta no NuGet.org e copiar o comando de instalação.

401 (Não autorizado)

Provavelmente você especificou um feed alternativo do NuGet e esse feed requer autenticação. Há algumas maneiras diferentes de resolver isso:

• Adicione o parâmetro --ignore-failed-sources para ignorar o erro do feed privado e usar o feed público da Microsoft.

  Se você estiver instalando uma ferramenta do feed do Microsoft NuGet, o feed personalizado retornará esse erro antes que o feed NuGet da Microsoft retorne um resultado. O erro encerra a solicitação, cancelando quaisquer outras solicitações de feed pendentes, que podem ser o feed NuGet da Microsoft. Adicionar a opção --ignore-failed-sources faz com que o comando trate esse erro como um aviso e permite que outros feeds processem a solicitação.

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

• Utilize o parâmetro --add-source para forçar o feed do Microsoft NuGet.

  É possível que o arquivo de configuração do NuGet global ou local esteja sem o feed público do Microsoft NuGet. Use uma combinação dos parâmetros --add-source e --ignore-failed-sources para evitar o feed incorreto e contar com o feed público da Microsoft.

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

• Use uma configuração do NuGet personalizada, parâmetro --configfile <FILE>.

  Crie um arquivo de nuget.config local apenas com o feed do Microsoft NuGet público e faça referência a ele com o parâmetro --configfile:

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

  Veja um exemplo de arquivo de configuração:

  <?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>
  

  Para obter mais informações, consulte a referência nuget.config.

• Adicione as credenciais necessárias ao arquivo de configuração.

  Se você souber que o pacote existe no feed configurado, forneça as credenciais de logon no arquivo de configuração do NuGet. Para obter mais informações sobre credenciais em um arquivo de configuração nuget, consulte a seção packageSourceCredentials da referência nuget.config.

Consulte também

• Ferramentas .NET