Come gestire gli strumenti .NET

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

Uno strumento .NET è un pacchetto NuGet speciale che contiene un'applicazione console. È possibile installare uno strumento nel computer nei modi seguenti:

  • Come strumento globale.

    I file binari dello strumento vengono installati in una directory predefinita aggiunta alla variabile di ambiente PATH. È possibile richiamare lo strumento da qualsiasi directory della macchina senza specificarne il percorso. Una versione di uno strumento viene usata per tutte le directory del computer.

  • Come strumento globale in un percorso personalizzato (noto anche come strumento tracciati).

    I file binari dello strumento vengono installati in un percorso specificato dall'utente. È possibile richiamare lo strumento dalla directory di installazione, specificando la directory con il nome del comando o aggiungendo la directory alla variabile di ambiente PATH. Una versione di uno strumento viene usata per tutte le directory del computer.

  • Come strumento locale (si applica a .NET Core SDK 3.0 e versioni successive).

    I file binari dello strumento vengono installati in una directory predefinita. È possibile richiamare lo strumento dalla directory di installazione o da una qualsiasi delle relative sottodirectory. Diverse directory possono usare versioni diverse dello stesso strumento.

    L'interfaccia della riga di comando di .NET usa i file manifesto per tenere traccia degli strumenti installati localmente in una directory. Quando il file manifesto viene salvato nella directory principale di un repository di codice sorgente, un collaboratore può clonare il repository e richiamare un singolo comando dell'interfaccia della riga di comando di .NET CLI per installare tutti gli strumenti elencati nei file manifesto.

Importante

Gli strumenti .NET vengono eseguiti con attendibilità totale. Non installare uno strumento .NET se non si considera attendibile l'autore.

Gli strumenti .NET potrebbero non funzionare correttamente se .NET è stato installato tramite Snap.

Trovare uno strumento

Ecco alcuni modi per trovare gli strumenti:

Verificare l'autore e le statistiche

Gli strumenti .NET possono essere potenti perché vengono eseguiti con attendibilità totale e gli strumenti globali vengono aggiunti alla variabile di ambiente PATH. Non scaricare gli strumenti da utenti non attendibili.

Se lo strumento è ospitato su NuGet, è possibile verificare l'autore e le statistiche eseguendo una ricerca dello strumento.

Installare uno strumento globale

Per installare uno strumento come strumento globale, utilizzare l'opzione -g o --global di dotnet tool install, come illustrato nell'esempio seguente:

dotnet tool install -g dotnetsay

L'output mostra il comando usato per richiamare lo strumento e la versione installata, come nell'esempio seguente:

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

Nota

Per impostazione predefinita, l'architettura dei file binari .NET da installare rappresenta l'architettura del sistema operativo attualmente in esecuzione. Per specificare un'architettura di sistema operativo diversa, vedere dotnet tool install, --opzione arch.

Il percorso predefinito per i file binari di uno strumento dipende dal sistema operativo:

Sistema operativo Percorso
Linux/macOS $HOME/.dotnet/tools
Finestre %USERPROFILE%\.dotnet\tools

Questo percorso viene aggiunto al percorso dell'utente quando l'SDK viene eseguito per la prima volta. Gli strumenti globali possono quindi essere richiamati da qualsiasi directory senza specificare il percorso dello strumento.

L'accesso agli strumenti è specifico dell'utente, non globale del computer. Uno strumento globale è disponibile solo per l'utente che lo ha installato.

Installare uno strumento globale in un percorso personalizzato

Per installare uno strumento come strumento globale in un percorso personalizzato, usare l'opzione --tool-path di dotnet tool install, come illustrato negli esempi seguenti:

In Windows:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

In Linux o macOS:

dotnet tool install dotnetsay --tool-path ~/bin

SDK .NET non aggiunge automaticamente questo percorso alla variabile di ambiente PATH. Per richiamare uno strumento tracciati, è necessario assicurarsi che il comando sia disponibile usando uno dei seguenti metodi:

  • Aggiungere la directory di installazione alla variabile di ambiente PATH.
  • Specificare il percorso completo dello strumento quando lo si richiama.
  • Richiamare lo strumento dall'interno della directory di installazione.

Installare uno strumento locale

Si applica a .NET Core 3.0 SDK e versioni successive.

Per installare uno strumento solo per l'accesso locale (per la directory e le sottodirectory correnti), è necessario aggiungere lo strumento a un file manifesto dello strumento. Per creare un file manifesto dello strumento, eseguire il comando dotnet new tool-manifest:

dotnet new tool-manifest

Questo comando crea un file manifesto denominato dotnet-tools.json nella directory .config. Per aggiungere uno strumento locale al file manifesto, usare il comando dotnet tool install e omettere le opzioni --global e --tool-path, come illustrato nell'esempio seguente:

dotnet tool install dotnetsay

L'output del comando mostra in quale file manifesto è presente lo strumento appena installato, come nell'esempio seguente:

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

