Condividi tramite

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 il percorso. Una versione di uno strumento viene usata per tutte le directory nel computer.

  • Come strumento globale in una posizione personalizzata (noto anche come strumento tool-path).

    I file binari dello strumento vengono installati in un percorso specificato. È 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 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 di .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à totale. Non installare uno strumento .NET a meno che non si consideri 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:

Controllare 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 persone che non si fidano.

Se lo strumento è ospitato in NuGet, è possibile controllare l'autore e le statistiche cercando lo 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.

Annotazioni

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

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 il percorso 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 un percorso personalizzato

Per installare uno strumento come strumento globale in un percorso personalizzato, 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 tool-path, è 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 (per la directory corrente e le sottodirectory), è necessario aggiungere lo strumento a un file manifesto dello strumento. Per creare un file manifesto dello strumento, 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 dotnet tool install e omettere le --global opzioni e --tool-path , come illustrato nell'esempio seguente:

Avvertimento

Assicurarsi che il file manifesto dello strumento sia archiviato in una posizione controllata. L'interfaccia della riga di comando di .NET avvia gli strumenti locali con dotnet tool run in base al contenuto del manifesto dello strumento. Se il manifesto viene modificato da un'entità non attendibile, l'interfaccia della riga di comando potrebbe eseguire codice dannoso.

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.

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 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 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 fornire 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, 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 tool-path, usare l'opzione --tool-path .

Per elencare uno strumento specifico, usare il comando dotnet tool list <PACKAGE_ID> :

dotnet tool list dotnetsay

L'output elenca lo strumento solo se è installato, simile all'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, questo è ciò 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 consiste nell'usare il dotnet comando 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 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 nell'ambito dello strumento locale.

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

dotnet-doc

Richiamare uno strumento tool-path

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 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 per trovare il primo file manifesto contenente l'ID pacchetto. Se non è presente alcun ID pacchetto di questo tipo 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 sull'utilizzo degli strumenti, immettere uno dei comandi seguenti o visualizzare il sito Web dello strumento:

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

Vedere anche

  • Last updated on