Ripristinare i pacchetti con il ripristino del pacchetto NuGet

Il ripristino pacchetti NuGet ripristina tutte le dipendenze di un progetto elencate in un file di progetto o in un file dipackages.config . È possibile ripristinare manualmente i pacchetti con nuget restore, dotnet restore, msbuild -t:restore o tramite Visual Studio. I comandi dotnet build e dotnet run ripristinano automaticamente i pacchetti ed è possibile configurare Visual Studio per ripristinare automaticamente i pacchetti quando compila un progetto.

Per promuovere un ambiente di sviluppo più pulito e ridurre le dimensioni del repository, Ripristino pacchetti rende disponibili tutte le dipendenze di un progetto senza doverle archiviare nel controllo del codice sorgente. Per configurare il repository del controllo del codice sorgente per escludere i file binari del pacchetto, vedere Pacchetti e controllo del codice sorgente.

Comportamento di ripristino dei pacchetti

Il ripristino dei pacchetti tenta di installare tutte le dipendenze del pacchetto nello stato corrispondente a <PackageReference> in un file di progetto, ad esempio .csproj, o <package> in un file packages.config. Il ripristino dei pacchetti installa prima le dipendenze dirette di un progetto se necessario, quindi installa tutte le dipendenze di tali pacchetti in tutto il grafico delle dipendenze.

Se non è già installato un pacchetto necessario, NuGet tenta prima di tutto di recuperarlo dai pacchetti globali locali o dalle cartelle della cache HTTP. Se il pacchetto non si trova nelle cartelle locali, NuGet tenta di scaricarlo da tutte le origini configurate in Visual Studio in Tools>Options>Opzioni> >NuGet Package Manager>Package Sources.

Durante il ripristino, NuGet ignora l'ordine delle origini dei pacchetti e usa il pacchetto dalla prima origine che risponde alle richieste. Se il ripristino non riesce, NuGet non indica l'errore fino a quando non controlla tutte le origini. NuGet segnala quindi un errore solo per l'ultima origine nell'elenco. L'errore implica che il pacchetto non era presente in nessuna delle origini, anche se non elenca gli altri errori singolarmente.

Per altre informazioni sul comportamento di NuGet, vedere Configurazioni NuGet comuni.

Ripristinare i pacchetti

Se i riferimenti al pacchetto nel file di progetto o packages.config file sono corretti, usare lo strumento preferito per ripristinare i pacchetti:

• Visual Studio
• dotnet CLI
• interfaccia della riga di comando di nuget.exe
• msbuild
• Azure Pipelines o Azure DevOps Server

Dopo un ripristino riuscito:

• Per i progetti che usano <PackageReference>, il pacchetto è presente nella cartella global-packages locale e il file obj/project.assets.json progetto viene ricreato.
• Per i progetti che usano packages.config, il pacchetto viene visualizzato nella cartella pacchetti del progetto.
• Il progetto dovrebbe ora essere costruito correttamente.

Se i riferimenti al pacchetto nel file di progetto o nel file dipackages.config non sono corretti e non corrispondono allo stato desiderato, installare o aggiornare i pacchetti corretti anziché usare il ripristino dei pacchetti.

Se, dopo l'esecuzione del ripristino del pacchetto, riscontri pacchetti mancanti o errori correlati ai pacchetti, ad esempio icone di errore in Solution Explorer, segui le istruzioni riportate in Risoluzione dei problemi di ripristino dei pacchetti o reinstalla o aggiorna i pacchetti. In Visual Studio la console di Package Manager offre diverse opzioni per reinstallare i pacchetti. Per ulteriori informazioni, vedi Usare Package-Update.

Ripristinare i pacchetti in Visual Studio

In Visual Studio in Windows è possibile ripristinare i pacchetti automaticamente o manualmente. Prima di tutto, configurare il Ripristino pacchetti tramite Tools>Options>NuGet Package Manager.

Configurare le opzioni di ripristino dei pacchetti Visual Studio

Configurare le opzioni di ripristino pacchetti seguenti in Tools>Options>NuGet Package Manager>General.

Consenti a NuGet di scaricare pacchetti mancanti

Selezionare Consenti a NuGet di scaricare i pacchetti mancanti per abilitare il ripristino dei pacchetti e il comando Ripristina pacchetti NuGet . Questa selezione imposta l'impostazione packageRestore/enabled su True nella sezione packageRestore del file globale NuGet.Config, in %AppData%\Roaming\NuGet in Windows o ~/.nuget/NuGet/ in Mac o Linux.

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Per abilitare o disabilitare il ripristino dei pacchetti per tutti gli utenti in un computer, è possibile aggiungere le impostazioni di configurazione al file globale NuGet.Config in Windows in %ProgramData%\NuGet\Config, a volte in uno specifico <IDE>\<Version>\<SKU> Visual Studio cartella o in Mac/Linux in ~/.local/share. I singoli utenti possono quindi abilitare in modo selettivo il ripristino in base alle esigenze a livello di progetto. Per altre informazioni su come NuGet assegna la priorità a più file di configurazione, vedere Configurazioni NuGet comuni.

