Como gerir ferramentas .NET

  • Artigo

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

Uma ferramenta .NET é um pacote NuGet especial que contém uma aplicação de consola. Pode instalar uma ferramenta no seu computador das seguintes formas:

  • Como uma ferramenta global.

    Os binários de ferramentas são instalados num diretório predefinido que é adicionado à variável de ambiente PATH. Pode invocar a ferramenta a partir de qualquer diretório no computador sem especificar a respetiva localização. É utilizada uma versão de uma ferramenta para todos os diretórios no computador.

  • Como uma ferramenta global numa localização personalizada (também conhecida como ferramenta de caminho de ferramenta).

    Os binários de ferramentas são instalados numa localização que especificar. Pode invocar a ferramenta a partir do diretório de instalação ao fornecer ao diretório o nome do comando ou ao adicionar o diretório à variável de ambiente PATH. É utilizada uma versão de uma ferramenta para todos os diretórios no computador.

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

    Os binários de ferramentas são instalados num diretório predefinido. Pode invocar a ferramenta a partir do diretório de instalação ou de qualquer um dos respetivos subdiretórios. Diferentes diretórios podem utilizar versões diferentes da mesma ferramenta.

    A CLI de .NET utiliza ficheiros de manifesto para controlar as ferramentas instaladas como locais num diretório. Quando o ficheiro de manifesto é guardado no diretório de raiz de um repositório de código fonte, um contribuidor pode clonar o repositório e invocar um único comando da CLI de .NET para instalar todas as ferramentas listadas nos ficheiros de manifesto.

Importante

As ferramentas .NET são executadas em total confiança. Não instale uma ferramenta .NET, a menos que confie no autor.

As ferramentas .NET poderão não funcionar corretamente se o .NET tiver sido instalado através do Snap.

Localizar uma ferramenta

Eis algumas formas de encontrar ferramentas:

Verificar o autor e as estatísticas

As ferramentas .NET podem ser poderosas porque são executadas em total confiança 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 alojada no NuGet, pode verificar o autor e as estatísticas ao procurar a ferramenta.

Instalar uma ferramenta global

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

dotnet tool install -g dotnetsay

O resultado mostra o comando utilizado para invocar a ferramenta e a versão instalada, semelhante ao exemplo seguinte:

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

A localização predefinida para os binários de uma ferramenta depende do sistema operativo:

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

Esta localização é adicionada ao caminho do utilizador quando o SDK é executado pela primeira vez. Assim, as ferramentas globais podem ser invocadas a partir de qualquer diretório sem especificar a localização da ferramenta.

O acesso a ferramentas é específico do utilizador e não global de máquinas. Uma ferramenta global só está disponível para o utilizador que instalou a ferramenta.

Instalar uma ferramenta global numa localização personalizada

Para instalar uma ferramenta como uma ferramenta global numa localização personalizada, utilize a opção --tool-path de instalação da ferramenta dotnet, conforme mostrado nos seguintes exemplos:

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 esta localização automaticamente à variável de ambiente PATH. Para invocar uma ferramenta de caminho de ferramenta, tem de garantir que o comando está disponível através de 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 a invocar.
  • Invoque a ferramenta a partir do diretório de instalação.

Instalar uma ferramenta local

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

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

dotnet new tool-manifest

Este comando cria um ficheiro de manifesto com o nome dotnet-tools.json no diretório .config . Para adicionar uma ferramenta local ao ficheiro de manifesto, utilize o comando de instalação da ferramenta dotnet e omita as --global opções e --tool-path , conforme mostrado no exemplo seguinte:

dotnet tool install dotnetsay

A saída do comando mostra em que ficheiro de manifesto a ferramenta recentemente instalada está presente, semelhante ao exemplo seguinte:

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 seguinte mostra um ficheiro 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, adiciona uma ferramenta local ao diretório de raiz do repositório. Depois de dar entrada do ficheiro de manifesto no repositório, os programadores que verificarem o código do repositório recebem o ficheiro de manifesto mais recente. Para instalar todas as ferramentas listadas no ficheiro de manifesto, executam o dotnet tool restore comando:

dotnet tool restore

O resultado 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 de ferramenta específica

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

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, utilize a opção --version e forneça um caráter universal, conforme mostrado no exemplo seguinte:

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

Utilizar uma ferramenta

O comando que utiliza para invocar uma ferramenta pode ser diferente do nome do pacote que instalar. Para apresentar todas as ferramentas atualmente instaladas no computador para o utilizador atual, utilize o comando da lista de ferramentas dotnet :

dotnet tool list

O resultado mostra a versão e o comando de cada ferramenta, semelhante ao 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, utilize a opção --global . Para ver ferramentas de caminho de ferramentas, utilize a opção --tool-path .

Invocar uma ferramenta global

Para ferramentas globais, utilize o comando da ferramenta por si só. Por exemplo, se o comando for dotnetsay ou dotnet-doc, é o que utiliza para invocar a ferramenta global:

dotnetsay
dotnet-doc

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

dotnet doc

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

  • Uma ferramenta global e uma ferramenta local têm o mesmo prefixo de comando prefixo por dotnet-.
  • Quer invocar a ferramenta global a partir de um diretório que está no âmbito da ferramenta local.

Neste cenário, dotnet doc invoque dotnet dotnet-doc a ferramenta local. Para invocar a ferramenta global, utilize o comando por si só:

dotnet-doc

Invocar uma ferramenta de caminho de ferramenta

Para invocar uma ferramenta global instalada através da opção tool-path , certifique-se de que o comando está disponível conforme explicado anteriormente neste artigo.

Invocar uma ferramenta local

Para invocar uma ferramenta local, tem de utilizar o comando a dotnet partir do diretório de instalação. Pode utilizar 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-, pode incluir ou omitir o prefixo quando invocar a ferramenta. Por exemplo, se o comando for dotnet-doc, qualquer um dos seguintes exemplos invoca a ferramenta local:

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

Atualizar uma ferramenta

A atualização de uma ferramenta envolve desinstalar e reinstalar a mesma com a versão estável mais recente. Para atualizar uma ferramenta, utilize o comando de atualização da ferramenta dotnet com a mesma opção que utilizou 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 principais para encontrar o primeiro ficheiro de manifesto que contém o ID do pacote. Se não existir esse ID de pacote em nenhum ficheiro de manifesto, o SDK adiciona uma nova entrada ao ficheiro de manifesto mais próximo.

Desinstalar uma ferramenta

Desinstale uma ferramenta com o comando de desinstalação da ferramenta dotnet com a mesma opção que utilizou 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 principais para encontrar o primeiro ficheiro de manifesto que contém o ID do pacote.

Obter ajuda e resolução de problemas

Se uma ferramenta não conseguir instalar ou executar, veja Resolver problemas de utilização da ferramenta .NET. Pode obter uma lista de comandos e parâmetros disponíveis dotnet tool com o --help parâmetro :

dotnet tool --help

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

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

Ver também