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.
Importante
As ferramentas .NET são executadas com confiança total. Não instale uma ferramenta .NET, a menos que você confie no autor.
As ferramentas do .NET podem não funcionar corretamente se o .NET foi instalado via Snap.
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.
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:
CLI do .NET
dotnettool install -g dotnetsay
A saída mostra o comando usado para invocar a ferramenta e a versão instalada, semelhante ao seguinte exemplo:
Saída
You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Observação
Por padrão, a arquitetura dos binários do .NET a serem instalados representa a arquitetura do SO sendo executado no momento. Para especificar uma arquitetura de SO diferente, consulte instalação da ferramenta dotnet, opção --arch.
O local padrão para binários de uma ferramenta depende do sistema operacional:
Sistema operacional
Caminho
Linux/macOS
$HOME/.dotnet/tools
Windows
%USERPROFILE%\.dotnet\tools
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:
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:
CLI do .NET
dotnetnew 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:
CLI do .NET
dotnettool install dotnetsay
A saída do comando mostra em qual arquivo de manifesto a ferramenta recém-instalada está, conforme ilustrado no seguinte exemplo:
Console
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:
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:
CLI do .NET
dotnettoolrestore
A saída indica as ferramentas restauradas:
Console
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:
CLI do .NET
dotnettool install dotnetsay --version2.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:
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:
CLI do .NET
dotnettoollist
A saída mostra a versão e o comando de cada ferramenta, conforme ilustra o seguinte exemplo:
Console
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.
A saída só listará essa ferramenta se ela estiver instalada, semelhante ao exemplo a seguir:
Console
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:
Console
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:
CLI do .NET
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ó:
CLI do .NET
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:
CLI do .NET
dotnettoolrun 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:
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:
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:
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:
CLI do .NET
dotnettool --help
Para obter instruções de uso da ferramenta, insira um dos seguintes comandos ou confira o site da ferramenta:
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
Comentários do .NET
O .NET é um projeto código aberto. Selecione um link para fornecer comentários:
Este módulo se concentrará nas ferramentas de desenvolvimento disponíveis que podem ajudar você a realizar atividades de desenvolvimento com o Power Platform.