Como gerenciar ferramentas .NET

Este artigo se aplica a: ✔️ SDK do .NET Core 2.1 e versões posteriores.

Uma ferramenta .NET é um pacote NuGet que contém um aplicativo de console. Você pode instalar uma ferramenta em seu computador das seguintes maneiras:

• Como uma ferramenta global.

  Os binários de ferramenta são instalados em um diretório padrão que é adicionado à variável de ambiente PATH. Você pode invocar a ferramenta de qualquer diretório no computador sem especificar a localização dela. A mesma versão de uma ferramenta pode ser usada para todos os diretórios do computador.

• Como uma ferramenta global em um local personalizado (também conhecido como uma ferramenta de caminho de ferramenta).

  Os binários de ferramenta são instalados em um local que você especifica. Você pode invocar a ferramenta do diretório de instalação, fornecendo o diretório com o nome do comando ou adicionando o diretório à variável de ambiente PATH. A mesma versão de uma ferramenta pode ser usada para todos os diretórios do computador.

• Como uma ferramenta local (aplica-se ao SDK do .NET Core 3.0 e versões posteriores).

  Os binários de ferramenta são instalados em um diretório padrão. Você pode invocar a ferramenta do diretório de instalação ou de qualquer um de seus subdiretórios. Diretórios diferentes podem usar versões diferentes da mesma ferramenta.

  A CLI do .NET usa arquivos de manifesto para acompanhar as ferramentas instaladas como locais para um diretório. Quando o arquivo de manifesto está salvo no diretório raiz de um repositório de código-fonte, o colaborador pode clonar o repositório e invocar um só comando da CLI do .NET para instalar todas as ferramentas listadas nos arquivos de manifesto.

Localizar uma ferramenta

Aqui estão algumas maneiras de encontrar ferramentas:

• Use o comando dotnet tool search para encontrar uma ferramenta publicada no NuGet.org.
• Use o filtro de tipo de pacote "ferramenta .NET" para pesquisar o site do NuGet. Para obter mais informações, consulte Localizando e escolhendo pacotes.
• Confira o código-fonte das ferramentas criadas pela equipe do ASP.NET Core no Diretório Ferramentas do repositório GitHub do dotnet/aspnetcore.
• Saiba mais sobre ferramentas de diagnóstico em Ferramentas de diagnóstico do .NET.

Verificar o autor e as estatísticas

As ferramentas NET podem ser poderosas porque são executadas com total confiança e as ferramentas globais são adicionadas à variável de ambiente PATH. Não baixe ferramentas de pessoas em quem você não confia.

Se a ferramenta estiver hospedada no NuGet, você pode verificar o autor e as estatísticas pesquisando a ferramenta.

Instalar uma ferramenta global

Para instalar uma ferramenta como global, use a opção -g ou --global do comando dotnet tool install, conforme mostrado no seguinte exemplo:

dotnet tool install -g dotnetsay

A saída mostra o comando usado para invocar a ferramenta e a versão instalada, semelhante ao seguinte exemplo:

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

O local padrão para binários de uma ferramenta depende do sistema operacional:

Esse local é adicionado ao caminho do usuário quando o SDK é executado pela primeira vez. Portanto, as ferramentas globais podem ser invocadas de qualquer diretório sem especificar o local da ferramenta.

O acesso à ferramenta é específico do usuário, não do computador global. Uma ferramenta global só está disponível para o usuário que a instalou.

Instalar uma ferramenta global em um local personalizado

Para instalar uma ferramenta como global em um local personalizado, use a opção --tool-path do comando dotnet tool install, conforme mostrado nos exemplos a seguir:

No Windows:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

No Linux ou no macOS:

dotnet tool install dotnetsay --tool-path ~/bin

O SDK do .NET não adiciona esse local automaticamente à variável de ambiente PATH. Para invoke a tool-path tool, você deve garantir que o comando esteja disponível usando um dos seguintes métodos:

• Adicione o diretório de instalação à variável de ambiente PATH.
• Especifique o caminho completo da ferramenta ao invocá-la.
• Invoque a ferramenta de dentro do diretório de instalação.

Instalar uma ferramenta local

Aplica-se ao SDK do .NET Core 3.0 e versões posteriores.

Se você quiser instalar uma ferramenta somente para acesso local (para o diretório e subdiretórios atuais), adicione a ferramenta a um arquivo de manifesto da ferramenta. Para criar um arquivo de manifesto da ferramenta, execute o comando dotnet new tool-manifest:

dotnet new tool-manifest

Esse comando cria um arquivo de manifesto chamado dotnet-tools.json no diretório .config. Para adicionar uma ferramenta local ao arquivo de manifesto, use o comando dotnet tool install e omita as opções --global e --tool-path, conforme mostrado no seguinte exemplo:

dotnet tool install dotnetsay

A saída do comando mostra em qual arquivo de manifesto a ferramenta recém-instalada está, conforme ilustrado no seguinte exemplo:

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