Verificare automaticamente la presenza di pacchetti mancanti durante la compilazione

Selezionare Verificare automaticamente la presenza di pacchetti mancanti durante la compilazione in Visual Studio per ripristinare automaticamente eventuali pacchetti mancanti quando si esegue una compilazione da Visual Studio. Questa impostazione non influisce sulle compilazioni eseguite dalla riga di comando di MSBuild. Questa selezione imposta l'impostazione packageRestore/automatic su True nella packageRestore sezione del file NuGet.Config .

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

È necessario selezionare Allow NuGet per scaricare pacchetti mancanti nonché Verificare automaticamente la presenza di pacchetti mancanti durante la compilazione in Visual Studio in Opzioni per abilitare il ripristino dei pacchetti durante la compilazione.

Scegliere il formato di gestione dei pacchetti predefinito

NuGet ha due formati di gestione dei pacchetti, PackageReference e packages.config. Selezionare il formato da usare nell'elenco a discesa in Gestione pacchetti. È anche possibile selezionare se consentire la selezione del formato al primo installazione del pacchetto.

Ripristinare i pacchetti manualmente o automaticamente

Dopo aver abilitato il ripristino dei pacchetti in Opzioni, è possibile fare clic con il pulsante destro del mouse sulla soluzione in Solution Explorer e selezionare Restore NuGet Packages per ripristinare i pacchetti in qualsiasi momento.

Se è stato abilitato il ripristino automatico in Opzioni, il ripristino dei pacchetti viene eseguito automaticamente quando si crea un progetto da un modello o si compila un progetto. Per NuGet 4.0+, il ripristino viene eseguito automaticamente anche quando si apportano modifiche a un progetto in stile SDK.

Per i progetti che usano <PackageReference>, è possibile visualizzare i riferimenti al pacchetto in Visual Studio Solution Explorer in Dependencies>Packages. Pacchetti che non vengono installati correttamente, quando li ripristini manualmente o esegui una build, mostrano icone di errore in Solution Explorer. Fare clic con il pulsante destro del mouse sul progetto, selezionare Gestisci pacchetti NuGet e usare il NuGet Package Manager per disinstallare e reinstallare i pacchetti interessati. Per altre informazioni, vedere Reinstallare e aggiornare i pacchetti.

Se viene visualizzato l'errore Questo progetto fa riferimento a pacchetti NuGet mancanti nel computer oppure è necessario ripristinare uno o più pacchetti NuGet, ma non è stato possibile perché il consenso non è stato concesso, assicurarsi di abilitare il ripristino automatico. Per i progetti meno recenti, vedere Eseguire la migrazione al ripristino automatico dei pacchetti. Vedere anche Risoluzione degli errori di ripristino dei pacchetti.

Ripristinare usando il CLI dotnet

Il dotnet restore comando ripristina i pacchetti elencati negli <PackageReference> elementi nel file di progetto. Per altre informazioni, vedere PackageReference nei file di progetto.

A partire da .NET Core 2.0 e continuando con .NET, i comandi dotnet build e dotnet run ripristinano automaticamente i pacchetti, come molti altri comandi dell'interfaccia della riga di comando dotnet. A partire da NuGet 4.0, dotnet restore esegue lo stesso codice del comando della CLI di nuget restore NuGet.

Per ripristinare i pacchetti tramite dotnet restore:

1. Aprire una finestra della riga di comando e passare alla directory che contiene il file di progetto.
2. Eseguire dotnet restore.

Eseguire il ripristino usando l'interfaccia della riga di comando di NuGet

Il comando CLI di NuGet restore scarica e installa eventuali pacchetti mancanti. Il comando funziona sui progetti che usano PackageReference o packages.config per i riferimenti ai pacchetti.

Come install, il restore comando aggiunge solo pacchetti al disco. Non modifica il file di progetto o packages.config file. Per aggiungere dipendenze di progetto, usare l'interfaccia utente o la console di Visual Studio Package Manager.

Per ripristinare i pacchetti, eseguire il comando seguente:

nuget restore <project-path>

Il restore comando usa un file di soluzione o un file package.config nel percorso del progetto specificato.

Ad esempio, per ripristinare tutti i pacchetti per MySolution.slnx nella directory corrente, eseguire il comando seguente:

nuget restore MySolution.slnx

Eseguire il ripristino tramite MSBuild

È possibile usare msbuild -t:restore per ripristinare i pacchetti in NuGet 4.x+ e MSBuild 15.1+, inclusi in Visual Studio 2017 e versioni successive.

Questo comando ripristina i pacchetti nei progetti che usano PackageReference per i riferimenti ai pacchetti. A partire da MSBuild 16.5+, il comando supporta anche i riferimenti al pacchettopackages.config , se usati con -p:RestorePackagesConfig=true.

Per usare il ripristino di MSBuild:

1. Aprire un prompt dei comandi per sviluppatori cercando prompt dei comandi per sviluppatori e avviando il prompt dal menu Start di Windows Start, che configura tutti i percorsi necessari per MSBuild.

