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 raiz 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 em sua máquina contém o caminho onde você instalou a PATH 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 DOTNET_ADD_GLOBAL_TOOLS_TO_PATH variável de ambiente como false.
  • Se você instalou o SDK do .NET Core 2.2 ou versões anteriores e definiu a DOTNET_SKIP_FIRST_TIME_EXPERIENCE variável de ambiente como true.

Nesses cenários ou se você especificou a opção durante a instalação de uma ferramenta dotnet, a variável de ambiente em sua máquina não contém automaticamente o caminho onde você instalou a --tool-pathPATH ferramenta global. Nesse caso, acrescente o local da ferramenta (por exemplo, $HOME/.dotnet/tools) à PATH variável de ambiente usando qualquer método que seu shell forneça para atualizar variáveis de ambiente. Para obter mais informações, consulte Ferramentas .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 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 a ferramenta que você está tentando executar. Se o arquivo não contiver uma entrada para , verifique também mais acima a hierarquia de arquivos para "isRoot": truearquivos 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 uso de uma ferramenta instalada no caminho da ferramenta é:

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

Tempo de execução não encontrado

As ferramentas .NET são aplicativos dependentes da estrutura, o que significa que dependem de um tempo de execução do .NET instalado em sua máquina. Se o tempo de execução esperado não for encontrado, eles seguirão regras normais de roll-forward de 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 roll-forward não ocorrerá por padrão em dois cenários comuns:

  • Apenas versões inferiores do tempo de execução estão disponíveis. O roll-forward seleciona apenas versões posteriores do tempo de execução.
  • Apenas versões principais superiores do tempo de execução estão disponíveis. O roll-forward não ultrapassa os limites 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 você acha que a ferramenta deve suportar a versão de tempo de execução que você tem instalado atualmente, você pode entrar em contato com o autor da ferramenta e ver se eles podem atualizar o número da versão ou multi-target. Depois que eles recompilarem e republicarem seu pacote de ferramentas no NuGet com um número de versão atualizado, você poderá 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 tempo de execução 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 DOTNET_ROOT de ambiente para o diretório que contém o dotnet executável.

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.

Aplicaçã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.

Lançamentos de pré-visualizações

  • Você está tentando instalar uma versão de visualização e não usou a opção para especificar a --version 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 , solicitar um arquivo específico nuget.config ou especificar feeds adicionais com nuget.configo --add-source switch. Por padrão, o NuGet lança um erro para qualquer feed que não possa se conectar. O sinalizador --ignore-failed-sources pode ignorar essas fontes inacessí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 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 para ignorar o erro do feed privado e use o --ignore-failed-sources 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 faz com que o comando trate esse erro como um aviso e permite que outros feeds processem a --ignore-failed-sources solicitação.

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

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

    É 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 e para evitar o feed errado e --ignore-failed-sources confie no feed público da --add-source Microsoft.

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

  • Use um parâmetro personalizado de configuração do --configfile <FILE> NuGet.

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

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

Consulte também