Partilhar via

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

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.

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

    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 (abordagem tradicional)

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

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

  • Utilização de 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 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": {
    "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 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 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

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

  • Last updated on