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

Esso artigo se aplica a: ✔️ .NET 8 SDK 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

Criar um arquivo de manifesto

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

Na pasta dotnet-env, navegue um nível acima até a pasta repositório:

cd ..

Crie um arquivo de manifesto executando o novo comando dotnet :

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 através dos diretórios superiores. A pesquisa termina quando encontra a ferramenta referenciada ou localiza um arquivo de manifesto com isRoot definido como true.

Instalar dotnet-env como uma ferramenta local (abordagem tradicional)

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

dotnet tool install --add-source ./dotnet-env/nupkg dotnet-env

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 dotnet-env' or 'dotnet dotnet-env'
Tool 'dotnet-env' (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": {
    "dotnet-env": {
      "version": "1.0.0",
      "commands": [
        "dotnet-env"
      ]
    }
  }
}

Usar a ferramenta local instalada

Depois de instalado como uma ferramenta local, você pode invocá-la de várias maneiras:

  • Execute a ferramenta diretamente usando dnx:

    dnx dotnet-env --add-source ./nupkg

    Observação

    Ao usar o dnx com um manifesto de ferramenta local, ele usa automaticamente a versão especificada no manifesto.

  • Usando dotnet dotnet-env:

    dotnet dotnet-env

  • Usando dotnet tool run

    dotnet tool run dotnet-env

Restaurar uma ferramenta local instalada por outras pessoas

Normalmente, você instala uma ferramenta local no diretório raiz do repositório. Depois de confirmar o envio do 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, elas podem executar um único dotnet tool restore comando.

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

    {
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-env": {
      "version": "1.0.0",
      "commands": [
        "dotnet-env"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

  2. 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.

  3. Execute o comando dotnet tool restore.

    dotnet tool restore

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

    Tool 'dotnet-env' (version '1.0.0') was restored. Available commands: dotnet-env
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

  4. Verifique se as ferramentas estão disponíveis:

    dotnet tool list

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

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

  5. Teste as ferramentas:

    dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run dotnet-env

Atualizar uma ferramenta local

A versão instalada da ferramenta dotnetsay local é 2.1.3. Use o comando de atualização da ferramenta dotnet 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 '3.0.3'
(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 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 da pesquisa estende-se através dos diretórios pai até que um arquivo de manifesto com isRoot = true seja encontrado.

Remover ferramentas locais

Remova as ferramentas instaladas executando o comando de desinstalação da ferramenta dotnet :

dotnet tool uninstall dotnet-env

dotnet tool uninstall dotnetsay

Troubleshoot

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

Consulte também

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

  • Last updated on