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 packages.config . È possibile ripristinare manualmente i pacchetti con nuget restore, dotnet restore, msbuild -t:restoreo tramite Visual Studio. I dotnet build comandi 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 pacchetti tenta di installare tutte le dipendenze del pacchetto allo stato corrispondente <PackageReference>a s in un file di progetto, ad esempio csproj o <package>s in un file packages.config . L'opzione Ripristino pacchetto installa prima di tutto le dipendenze dirette di un progetto in base alle esigenze, quindi installa eventuali dipendenze di tali pacchetti in tutto il grafico 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 prova a scaricarlo da tutte le origini configurate in Visual Studio in Opzioni>strumenti>NuGet Gestione pacchetti> Origini pacchetto.

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 pacchetti

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

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 del progetto viene ricreato.
  • Per i progetti che usano packages.config, il pacchetto viene visualizzato nella cartella pacchetti del progetto.
  • La compilazione del progetto dovrebbe ora avvenire senza problemi.

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

Se dopo l'esecuzione del ripristino del pacchetto sono presenti pacchetti o errori correlati al pacchetto, ad esempio icone di errore in Esplora soluzioni, seguire le istruzioni riportate in Risoluzione degli errori di ripristino dei pacchetti o reinstallare o aggiornare i pacchetti. In Visual Studio la console di Gestione pacchetti offre diverse opzioni per reinstallare i pacchetti. Per altre informazioni, vedere Usare Package-Update.

Ripristinare i pacchetti in Visual Studio

In Visual Studio in Windows è possibile ripristinare automaticamente o manualmente i pacchetti. Prima di tutto, configurare il ripristino dei pacchetti tramite Le opzioni degli>strumenti>nuGet Gestione pacchetti.

Configurare le opzioni di ripristino dei pacchetti di Visual Studio

Configurare le opzioni di ripristino dei pacchetti seguenti in Opzioni strumenti>>NuGet Gestione pacchetti> General.

Screenshot that shows the NuGet Package Manager options.

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 su nella sezione packageRestore del file NuGet.Config globale, in %AppData%\Roaming\NuGet in Windows o ~/.nuget/NuGet/ in True Mac o Linux.packageRestore/enabled

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

Nota

Per eseguire l'override globale dell'impostazionepackageRestore/enabled, è possibile impostare la variabile di ambiente EnableNuGetPackageRestore su True o False prima di aprire Visual Studio o avviare una compilazione.

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

Importante

Se si modificano direttamente le packageRestore impostazioni in NuGet.Config , riavviare Visual Studio in modo che le opzioni visualizzino i valori correnti.

Verificare automaticamente la presenza di pacchetti mancanti durante la compilazione

Selezionare Verifica automatica 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 su nella packageRestore sezione del file NuGet.Config.TruepackageRestore/automatic

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

Per i progetti non in stile SDK, è necessario selezionare Consenti a NuGet di scaricare pacchetti mancanti, nonché Verificare automaticamente la presenza di pacchetti mancanti durante la compilazione in Visual Studio in Opzioni per abilitare il ripristino automatico.

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.

Nota

  • Se un progetto non supporta entrambi i formati di gestione dei pacchetti, NuGet usa il formato di gestione dei pacchetti compatibile con il progetto, che potrebbe non essere l'impostazione predefinita nelle opzioni. NuGet non richiederà quindi la selezione al primo installazione, anche se è stata selezionata l'opzione.

  • Se si usa Gestione pacchetti Console per installare il primo pacchetto in un progetto, NuGet non richiede la selezione del formato, anche se questa opzione è selezionata in Opzioni.

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 Esplora soluzioni e scegliere Ripristina pacchetti NuGet 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 Esplora soluzioni in Pacchetti di dipendenze>. Pacchetti che non vengono installati correttamente quando si ripristinano manualmente o si eseguono icone di errore di visualizzazione della compilazione in Esplora soluzioni. Fare clic con il pulsante destro del mouse sul progetto, scegliere Gestisci pacchetti NuGet e usare il Gestione pacchetti NuGet 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.

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

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

.NET Core 2.0 e versioni successive dotnet build e dotnet run comandi ripristinano automaticamente i pacchetti. A partire da NuGet 4.0, dotnet restore esegue lo stesso codice di nuget restore.

Per ripristinare un pacchetto con dotnet restore:

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

Importante

Per aggiungere un riferimento al pacchetto mancante al file di progetto, usare dotnet add package, che esegue restoreanche .

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

Il comando di ripristino dell'interfaccia della riga di comando nuGet scarica e installa eventuali pacchetti mancanti. Il comando funziona su progetti che usano PackageReference o packages.config per i riferimenti ai pacchetti.

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

Per ripristinare i pacchetti, eseguire il comando seguente:

nuget restore <projectPath>

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.sln nella directory corrente, eseguire:

nuget restore MySolution.sln

Nota

Per i progetti non in stile SDK che usano PackageReference, usare invece msbuild -t:restore per ripristinare i pacchetti.

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 pacchetto packages.config , se usati con -p:RestorePackagesConfig=true.

Per usare il ripristino di MSBuild:

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

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

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

Nota

È possibile usare msbuild -restore per eseguire restore, ricaricare il progetto e compilare, poiché la compilazione è la destinazione predefinita. Per altre informazioni, vedere Ripristinare e compilare con un comando MSBuild.

Eseguire il ripristino con Azure Pipelines o Azure DevOps Server

Quando si crea una definizione di compilazione in Azure Pipelines, è possibile includere l'attività di ripristino dell'interfaccia della riga di comando nuGet 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 i vincoli di versione specificati in packages.config o nel file di progetto.

  • In packages.config è possibile specificare un allowedVersions intervallo nella dipendenza. Per altre informazioni, vedere Vincoli per le versioni di aggiornamento. Ad 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. Ad 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 da origini di 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 Cancella tutte le cache NuGet in Strumenti>Opzioni>NuGet Gestione pacchetti> Generale.
  • Nell'interfaccia della riga di comando 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 le 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 Visual Studio Gestione pacchetti o console.

Eseguire la migrazione al ripristino automatico dei pacchetti

Le versioni precedenti di NuGet supportano un ripristino integrato di 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.exe e 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 dei pacchetti automatico:

  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 packages 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