L'esempio seguente mostra un file manifesto con due strumenti locali installati:

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

In genere si aggiunge uno strumento locale alla directory radice del repository. Dopo aver archiviato il file manifesto nel repository, gli sviluppatori che estraggono il codice dal repository ottengono il file manifesto più recente. Per installare tutti gli strumenti elencati nel file manifesto, eseguire il comando dotnet tool restore:

dotnet tool restore

L'output indica gli strumenti ripristinati:

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Installare una versione specifica dello strumento

Per installare una versione non definitiva o una versione specifica di uno strumento, specificare il numero di versione usando l'opzione --version, come illustrato nell'esempio seguente:

dotnet tool install dotnetsay --version 2.1.3

Per installare una versione non definitiva dello strumento senza specificare il numero di versione esatto, usare l'opzione --version e specificare un carattere jolly, come illustrato nell'esempio seguente:

dotnet tool install --global dotnetsay --version "*-rc*"

Usare uno strumento

Il comando usato per richiamare uno strumento potrebbe essere diverso dal nome del pacchetto installato. Per visualizzare tutti gli strumenti attualmente installati nel computer per l'utente corrente, usare il comando dotnet tool list:

dotnet tool list

L'output mostra la versione e il comando di ogni strumento, come nell'esempio seguente:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Come illustrato nell'esempio precedente, l'elenco mostra gli strumenti locali. Per visualizzare gli strumenti globali, usare l'opzione --global. Per visualizzare gli strumenti tracciati, usare l'opzione --tool-path.

Per elencare uno strumento specifico, usare il comando PACKAGE_ID<elenco degli strumenti dotnet>:

dotnet tool list dotnetsay

L'output elencherà lo strumento solo se è installato, come nell'esempio seguente:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Richiamare uno strumento globale

Per gli strumenti globali, usare il comando dello strumento da solo. Ad esempio, se il comando è dotnetsay o dotnet-doc, è quello che si usa per richiamare lo strumento globale:

dotnetsay
dotnet-doc

Se il comando inizia con il prefisso dotnet-, un modo alternativo per richiamare lo strumento è usare il comando dotnet e omettere il prefisso del comando dello strumento. Ad esempio, se il comando è dotnet-doc, il comando seguente richiama lo strumento:

dotnet doc

Tuttavia, nello scenario seguente non è possibile usare il comando dotnet per richiamare uno strumento globale:

  • Uno strumento globale e uno strumento locale hanno lo stesso comando preceduto da dotnet-.
  • Si vuole richiamare lo strumento globale da una directory nell'ambito dello strumento locale.

In questo scenario, dotnet doc e dotnet dotnet-doc richiamare lo strumento locale. Per richiamare lo strumento globale, usare il comando stesso:

dotnet-doc

Richiamare uno strumento tracciati

Per richiamare uno strumento globale installato usando l'opzione tool-path, assicurarsi che il comando sia disponibile come illustrato precedente in questo articolo.

Richiamare uno strumento locale

Per richiamare uno strumento locale, è necessario usare il comando dotnet dall'interno della directory di installazione. È possibile usare il formato lungo (dotnet tool run <COMMAND_NAME>) o la forma breve (dotnet <COMMAND_NAME>), come illustrato negli esempi seguenti:

dotnet tool run dotnetsay
dotnet dotnetsay

Se il comando è preceduto da dotnet-, è possibile includere o omettere il prefisso quando si richiama lo strumento. Ad esempio, se il comando è dotnet-doc, uno degli esempi seguenti richiama lo strumento locale:

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Aggiornare uno strumento

L'aggiornamento di uno strumento comporta la disinstallazione e la reinstallazione con la versione stabile più recente. Per aggiornare uno strumento, usare il comando dotnet tool update con la stessa opzione usata per installare lo strumento:

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

Per uno strumento locale, l'SDK cerca nella directory corrente e nelle directory padre il primo file manifesto contenente l'ID pacchetto. Se non è presente un ID pacchetto simile in nessun file manifesto, l'SDK aggiunge una nuova voce al file manifesto più vicino.

Disinstallare uno strumento

Disinstallare uno strumento usando il comando dotnet tool uninstall con la stessa opzione usata per installare lo strumento:

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

Per uno strumento locale, l'SDK cerca nella directory corrente e nelle directory padre il primo file manifesto contenente l'ID pacchetto.

Ottenere assistenza e risolvere i problemi

Se non è possibile installare o eseguire uno strumento, vedere Risolvere i problemi di utilizzo degli strumenti .NET. È possibile ottenere un elenco dei comandi e dei parametri dotnet tool disponibili usando il parametro --help:

dotnet tool --help

Per ottenere le istruzioni sull'utilizzo degli strumenti, immettere uno dei comandi seguenti o visualizzare il sito Web dello strumento:

<command> --help
dotnet <command> --help

Vedi anche