Risolvere i problemi di utilizzo degli strumenti .NET

  • Articolo

Potrebbero verificarsi problemi durante il tentativo di installare o eseguire uno strumento .NET, che può essere uno strumento globale o uno strumento locale. Questo articolo descrive le cause radice comuni e alcune possibili soluzioni.

L'esecuzione dello strumento .NET installato non riesce

Quando l'esecuzione di uno strumento .NET non riesce, probabilmente si è verificato uno dei problemi seguenti:

File eseguibile non trovato

Se il file eseguibile non viene trovato, verrà visualizzato un messaggio simile al seguente:

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

Il nome dell'eseguibile determina come richiamare lo strumento. La tabella seguente descrive il formato:

Formato nome eseguibile Formato chiamata
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

Strumenti globali

Gli strumenti globali possono essere installati nella directory predefinita o in un percorso specifico. Le directory predefinite sono:

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

Se si sta tentando di eseguire uno strumento globale, verificare che la variabile di ambiente PATH nel computer contenga il percorso in cui è stato installato lo strumento globale e che il file eseguibile si trovi in tale percorso.

L'interfaccia della riga di comando di .NET tenta di aggiungere il percorso predefinito alla variabile di ambiente PATH al primo utilizzo. Esistono tuttavia alcuni scenari in cui la posizione potrebbe non essere aggiunta automaticamente a PATH:

  • Se si usa Linux e si è installato .NET SDK usando file .tar.gz e non apt-get o rpm.
  • Se si usa macOS 10.15 "Catalina" o versioni successive.
  • Se si usa macOS 10.14 "Mojave" o versioni precedenti e si è installato .NET SDK usando file .tar.gz e non .pkg.
  • Se è stato installato .NET Core 3.0 SDK e si è impostata la variabile di ambiente DOTNET_ADD_GLOBAL_TOOLS_TO_PATH su false.
  • Se è stato installato .NET Core 2.2 SDK o versioni precedenti e la variabile di ambiente DOTNET_SKIP_FIRST_TIME_EXPERIENCE è stata impostata su true.

In questi scenari o se è stata specificata l'opzione --tool-pathdurante l'installazione di uno strumento dotnet, la variabile di ambiente PATH nel computer non contiene automaticamente il percorso in cui è stato installato lo strumento globale. In tal caso, aggiungere il percorso dello strumento (ad esempio, $HOME/.dotnet/tools) alla variabile PATH di ambiente usando qualsiasi metodo fornito dalla shell per aggiornare le variabili di ambiente. Per altre informazioni, vedere strumenti .NET.

Strumenti locali

Se si sta tentando di eseguire uno strumento locale, verificare che sia presente un file manifesto denominato dotnet-tools.json nella directory corrente o in una delle directory padre. Questo file può anche trovarsi in una cartella denominata .config ovunque nella gerarchia delle cartelle del progetto, anziché nella cartella radice. Se dotnet-tools.json esiste, aprirlo e verificare la presenza dello strumento che si sta tentando di eseguire. Se il file non contiene una voce per "isRoot": true, controllare anche la gerarchia dei file per altri file manifesto dello strumento.

Se si sta tentando di eseguire uno strumento .NET installato con un percorso specificato, è necessario includere tale percorso quando si usa lo strumento. Un esempio di uso di uno strumento installato con percorso strumento è:

..\<toolDirectory>\dotnet-<toolName>

Runtime non trovato

Gli strumenti .NET sono applicazioni dipendenti dal framework, il che significa che si basano su un runtime .NET installato nel computer. Se il runtime previsto non viene trovato, seguono le normali regole di roll forward del runtime .NET, ad esempio:

  • Un'applicazione esegue il roll forward alla versione di patch più recente della versione principale e secondaria specificate.
  • Se non esiste un runtime corrispondente con un numero di versione principale e secondario corrispondente, viene usata la versione secondaria successiva.
  • Il roll forward non viene eseguito tra due versioni di anteprima del runtime o tra versioni di anteprima e versioni di rilascio. Gli strumenti .NET creati con le versioni di anteprima devono quindi essere ricompilati e ripubblicati dall'autore e reinstallati.

Il rollforward non si verificherà per impostazione predefinita in due scenari comuni:

  • Sono disponibili solo versioni precedenti del runtime. Il rollforward seleziona solo le versioni successive del runtime.
  • Sono disponibili solo versioni principali più recenti del runtime. Il rollforward non supera i limiti di versione principali.

Se un'applicazione non riesce a trovare un runtime appropriato, l'esecuzione non riesce e segnala un errore.

È possibile scoprire quali runtime .NET sono installati nel computer usando uno dei comandi seguenti:

dotnet --list-runtimes
dotnet --info

Se si ritiene che lo strumento supporti la versione di runtime attualmente installata, è possibile contattare l'autore dello strumento e verificare se è possibile aggiornare il numero di versione o multi-destinazione. Dopo aver ricompilato e ripubblicato il pacchetto dello strumento in NuGet con un numero di versione aggiornato, è possibile aggiornare la copia. Anche se ciò non avviene, la soluzione più rapida consiste nell'installare una versione del runtime che funzionerebbe con lo strumento che si sta tentando di eseguire. Per scaricare una versione specifica del runtime .NET, visitare la pagina di download di .NET.