2. Passare alla cartella del progetto e immettere msbuild -t:restore.

3. Al termine del ripristino, inserisci msbuild per ricostruire il progetto. Assicurarsi che l'output di MSBuild indichi che la compilazione è stata completata correttamente.

Eseguire il ripristino con Azure Pipelines o Azure DevOps Server

Quando si crea una definizione di compilazione in Azure Pipelines, è possibile includere l'attività 'NuGet CLI restore' o 'dotnet CLI restore' nella definizione prima di qualsiasi attività di compilazione. Alcuni modelli di compilazione includono l'attività di ripristino per impostazione predefinita.

Azure DevOps Server e TFS 2013 e versioni successive ripristinano automaticamente i pacchetti durante la compilazione, se si usa un modello TFS 2013 o versione successiva di Team Build. È anche possibile includere un passaggio di compilazione per eseguire un'opzione di ripristino della riga di comando o, facoltativamente, eseguire la migrazione del modello di compilazione a una versione successiva. Per altre informazioni, vedere Configurare il ripristino dei pacchetti con Team Foundation Build.

Vincolare le versioni dei pacchetti

Il ripristino NuGet tramite qualsiasi metodo rispetta tutti i vincoli di versione specificati in packages.config o nel file di progetto.

• In packages.configè possibile specificare un allowedVersions intervallo nella dipendenza. Per ulteriori informazioni, consultare Vincoli per le versioni di aggiornamento. Per esempio:

  <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />
  

• In un file di progetto è possibile specificare l'intervallo di versioni nella Version proprietà della dipendenza. Per esempio:

  <PackageReference Include="Newtonsoft.json" Version="[6,7)" />
  

In entrambi i casi, usare la notazione descritta in Controllo delle versioni dei pacchetti.

Forzare il ripristino dalle fonti dei pacchetti remoti

Per impostazione predefinita, le operazioni di ripristino di NuGet usano pacchetti dalle cartelle global-packages e http-cache locali, come descritto in Gestire i pacchetti globali e le cartelle della cache. Per evitare di usare questi pacchetti locali, usare le opzioni seguenti.

Per cancellare tutte le cache locali:

• In Visual Studio selezionare il pulsante Clear All NuGet Cache(s) in Tools>Options>NuGet Package Manager>General.
• Nella CLI dotnet usare dotnet nuget locals all --clear.
• Nell'interfaccia della riga di comando di NuGet usare nuget locals all -clear.

Per evitare di usare i pacchetti nella cartella global-packages :

• Cancellare la cartella utilizzando nuget locals global-packages -clear o dotnet nuget locals global-packages --clear.
• Impostare temporaneamente la variabile di ambiente NUGET_PACKAGES su una cartella diversa.
• Creare un file NuGet.Config che imposta globalPackagesFolder per PackageReference, o repositoryPath per packages.config, in una cartella diversa. Per altre informazioni, vedere Impostazioni di configurazione.
• Solo per MSBuild, specificare una cartella diversa con la RestorePackagesPath proprietà .

Per evitare di usare pacchetti nella cache HTTP:

• Cancellare la cache usando nuget locals http-cache -clear o dotnet nuget locals http-cache --clear.
• Impostare temporaneamente la variabile di ambiente NUGET_HTTP_CACHE_PATH su una cartella diversa.
• Per nuget restoreusare l'opzione -NoHttpCache o per dotnet restore, usare l'opzione --no-http-cache . Queste opzioni non influiscono sulle operazioni di ripristino tramite la Visual Studio Package Manager o la console.

Eseguire la migrazione al ripristino automatico dei pacchetti

Le versioni precedenti di NuGet supportavano un ripristino pacchetti integrato con MSBuild. I progetti che usano il ripristino del pacchetto integrato MSBuild deprecato devono eseguire la migrazione al ripristino automatico dei pacchetti.

Questi progetti in genere contengono una cartella nuget con tre file: NuGet.config, nuget.exee NuGet.targets. Il file NuGet.targets fa sì che NuGet usi l'approccio integrato msBuild, quindi deve essere rimosso.

Per eseguire la migrazione al ripristino automatico dei pacchetti:

1. Abilitare il ripristino automatico dei pacchetti.
2. Chiudere Visual Studio.
3. Eliminare .nuget/nuget.exe e .nuget/NuGet.targets.
4. Per ogni file di progetto, rimuovere l'elemento <RestorePackages> e rimuovere eventuali riferimenti a NuGet.targets.

Per testare il ripristino automatico dei pacchetti:

1. Rimuovere la cartella pacchetti dalla soluzione.
2. Aprire la soluzione in Visual Studio e avviare una compilazione. Il ripristino automatico dei pacchetti deve scaricare e installare ogni pacchetto di dipendenza, senza aggiungerlo al controllo del codice sorgente.

Passaggi successivi

• Risolvere i problemi di ripristino dei pacchetti
• Gestire i pacchetti globali, la cache e le cartelle temporanee