Partilhar via

Solucionar problemas de uso da ferramenta .NET

  • Artigo

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

Falha na execução da ferramenta .NET instalada

Quando uma ferramenta .NET não é executada, é muito provável que você se depare com um dos seguintes problemas:

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 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 sua máquina 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 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 sua máquina não contém automaticamente o caminho onde 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 .NET em .

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 viver sob uma pasta chamada .config em qualquer lugar na hierarquia de pastas do projeto, em vez da pasta raiz. Se dotnet-tools.json existir, abra-o e verifique se a ferramenta que está a tentar executar está presente. Se o arquivo não contiver uma entrada para "isRoot": true, verifique também mais acima a hierarquia de arquivos para 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 utilização de uma ferramenta instalada num trajeto de ferramenta é:

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

Tempo de execução não encontrado

As ferramentas .NET são aplicações dependentes do framework, o que significa que dependem de um runtime do .NET instalado no teu computador. Se o tempo de execução esperado não for encontrado, eles seguirão as regras normais de roll-forward do tempo de execução do .NET, como:

  • Um aplicativo avança para a versão de patch mais alta da versão principal e secundária especificada.
  • Se não houver tempo de execução correspondente com um número de versão principal e secundária correspondente, a próxima versão secundária superior será usada.
  • A rolagem não ocorre entre as versões de visualização do tempo de execução ou entre as versões de visualização e as versões de lançamento. Portanto, as ferramentas .NET criadas usando versões de visualização devem ser reconstruídas e republicadas pelo autor e reinstaladas.

O avanço não ocorrerá por padrão em duas situações comuns:

  • Apenas versões inferiores do tempo de execução estão disponíveis. A funcionalidade de avanço seleciona apenas versões posteriores do runtime.
  • Apenas versões principais superiores do tempo de execução estão disponíveis. O avanço para a frente não ultrapassa as barreiras das versões principais.

Se um aplicativo não conseguir encontrar um tempo de execução apropriado, ele não será executado e relatará um erro.

Você pode descobrir quais tempos de execução do .NET estão instalados em sua máquina usando um dos seguintes comandos:

dotnet --list-runtimes
dotnet --info

Se achar que a ferramenta deve suportar a versão em tempo de execução que tem atualmente instalada, pode contactar o autor da ferramenta e verificar se ele pode atualizar o número da versão ou direcionar para múltiplos alvos. Depois que eles recompilarem e republicarem o pacote de ferramentas no NuGet com um número de versão atualizado, você pode atualizar sua cópia. Enquanto isso não acontece, a solução mais rápida para você é instalar uma versão do tempo de execução que funcione 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 executável dotnet.

Falha na instalação da ferramenta .NET

Há uma série de razões pelas 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 NuGet pode ajudá-lo a identificar o problema.

Imposição de nomenclatura de pacotes

A Microsoft alterou sua orientação 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 a nova forma:

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

À medida que os IDs do pacote são atualizados, você precisará alterar para o novo ID do pacote para obter as atualizações mais recentes. Os pacotes com o nome simplificado da ferramenta serão preteridos.

Pré-visualização de versões

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

As ferramentas .NET que estão em visualização devem ser especificadas com uma parte do nome para indicar que estão em visualização. Não é necessário incluir toda a visualização. Supondo que os números de versão estejam no formato esperado, você pode usar algo como o 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 de 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. Falha se o feed não estiver disponível. Você pode alterar feeds com nuget.config, solicitar um arquivo de nuget.config específico ou especificar feeds adicionais com a opção --add-source. Por padrão, o NuGet lança um erro para qualquer feed que não possa se conectar. A bandeira --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 falha é que o nome da ferramenta não está correto. Isso pode acontecer devido a erros de digitação ou porque a ferramenta foi movida ou preterida. Para ferramentas no NuGet.org, uma maneira de garantir que você tenha o nome correto é procurar a ferramenta em NuGet.org e copiar o comando de instalação.

401 (Não autorizado)

Muito provavelmente você especificou um feed NuGet alternativo e esse feed requer autenticação. Existem algumas maneiras diferentes de resolver isso:

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

    Se você estiver instalando uma ferramenta do feed NuGet da Microsoft, seu 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>

  • Força o feed do Microsoft NuGet com o parâmetro --add-source.

    É possível que o arquivo de configuração global ou local do NuGet esteja faltando no 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 confiar no 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 público do Microsoft NuGet e faça referência a ele com o parâmetro --configfile:

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

    Aqui está 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 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 login 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.

Ver também