Se si installa .NET SDK in un percorso non predefinito, è necessario impostare la variabile di ambiente DOTNET_ROOT sulla directory che contiene l'eseguibile dotnet.

L'installazione dello strumento .NET non riesce

Esistono diversi motivi per cui l'installazione di uno strumento globale o locale .NET potrebbe non riuscire. Quando l'installazione dello strumento non riesce, verrà visualizzato un messaggio simile al seguente:

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

Per diagnosticare questi errori, i messaggi NuGet vengono visualizzati direttamente all'utente, insieme al messaggio precedente. Il messaggio NuGet può aiutare a identificare il problema.

Imposizione dei nomi dei pacchetti

Microsoft ha modificato le linee guida sull'ID pacchetto per gli strumenti, con conseguente mancata ricerca di numerosi strumenti con il nome stimato. Le nuove indicazioni sono che tutti gli strumenti Microsoft devono essere preceduti da "Microsoft". Questo prefisso è riservato e può essere usato solo per i pacchetti firmati con un certificato autorizzato Microsoft.

Durante la transizione, alcuni strumenti Microsoft avranno la forma precedente dell'ID pacchetto, mentre altri avranno il nuovo modulo:

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

Man mano che gli ID pacchetto vengono aggiornati, è necessario passare al nuovo ID pacchetto per ottenere gli aggiornamenti più recenti. I pacchetti con il nome dello strumento semplificato saranno deprecati.

Versioni preliminari

  • Si sta tentando di installare una versione di anteprima e non si è usata l'opzione --version per specificare la versione.

Gli strumenti .NET in anteprima devono essere specificati con una parte del nome per indicare che sono in anteprima. Non è necessario includere l'intera anteprima. Supponendo che i numeri di versione siano nel formato previsto, è possibile usare un codice simile all'esempio seguente:

dotnet tool install -g --version 1.1.0-pre <toolName>

Il pacchetto non è uno strumento .NET

  • È stato trovato un pacchetto NuGet con questo nome, ma non era uno strumento .NET.

Se si tenta di installare un pacchetto NuGet che è un normale pacchetto NuGet e non uno strumento .NET, verrà visualizzato un errore simile al seguente:

NU1212: combinazione di pacchetti di progetto non valida per <toolName>. Lo stile del progetto DotnetToolReference può contenere solo riferimenti del tipo DotnetTool.

Non è possibile accedere al feed NuGet

  • Non è possibile accedere al feed NuGet richiesto, ad esempio a causa di un problema di connessione Internet.

L'installazione dello strumento richiede l'accesso al feed NuGet che contiene il pacchetto dello strumento. Ha esito negativo se il feed non è disponibile. È possibile modificare i feed con nuget.config, richiedere un file specifico nuget.config o specificare feed aggiuntivi con l'opzione --add-source. Per impostazione predefinita, NuGet genera un errore per qualsiasi feed che non è in grado di connettersi. Il flag --ignore-failed-sources può ignorare queste origini non raggiungibili.

ID pacchetto non corretto

  • Il nome dello strumento è stato digitato in modo non appropriato.

Un motivo comune per cui si verifica un errore è che il nome dello strumento non è corretto. Ciò può verificarsi a causa di errori di digitazione o perché lo strumento è stato spostato o deprecato. Per gli strumenti su NuGet.org, un modo per assicurarsi di avere il nome corretto consiste nel cercare lo strumento in NuGet.org e copiare il comando di installazione.

401 (Non autorizzato)

È molto probabile che sia stato specificato un feed NuGet alternativo e che il feed richieda l'autenticazione. Esistono diversi modi per risolvere questo problema:

  • Aggiungere il parametro --ignore-failed-sources per ignorare l'errore dal feed privato e usare il feed Microsoft pubblico.

    Se si installa uno strumento dal feed Microsoft NuGet, il feed personalizzato restituisce questo errore prima che il feed NuGet di Microsoft restituisca un risultato. L'errore termina la richiesta, annullando qualsiasi altra richiesta di feed in sospeso, che potrebbe essere il feed NuGet di Microsoft. L'aggiunta dell'opzione --ignore-failed-sources fa sì che il comando consideri questo errore come avviso e consenta ad altri feed di elaborare la richiesta.

    dotnet tool install -g --ignore-failed-sources <toolName>

  • Forzare il feed Microsoft NuGet con il parametro --add-source.

    È possibile che il file di configurazione NuGet globale o locale non sia presente nel feed NuGet Microsoft pubblico. Usare una combinazione dei parametri --add-source e --ignore-failed-sources per evitare il feed errato e basarsi sul feed Microsoft pubblico.

    dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>

  • Usare una configurazione NuGet personalizzata, parametro --configfile <FILE>.

    Creare un locale file nuget.config con solo il feed NuGet Microsoft pubblico, e farvi riferimento con il parametro --configfile:

    dotnet tool install -g --configfile "./nuget.config" <toolName>

    Ecco un file di configurazione di esempio:

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>

    Per altre informazioni, vedere Informazioni di riferimento su nuget.config

  • Aggiungere le credenziali necessarie al file di configurazione.

    Se si conosce che il pacchetto esiste nel feed configurato, specificare le credenziali di accesso nel file di configurazione NuGet. Per altre informazioni sulle credenziali in un file di configurazione nuget, vedere la sezione packageSourceCredentials della di riferimento nuget.config.

Vedi anche