Como gerenciar ferramentas .NET

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

Uma ferramenta .NET é um pacote NuGet especial que contém um aplicativo de console. Pode instalar uma ferramenta na sua máquina das seguintes formas:

• Como uma ferramenta global.

  Os binários da 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 na máquina sem especificar sua localização. Uma versão de uma ferramenta é usada para todos os diretórios na máquina.

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

  Os binários da ferramenta são instalados em um local que você especificar. Você pode invocar a ferramenta a partir 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. Uma versão de uma ferramenta é usada para todos os diretórios na máquina.

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

  Os binários da ferramenta são instalados em um diretório padrão. Você pode invocar a ferramenta a partir 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 controlar as ferramentas instaladas como locais em um diretório. Quando o arquivo de manifesto é salvo no diretório raiz de um repositório de código-fonte, um colaborador pode clonar o repositório e invocar um único comando da CLI do .NET para instalar todas as ferramentas listadas nos arquivos de manifesto.

Encontre uma ferramenta

Aqui estão algumas maneiras de encontrar ferramentas:

• Use o comando de pesquisa da ferramenta dotnet 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.
• Consulte o código-fonte das ferramentas que a equipe do ASP.NET Core criou no diretório Tools do repositório GitHub dotnet/aspnetcore.
• Saiba mais sobre as ferramentas de diagnóstico em Ferramentas de diagnóstico .NET.

Verifique o autor e as estatísticas

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

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

Instalar uma ferramenta global

Para instalar uma ferramenta como uma ferramenta global, use a -g opção ou --global de instalação da ferramenta dotnet, conforme mostrado no exemplo a seguir:

dotnet tool install -g dotnetsay

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

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

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

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

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

Instalar uma ferramenta global em um local personalizado

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

No Windows:

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

No Linux ou macOS:

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

O SDK .NET não adiciona esse local automaticamente à variável de ambiente PATH. Para invocar uma ferramenta de caminho de ferramenta, 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 para a ferramenta quando você invocá-la.
• Invoque a ferramenta a partir do diretório de instalação.

Instalar uma ferramenta local

Aplica-se ao SDK do .NET Core 3.0 e posterior.

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

dotnet new tool-manifest

Este 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 --global opções e --tool-path , conforme mostrado no exemplo a seguir:

dotnet tool install dotnetsay

A saída do comando mostra em qual arquivo de manifesto a ferramenta recém-instalada está presente, semelhante ao exemplo a seguir:

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 exemplo a seguir 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 de fazer check-in do arquivo de manifesto no repositório, os desenvolvedores que fazem check-out do código do repositório obtêm o arquivo de manifesto mais recente. Para instalar todas as ferramentas listadas no arquivo de manifesto, eles executam o dotnet tool restore comando:

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 --version opção, conforme mostrado no exemplo a seguir:

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 e forneça um curinga --version , conforme mostrado no exemplo a seguir:

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

Utilizar uma ferramenta

O comando que você usa para invocar uma ferramenta pode ser diferente do nome do pacote que você instala. Para exibir todas as ferramentas atualmente instaladas na máquina para o usuário atual, use o comando dotnet tool list :

dotnet tool list

A saída mostra a versão e o comando de cada ferramenta, semelhante ao exemplo a seguir:

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

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

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

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

Invoque uma ferramenta global

Para ferramentas globais, use o comando tool sozinho. 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 maneira alternativa de invocar a ferramenta é usar o dotnet comando e omitir o prefixo do comando tool. Por exemplo, se o comando for dotnet-doc, o comando a seguir invoca a ferramenta:

dotnet doc

No entanto, no cenário a seguir, você não pode usar o dotnet comando 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 invoque 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 tool-path opção, 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 dotnet comando de dentro do diretório de instalação. Você pode usar a forma longa (dotnet tool run <COMMAND_NAME>) ou a forma curta (dotnet <COMMAND_NAME>), conforme mostrado nos exemplos a seguir:

dotnet tool run dotnetsay
dotnet dotnetsay

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

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

Atualizar uma ferramenta

Atualizar uma ferramenta envolve desinstalá-la e reinstalá-la com a versão estável mais recente. Para atualizar uma ferramenta, use o comando dotnet tool update com a mesma opção que você usou 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 encontrar o primeiro arquivo de manifesto que contém a ID do pacote. Se não houver esse ID de pacote em nenhum arquivo de manifesto, o SDK adicionará uma nova entrada ao arquivo de manifesto mais próximo.

Desinstalar uma ferramenta

Desinstale uma ferramenta usando o comando dotnet tool uninstall com a mesma opção que você usou 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 encontrar o primeiro arquivo de manifesto que contém a ID do pacote.

Obter ajuda e solucionar problemas

Se uma ferramenta falhar ao instalar ou executar, consulte Solucionar problemas de uso da ferramenta .NET. Você pode obter uma lista de comandos e parâmetros disponíveis dotnet tool usando o --help parâmetro:

dotnet tool --help

Para obter instruções de utilização da ferramenta, introduza um dos seguintes comandos ou consulte o Web site da ferramenta:

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

Consulte 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