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

Artigo
05/10/2023

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

Este tutorial ensina como instalar e usar uma ferramenta local. Você usa uma ferramenta criada no primeiro tutorial desta série.

Pré-requisitos

Conclua o primeiro tutorial desta série.
Instale o runtime do .NET Core 2.1.

Para este tutorial, você instala e usa uma ferramenta que tem como destino o .NET Core 2.1; portanto, você precisa ter esse runtime instalado em seu computador. Para instalar o runtime 2.1, acesse a página de download do .NET Core 2.1 e localize o link de instalação do runtime na coluna Executar aplicativos – Runtime.

Criar um arquivo de manifesto

Para instalar uma ferramenta somente para acesso local (para o diretório e os subdiretórios atuais), ela precisa ser adicionada a um arquivo de manifesto.

Na pasta microsoft.botsay, navegue um nível para cima até a pasta do repositório:

cd ..

Crie um arquivo de manifesto executando o comando dotnet new:

dotnet new tool-manifest

A saída indica a criação bem-sucedida do arquivo.

The template "Dotnet local tool manifest file" was created successfully.

O arquivo .config/dotnet-tools.json ainda não tem ferramentas:

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

As ferramentas listadas em um arquivo de manifesto estão disponíveis para o diretório e subdiretórios atuais. O diretório atual é aquele que contém o diretório .config com o arquivo de manifesto.

Quando você usa um comando da CLI que se refere a uma ferramenta local, o SDK procura um arquivo de manifesto no diretório atual e nos diretórios pai. Se encontrar um arquivo de manifesto, mas o arquivo não incluir a ferramenta referenciada, ele continuará a pesquisa por diretórios pai. A pesquisa termina quando ele encontrar a ferramenta referenciada ou encontrar um arquivo de manifesto com isRoot definido como true.

Instalar o botsay como uma ferramenta local

Instale a ferramenta do pacote que você criou no primeiro tutorial:

dotnet tool install --add-source ./microsoft.botsay/nupkg microsoft.botsay

Esse comando adiciona a ferramenta ao arquivo de manifesto que você criou na etapa anterior. A saída do comando mostra em qual arquivo de manifesto a ferramenta recém-instalada está:

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

O arquivo .config/dotnet-tools.json agora tem uma ferramenta:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    }
  }
}

Usar a ferramenta

Invoque a ferramenta executando o comando dotnet tool run da pasta do repositório:

dotnet tool run botsay hello from the bot

Restaurar uma ferramenta local instalada por terceiros

Normalmente, você adiciona uma ferramenta local ao diretório raiz do repositório. Depois que você verificar o arquivo de manifesto no repositório, outros desenvolvedores poderão obter o arquivo de manifesto mais recente. Para instalar todas as ferramentas listadas no arquivo de manifesto, eles podem executar o comando único dotnet tool restore.

Abra o arquivo .config/dotnet-tools.json e substitua o conteúdo pelo seguinte JSON:

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

Salve suas alterações.

Fazer essa alteração é o mesmo que obter a versão mais recente do repositório depois que outra pessoa instalou o pacote dotnetsay no diretório do projeto.

Execute o comando dotnet tool restore.

dotnet tool restore

O comando produz uma saída como o exemplo a seguir:

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

Verifique se as ferramentas estão disponíveis:

dotnet tool list

A saída é uma lista de pacotes e comandos, semelhante ao exemplo a seguir:

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

Teste as ferramentas:

dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run botsay hello from botsay

Atualizar uma ferramenta local

A versão instalada da ferramenta dotnetsay local é 2.1.3. Use o comando dotnet tool update para atualizar a ferramenta para a versão mais recente.

dotnet tool update dotnetsay

A saída indica o novo número de versão:

Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '2.1.7'
(manifest file /home/name/repository/.config/dotnet-tools.json).

O comando de atualização localiza o primeiro arquivo de manifesto que contém a ID do pacote e o atualiza. Se não houver essa ID do pacote em nenhum arquivo de manifesto no escopo de pesquisa, o SDK adicionará uma nova entrada ao arquivo de manifesto mais próximo. O escopo de pesquisa percorre diretórios pai até que um arquivo de manifesto com isRoot = true seja encontrado.

Remover ferramentas locais

Remova a ferramenta executando o comando dotnet tool uninstall:

dotnet tool uninstall microsoft.botsay

dotnet tool uninstall dotnetsay

Solucionar problemas

Se você receber uma mensagem de erro ao seguir o tutorial, confira Solucionar problemas de uso da ferramenta .NET.

Confira também

Para obter mais informações, confira ferramentas do .NET

Compartilhar via