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 nel computer senza specificarne la posizione. Una versione di uno strumento viene usata per tutte le directory nel computer.

  • Come strumento globale in una posizione personalizzata (noto anche come strumento per il percorso degli strumenti).

    I file binari dello strumento vengono installati in un percorso specificato. È possibile richiamare lo strumento dalla directory di installazione, fornendo 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 nel 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 delle relative sottodirectory. Directory diverse possono usare versioni diverse dello stesso strumento.

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

Importante

Gli strumenti .NET vengono eseguiti con attendibilità completa. Non installare uno strumento .NET a meno che 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à completa 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, usare l'opzione -g o --global di installazione dello strumento dotnet, come illustrato nell'esempio seguente:

dotnet tool install -g dotnetsay

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

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

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

Sistema operativo Percorso
Linux/macOS $HOME/.dotnet/tools
Windows %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 la posizione dello strumento.

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

Installare uno strumento globale in una posizione personalizzata

Per installare uno strumento come strumento globale in una posizione personalizzata, usare l'opzione --tool-path di installazione dello strumento dotnet, 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

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

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

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

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 di installazione dello strumento dotnet e omettere le --global opzioni 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, simile all'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.

Nell'esempio seguente viene illustrato 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 estrae il codice dal repository ottengono il file manifesto più recente. Per installare tutti gli strumenti elencati nel file manifesto, esegue il dotnet tool restore comando:

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 di uno strumento specifica

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

dotnet tool install dotnetsay --version 2.1.3

Per installare una versione preliminare dello strumento senza specificare il numero di versione esatta, 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 elenco degli strumenti dotnet :

dotnet tool list

L'output mostra la versione e il comando di ogni strumento, simile all'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 del percorso degli strumenti, usare l'opzione --tool-path .

Richiamare uno strumento globale

Per gli strumenti globali, usare il comando strumento stesso. Ad esempio, se il comando è dotnetsay o dotnet-doc, è ciò che si usa per richiamare lo strumento globale:

dotnetsay
dotnet-doc

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

dotnet doc

Tuttavia, nello scenario seguente non è possibile usare il dotnet comando 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 che si trova 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 del percorso degli strumenti

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

Richiamare uno strumento locale

Per richiamare uno strumento locale, è necessario usare il dotnet comando dalla directory di installazione. È possibile usare il modulo lungo () o il modulo breve (dotnet tool run <COMMAND_NAME>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 di aggiornamento degli strumenti dotnet 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 per trovare il primo file manifesto contenente l'ID pacchetto. Se non è presente tale ID pacchetto in alcun file manifesto, l'SDK aggiunge una nuova voce al file manifesto più vicino.

Disinstallare uno strumento

Disinstallare uno strumento usando il comando di disinstallazione dello strumento dotnet 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 per trovare 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 di comandi e parametri disponibili dotnet tool usando il --help parametro :

dotnet tool --help

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

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

Vedi anche