Resolver problemas de utilização da ferramenta .NET

Poderá deparar-se 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, é provável que se detete um dos seguintes problemas:

Ficheiro executável não encontrado

Se o ficheiro executável não for encontrado, 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 a forma como invoca a ferramenta. A tabela seguinte 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 predefinido ou numa localização específica. Os diretórios predefinidos são:

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

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

A CLI de .NET tenta adicionar a localização predefinida à variável de ambiente PATH na primeira utilização. No entanto, existem alguns cenários em que a localização pode não ser adicionada automaticamente ao PATH:

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

Nestes cenários ou se especificou a opção --tool-path , a PATH variável de ambiente no seu computador não contém automaticamente o caminho onde instalou a ferramenta global. Nesse caso, acrescente a localização da ferramenta (por exemplo, $HOME/.dotnet/tools) à variável de ambiente através do PATH método fornecido pela shell para atualizar variáveis de ambiente. Para obter mais informações, veja Ferramentas .NET.

Ferramentas locais

Se estiver a tentar executar uma ferramenta local, verifique se existe um ficheiro de manifesto chamado dotnet-tools.json no diretório atual ou em qualquer um dos respetivos diretórios principais. Este ficheiro também pode estar numa pasta com o nome .config em qualquer parte da hierarquia de pastas do projeto, em vez da pasta raiz. Se o dotnet-tools.json existir, abra-o e verifique a ferramenta que está a tentar executar. Se o ficheiro não contiver uma entrada para "isRoot": true, verifique também a hierarquia de ficheiros para obter ficheiros de manifesto de ferramentas adicionais.

Se estiver a tentar executar uma ferramenta .NET instalada com um caminho especificado, terá de incluir esse caminho ao utilizar a ferramenta. Um exemplo de utilização de uma ferramenta de caminho de ferramentas instalada é:

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

Runtime não encontrado

As ferramentas .NET são aplicações dependentes da arquitetura, o que significa que dependem de um runtime .NET instalado no seu computador. Se o runtime esperado não for encontrado, seguirão regras normais de roll-forward de runtime do .NET, tais como:

  • Uma aplicação avança para a versão de patch mais alta da versão principal e secundária especificada.
  • Se não existir um runtime correspondente com um número de versão principal e secundária correspondente, é utilizada a próxima versão secundária superior.
  • O roll forward não ocorre entre versões de pré-visualização do runtime ou entre versões de pré-visualização e versões de lançamento. Assim, as ferramentas .NET criadas com versões de pré-visualização têm de ser reconstruídas e republicadas pelo autor e reinstaladas.

O roll-forward não ocorrerá por predefinição em dois cenários comuns:

  • Só estão disponíveis versões inferiores do runtime. Avançar apenas seleciona versões posteriores do runtime.
  • Só estão disponíveis versões principais mais elevadas do runtime. O roll-forward não ultrapassa os limites de versões principais.

Se uma aplicação não conseguir encontrar um runtime adequado, não será executado e comunica um erro.

Pode descobrir quais os runtimes do .NET instalados no seu computador com um dos seguintes comandos:

dotnet --list-runtimes
dotnet --info

Se acha que a ferramenta deve suportar a versão de runtime que instalou atualmente, pode contactar o autor da ferramenta e ver se consegue atualizar o número da versão ou o multi-destino. Depois de recompilarem e publicarem novamente o pacote de ferramentas no NuGet com um número de versão atualizado, pode atualizar a cópia. Embora isso não aconteça, a solução mais rápida para si é instalar uma versão do runtime que funcionaria com a ferramenta que está a tentar executar. Para transferir uma versão específica do runtime do .NET, visite a página de transferência do .NET.

Se instalar o SDK .NET numa localização não predefinida, terá de 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

Existem 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, 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 estas falhas, as mensagens NuGet são apresentadas diretamente ao utilizador, juntamente com a mensagem anterior. A mensagem NuGet pode ajudá-lo a identificar o problema.

Imposição de nomenclatura de pacotes

A Microsoft alterou a documentação de orientação sobre o ID do Pacote para ferramentas, o que resulta na não deteção de várias ferramentas com o nome previsto. A nova documentação de orientação é que todas as ferramentas da Microsoft sejam prefixadas com "Microsoft". Este prefixo é reservado e só pode ser utilizado para pacotes assinados com um certificado autorizado da Microsoft.

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

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

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

Versões de pré-visualização

  • Está a tentar instalar uma versão de pré-visualização e não utilizou a opção --version para especificar a versão.

As ferramentas .NET que estão em pré-visualização têm de ser especificadas com uma parte do nome para indicar que estão em pré-visualização. Não precisa de incluir toda a pré-visualização. Partindo do princípio de que os números da versão estão no formato esperado, pode utilizar algo semelhante ao seguinte exemplo:

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

O pacote não é uma ferramenta .NET

  • Foi encontrado um pacote NuGet com este nome, mas não era uma ferramenta .NET.

Se tentar instalar um pacote NuGet que seja um pacote NuGet normal 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.

Não é possível aceder ao feed NuGet

  • O feed NuGet necessário não pode ser acedido, talvez devido a um problema de ligação à Internet.

A instalação de ferramentas requer acesso ao feed NuGet que contém o pacote de ferramentas. Falha se o feed não estiver disponível. Pode alterar feeds com nuget.config, pedir um ficheiro específico nuget.config ou especificar feeds adicionais com o --add-source comutador. Por predefinição, o NuGet gera um erro para qualquer feed que não consiga estabelecer ligação. O sinalizador --ignore-failed-sources pode ignorar estas origens não acessíveis.

ID do Pacote incorreto

  • O nome da ferramenta foi escrito incorretamente.

Uma razão comum para a falha é que o nome da ferramenta não está correto. Isto pode acontecer devido a mistyping ou porque a ferramenta foi movida ou preterida. Para ferramentas no NuGet.org, uma forma de garantir que tem o nome correto é procurar a ferramenta em NuGet.org e copiar o comando de instalação.

401 (Não Autorizado)

Muito provavelmente especificou um feed NuGet alternativo e esse feed requer autenticação. Existem algumas formas diferentes de resolver este problema:

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

    Se estiver a instalar uma ferramenta a partir do feed NuGet da Microsoft, o seu feed personalizado irá devolver este erro antes de o feed NuGet da Microsoft devolver um resultado. O erro termina o pedido, cancelando quaisquer outros pedidos de feed pendentes, que podem ser o feed NuGet da Microsoft. Adicionar a opção --ignore-failed-sources faz com que o comando trate este erro como um aviso e permite que outros feeds processem o pedido.

    dotnet tool install -g --ignore-failed-sources <toolName>
    
  • Force o feed NuGet da Microsoft com o --add-source parâmetro .

    É possível que o ficheiro de configuração nuGet global ou local não tenha o feed NuGet público da Microsoft. Utilize uma combinação dos --add-source parâmetros e --ignore-failed-sources para evitar o feed erróneo e depender do feed público da Microsoft.

    dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>
    
  • Utilize uma configuração personalizada do NuGet, --configfile <FILE> parâmetro.

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

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

    Eis um ficheiro 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, veja referência denuget.config

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

    Se souber que o pacote existe no feed configurado, forneça as credenciais de início de sessão no ficheiro de configuração do NuGet. Para obter mais informações sobre as credenciais num ficheiro de configuração nuget, veja a secção packageSourceCredentials da referência denuget.config.

Ver também