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 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 não é 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 seguinte tabela descreve o formato:

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:

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

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

• 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ê tiver especificado a opção --tool-pathao instalar uma ferramenta dotnet, a variável de ambiente PATH em seu computador não conterá 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, confira 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 estar 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, precisará 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 .NET são aplicativos dependentes da estrutura, o que significa que elas dependem de um runtime do .NET instalado em seu computador. Se o runtime esperado não for encontrado, elas seguem as regras normais de roll forward do Runtime do .NET, tais 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 .NET criadas usando versões prévias devem ser recriadas e republicadas pelo autor e reinstaladas.

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

• Quando houver somente versões inferiores do runtime disponíveis. O roll forward seleciona apenas versões posteriores do runtime.
• Quando houver somente versões principais superiores do runtime disponíveis. O roll-forward não ultrapassa os limites da versão principal.

Se um aplicativo não consegue encontrar um runtime apropriado, ele não é executado e relata um erro.

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

dotnet --list-runtimes
dotnet --info

Se você acha que a ferramenta deve dar suporte à versão de runtime que você instalou no momento, entre em contato com o autor da ferramenta e veja se ela pode atualizar o número de versão ou os vários destinos. 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 com o diretório que contém o executável dotnet.

Falha na instalação da ferramenta .NET

Há várias razões pelas quais a instalação de uma ferramenta .NET global ou local 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 NuGet são mostradas diretamente ao usuário, juntamente com a mensagem anterior. A mensagem do NuGet pode ajudar a identificar o problema.

• Imposição de nomenclatura de pacote
• Versões prévias
• O pacote 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 mudou suas diretrizes sobre a ID de Pacote das ferramentas, o que resultou em várias ferramentas não serem encontradas com o nome previsto. As novas diretrizes indicam que todas as ferramentas da Microsoft sejam prefixadas com o termo "Microsoft". Esse prefixo é reservado e só pode ser usado em pacotes assinados com um certificado autorizado pela Microsoft.

Durante a transição, algumas ferramentas da Microsoft terão o formato antigo da ID de pacote, enquanto outras terão o novo formato:

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

À medida que as IDs de pacote forem atualizadas, você precisará alterar para o novo formato da ID de pacote a fim de 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 do .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 seguinte exemplo:

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 comum e não uma ferramenta .NET, será exibido um erro semelhante ao seguinte:

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

O feed do NuGet não pode ser acessado

• O feed do 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 específico nuget.config 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 erro de digitação ou porque a ferramenta foi movida ou preterida. Para ferramentas no NuGet.org, uma forma de garantir que você esteja usando o nome correto é pesquisar a ferramenta no NuGet.org e copiar o comando de instalação.

401 (não autorizado)

Provavelmente você especificou um feed do NuGet alternativo 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 NuGet da Microsoft, o feed personalizado retornará esse erro antes que o feed do 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 do 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>
  

• Imponha o feed do NuGet da Microsoft com o parâmetro --add-source.

  É possível que o arquivo de configuração global ou local do NuGet não tenha o feed do NuGet público da Microsoft. 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 personalizada do NuGet, parâmetro --configfile <FILE>.

  Crie um arquivo nuget.config local apenas com o feed do NuGet público da Microsoft e referencie-o com o parâmetro --configfile:

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

  Aqui está um arquivo de configuração de exemplo:

  <?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, confira Referência do 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 do NuGet, confira a seção packageSourceCredentials da Referência do nuget.config.

Confira também

• Ferramentas .NET