Tutorial: Instalar e utilizar uma ferramenta local .NET com a CLI do .NET

Artigo
05/10/2023

Este artigo aplica-se a: ✔️ SDK .NET Core 3.0 e versões posteriores

Este tutorial ensina-o a instalar e utilizar uma ferramenta local. Utiliza uma ferramenta que cria no primeiro tutorial desta série.

Pré-requisitos

Conclua o primeiro tutorial desta série.
Instale o runtime .NET Core 2.1.

Neste tutorial, vai instalar e utilizar uma ferramenta que visa o .NET Core 2.1, pelo que precisa de ter esse runtime instalado no seu computador. Para instalar o runtime 2.1, aceda à página de transferência do .NET Core 2.1 e localize a ligação de instalação do runtime na coluna Executar aplicações – Runtime .

Criar um ficheiro de manifesto

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

Na pasta microsoft.botsay , navegue um nível para a pasta do repositório :

cd ..

Crie um ficheiro de manifesto ao executar o novo comando dotnet :

dotnet new tool-manifest

O resultado indica a criação com êxito do ficheiro.

The template "Dotnet local tool manifest file" was created successfully.

O ficheiro.config/dotnet-tools.json ainda não tem ferramentas:

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

As ferramentas listadas num ficheiro 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 ficheiro de manifesto.

Quando utiliza um comando da CLI que se refere a uma ferramenta local, o SDK procura um ficheiro de manifesto no diretório atual e nos diretórios principais. Se encontrar um ficheiro de manifesto, mas o ficheiro não incluir a ferramenta referenciada, continua a pesquisa através dos diretórios principais. A pesquisa termina quando encontra a ferramenta referenciada ou encontra um ficheiro de manifesto com isRoot definido como true.

Instalar o botsay como uma ferramenta local

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

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

Este comando adiciona a ferramenta ao ficheiro de manifesto que criou no passo anterior. A saída do comando mostra em que ficheiro de manifesto se encontra a ferramenta recentemente instalada:

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 ficheiro.config/dotnet-tools.json tem agora uma ferramenta:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    }
  }
}

Utilizar a ferramenta

Invoque a ferramenta ao executar o dotnet tool run comando a partir da pasta do repositório :

dotnet tool run botsay hello from the bot

Restaurar uma ferramenta local instalada por outras pessoas

Normalmente, instala uma ferramenta local no diretório de raiz do repositório. Depois de dar entrada do ficheiro de manifesto no repositório, outros programadores podem obter o ficheiro de manifesto mais recente. Para instalar todas as ferramentas listadas no ficheiro de manifesto, podem executar um único dotnet tool restore comando.

Abra o ficheiro.config/dotnet-tools.json e substitua os conteúdos pelo seguinte JSON:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Guarde as alterações.

Efetuar esta alteração é o mesmo que obter a versão mais recente do repositório depois de outra pessoa ter instalado o pacote dotnetsay para o diretório do projeto.

Execute o comando dotnet tool restore.

dotnet tool restore

O comando produz um resultado como o seguinte exemplo:

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

O resultado é uma lista de pacotes e comandos, semelhante ao exemplo seguinte:

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 dotnetsay local é a 2.1.3. Utilize o comando de atualização da ferramenta dotnet para atualizar a ferramenta para a versão mais recente.

dotnet tool update dotnetsay

O resultado indica o novo número da 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 ficheiro de manifesto que contém o ID do pacote e atualiza-o. Se não existir esse ID de pacote em qualquer ficheiro de manifesto que esteja no âmbito da pesquisa, o SDK adiciona uma nova entrada ao ficheiro de manifesto mais próximo. O âmbito de pesquisa é atualizado através dos diretórios principais até ser encontrado um ficheiro de manifesto com isRoot = true .

Remover ferramentas locais

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

dotnet tool uninstall microsoft.botsay

dotnet tool uninstall dotnetsay

Resolução de problemas

Se receber uma mensagem de erro ao seguir o tutorial, veja Resolver problemas de utilização da ferramenta .NET.

Ver também

Para obter mais informações, veja Ferramentas do .NET