Compartilhar via

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

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.

  • SDK do .NET 10.0.100 ou posterior (para dnx) – opcional, mas recomendado.

    Para este tutorial, você instala e usa uma ferramenta direcionada ao .NET Core 2.1, portanto, você precisa ter esse runtime instalado em seu computador. Para instalar o runtime 2.1, vá para 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 subdiretórios atuais), ela precisa ser adicionada a um arquivo de manifesto.

Na pasta microsoft.botsay, 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 o botsay como uma ferramenta local (abordagem tradicional)

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 local instalada

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

  • Execute a ferramenta diretamente usando dnx:

    dnx microsoft.botsay --add-source ./nupkg hello from the bot

    Observação

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

  • Usando dotnet botsay:

    dotnet botsay hello from the bot

  • Usando dotnet tool run

    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 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": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "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 '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.

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

  5. 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 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 '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 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 microsoft.botsay

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