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

Artigo
01/29/2025

Este artigo aplica-se 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 que criou no tutorial da série.

Pré-requisitos

Conclua o primeiro tutorial desta série.
Instale o ambiente de execução do .NET Core 2.1.

Para este tutorial, instale e utilize uma ferramenta direcionada ao .NET Core 2.1, pelo que necessita de ter esse runtime instalado na sua máquina. Para instalar o tempo de execução 2.1, vá para a página de download do .NET Core 2.1 e localize o link de instalação do tempo de execução na coluna Executar aplicativos - Runtime.

Criar um arquivo de manifesto

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

A partir da pasta microsoft.botsay, suba um nível para a pasta repositório:

cd ..

Crie um ficheiro 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 possui 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 ele encontrar um arquivo de manifesto, mas o arquivo não incluir a ferramenta referenciada, ele continuará a pesquisa através de diretórios pai. A pesquisa termina quando encontra a ferramenta referenciada ou encontra um ficheiro de manifesto com isRoot definido como true.

Instalar botsay como uma ferramenta local

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

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

Este 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"
      ]
    }
  }
}

Utilize a ferramenta

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

dotnet tool run botsay hello from the bot

Restaurar uma ferramenta local instalada por outras pessoas

Normalmente, você instala uma ferramenta local no diretório raiz do repositório. Depois de registar o ficheiro de manifesto no repositório, outros desenvolvedores podem obter o ficheiro de manifesto mais recente. Para instalar todas as ferramentas listadas no arquivo de manifesto, eles podem executar um único comando 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 para o diretório do projeto.

Execute o comando dotnet tool restore.

dotnet tool restore

O comando produz 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 local dotnetsay é 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 número da nova 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 update localiza o primeiro arquivo de manifesto que contém a ID do pacote e o atualiza. Se não houver esse ID de pacote em qualquer arquivo de manifesto que esteja no escopo da pesquisa, o SDK adicionará uma nova entrada ao arquivo de manifesto mais próximo. O escopo de pesquisa abrange os diretórios pai até que um arquivo de manifesto com isRoot = true seja encontrado.

Remover ferramentas locais

Remova as ferramentas instaladas executando o comando dotnet tool uninstall:

dotnet tool uninstall microsoft.botsay

dotnet tool uninstall dotnetsay

Solução de problemas

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

Ver também

Para mais informações, consulte as ferramentas .NET .

Partilhar via