O seguinte exemplo mostra um arquivo de manifesto com duas ferramentas locais instaladas:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Normalmente, você adiciona uma ferramenta local ao diretório raiz do repositório. Depois que você fizer check-in do arquivo de manifesto no repositório, os desenvolvedores que fizerem check-out de código do repositório obterão o arquivo de manifesto mais recente. Para instalar todas as ferramentas listadas no arquivo de manifesto, eles executam o comando dotnet tool restore:

dotnet tool restore

A saída indica as ferramentas restauradas:

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Instalar uma versão específica da ferramenta

Para instalar uma versão de pré-lançamento ou uma versão específica de uma ferramenta, especifique o número da versão usando a opção --version, conforme mostrado no seguinte exemplo:

dotnet tool install dotnetsay --version 2.1.3

Para instalar uma versão de pré-lançamento da ferramenta sem especificar o número exato da versão, use a opção --version e forneça um caractere curinga, conforme mostrado no seguinte exemplo:

dotnet tool install --global dotnetsay --version "*-rc*"

Usar uma ferramenta

O comando que você usa para invocar uma ferramenta pode ser diferente do nome do pacote instalado. Para exibir todas as ferramentas instaladas no computador no momento para o usuário atual, use o comando lista de dotnet tool list:

dotnet tool list

A saída mostra a versão e o comando de cada ferramenta, conforme ilustra o seguinte exemplo:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Conforme mostrado no exemplo anterior, a lista mostra as ferramentas locais. Para ver as ferramentas globais, use a opção --global. Para ver as ferramentas de caminho de ferramenta, use a opção --tool-path.

Para listar uma ferramenta específica, use o comando lista de ferramentas dotnet <PACKAGE_ID> :

dotnet tool list dotnetsay

A saída só listará essa ferramenta se ela estiver instalada, semelhante ao exemplo a seguir:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Invocar uma ferramenta global

Para ferramentas globais, use o comando de ferramenta por si só. Por exemplo, se o comando for dotnetsay ou dotnet-doc, é isso que você usa para invocar a ferramenta global:

dotnetsay
dotnet-doc

Se o comando começar com o prefixo dotnet-, uma forma alternativa de invocar a ferramenta é usar o comando dotnet e omitir o prefixo de comando da ferramenta. Por exemplo, se o comando for dotnet-doc, o seguinte comando invocará a ferramenta:

dotnet doc

No entanto, no seguinte cenário, você não pode usar o comando dotnet para invocar uma ferramenta global:

• Uma ferramenta global e uma ferramenta local têm o mesmo comando prefixado por dotnet-.
• Você deseja invocar a ferramenta global de um diretório que está no escopo da ferramenta local.

Nesse cenário, dotnet doc e dotnet dotnet-doc invocam a ferramenta local. Para invocar a ferramenta global, use o comando por si só:

dotnet-doc

Invocar uma ferramenta de caminho de ferramenta

Para invocar uma ferramenta global instalada usando a opção tool-path, verifique se o comando está disponível, conforme explicado anteriormente neste artigo.

Invocar uma ferramenta local

Para invocar uma ferramenta local, você deve usar o comando dotnet de dentro do diretório de instalação. Você pode usar o formulário longo (dotnet tool run <COMMAND_NAME>) ou o formulário curto (dotnet <COMMAND_NAME>), conforme mostrado nos seguintes exemplos:

dotnet tool run dotnetsay
dotnet dotnetsay

Se o comando for prefixado por dotnet-, você poderá incluir ou omitir o prefixo ao invocar a ferramenta. Por exemplo, se o comando for dotnet-doc, qualquer um dos seguintes exemplos invocará a ferramenta local:

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Atualizar uma ferramenta

A atualização de uma ferramenta envolve a desinstalação e a reinstalação com a versão estável mais recente. Para atualizar uma ferramenta, use o comando dotnet tool update com a mesma opção usada para instalar a ferramenta:

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

Para uma ferramenta local, o SDK procura no diretório atual e nos diretórios pai para localizar o primeiro arquivo de manifesto que contém o ID do pacote. Se não houver essa ID de pacote em nenhum arquivo de manifesto, o SDK adicionará uma nova entrada ao arquivo de manifesto mais próximo.

Desinstalar uma ferramenta

Remova uma ferramenta usando o comando dotnet tool uninstall com a mesma opção usada para instalar a ferramenta:

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

Para uma ferramenta local, o SDK procura no diretório atual e nos diretórios pai para localizar o primeiro arquivo de manifesto que contém o ID do pacote.

Obter ajuda e solucionar problemas

Se não for possível instalar ou executar uma ferramenta, confira Solucionar problemas de uso da ferramenta .NET. Você pode obter uma lista de comandos dotnet tool e parâmetros disponíveis usando o parâmetro --help:

dotnet tool --help

Para obter instruções de uso da ferramenta, insira um dos seguintes comandos ou confira o site da ferramenta:

<command> --help
dotnet <command> --help

Confira também

• Tutorial: criar uma ferramenta .NET usando a CLI do .NET
• Tutorial: instalar e usar uma ferramenta global do .NET usando a CLI do .NET
• Tutorial: instalar e usar uma ferramenta local do .NET usando a CLI do .NET