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

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

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 dotnet-env , navegue um nível acima até à 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 dotnet-env como uma ferramenta local (abordagem tradicional)

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

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

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

Use a ferramenta local instalada

Uma vez instalado como uma ferramenta local, você pode invocá-lo 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.

  • Utilização de 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 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.

  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 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 exemplo a seguir:

    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 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 '3.0.3'
(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 dotnet-env

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 .

  • Last updated on