Esercitazione: Installare e usare uno strumento locale .NET con l'interfaccia della riga di comando di .NET

  • Articolo

Questo articolo si applica a: ✔️ .NET Core 3.0 SDK e versioni successive

Questa esercitazione illustra come installare e usare uno strumento locale. Userai uno strumento che hai creato nella prima esercitazione di questa serie.

Prerequisiti

  • Completa la prima esercitazione di questa serie.

  • Installare il runtime di .NET Core 2.1.

    In questa esercitazione installerai e userai uno strumento destinato a .NET Core 2.1, quindi è necessario che quel runtime sia installato nel tuo computer. Per installare il runtime 2.1, accedi alla pagina di download di .NET Core 2.1 e cerca il collegamento di installazione del runtime nella colonna Esegui app - Runtime.

Creare un file manifesto

Per installare uno strumento solo per l'accesso locale (per la directory corrente e le sottodirectory), deve essere aggiunto a un file manifesto.

Dalla cartella microsoft.botsay passa a un livello superiore fino alla cartella del repository:

cd ..

Crea un file manifesto eseguendo il comando dotnet new:

dotnet new tool-manifest

L'output indica la corretta creazione del file.

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

Il file .config/dotnet-tools.json non include ancora strumenti:

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

Gli strumenti elencati in un file manifesto sono disponibili per la directory corrente e le sottodirectory. La directory corrente è quella che contiene la directory config con il file manifesto.

Quando si usa un comando dell'interfaccia della riga di comando che fa riferimento a uno strumento locale, l'SDK cerca un file manifesto nella directory corrente e nelle directory padre. Se trova un file manifesto, ma il file non include lo strumento di riferimento, continua la ricerca nelle directory padre. La ricerca termina quando trova lo strumento a cui si fa riferimento oppure quando trova un file manifesto con isRoot impostato su true.

Installare botsay come strumento locale

Installa lo strumento dal pacchetto che hai creato nella prima esercitazione:

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

Questo comando aggiunge lo strumento al file manifesto creato nel passaggio precedente. L'output del comando mostra il file manifesto in cui si trova lo strumento appena installato:

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

Il file .config/dotnet-tools.json ora include uno strumento:

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

Usare lo strumento

Richiama lo strumento eseguendo il comando dotnet tool run dalla cartella del repository:

dotnet tool run botsay hello from the bot

Ripristinare uno strumento locale installato da altri utenti

In genere si installa uno strumento locale nella directory radice del repository. Dopo aver archiviato il file manifesto nel repository, altri sviluppatori possono ottenere il file manifesto più recente. Per installare tutti gli strumenti elencati nel file manifesto, è possibile eseguire un singolo comando dotnet tool restore.

  1. Apri il file .config/dotnet-tools.json e sostituisci il contenuto con il JSON seguente:

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

  2. Salva le modifiche.

    Applicare questa modifica equivale a ottenere la versione più recente dal repository dopo che un altro utente ha installato il pacchetto dotnetsay per la directory del progetto.

  3. Eseguire il comando dotnet tool restore.

    dotnet tool restore

    Il comando genera un output simile all'esempio seguente:

    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. Verifica che gli strumenti siano disponibili:

    dotnet tool list

    L'output è un elenco di pacchetti e comandi, simile all'esempio seguente:

    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. Testa gli strumenti:

    dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run botsay hello from botsay

Aggiorna uno strumento locale

La versione installata dello strumento locale dotnetsay è 2.1.3. Usa il comando dotnet tool update per aggiornare lo strumento alla versione più recente.

dotnet tool update dotnetsay

L'output indica il nuovo numero di versione:

Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '2.1.7'
(manifest file /home/name/repository/.config/dotnet-tools.json).

Il comando update trova il primo file manifesto che contiene l'ID del pacchetto e lo aggiorna. Se non è presente alcun ID pacchetto in nessun file manifesto che rientra nell'ambito della ricerca, l'SDK aggiunge una nuova voce al file manifesto più vicino. L'ambito di ricerca si estende alle directory padre fino a quando non viene trovato un file manifesto con isRoot = true.

Rimuovere gli strumenti locali

Rimuovi gli strumenti installati eseguendo il comando dotnet tool uninstall:

dotnet tool uninstall microsoft.botsay

dotnet tool uninstall dotnetsay

Risoluzione dei problemi

Se compare un messaggio di errore durante l'esercitazione, vedi Risolvere i problemi di utilizzo degli strumenti .NET.

Vedi anche

Per altre informazioni, vedi Strumenti .NET