Eseguire la migrazione da packages.config a PackageReference

Visual Studio 2017 versione 15.7 e successive supporta la migrazione di un progetto dal formato di gestione packages.config al formato PackageReference .

Vantaggi dell'uso di PackageReference

• Gestire tutte le dipendenze del progetto in un'unica posizione: analogamente ai riferimenti di progetto e agli assembly, i riferimenti ai pacchetti NuGet (usando il PackageReference nodo) vengono gestiti direttamente all'interno dei file di progetto anziché usare un file di packages.config separato.
• Visualizzazione non ordinata delle dipendenze di primo livello: a differenza di packages.config, PackageReference elenca solo i pacchetti NuGet installati direttamente nel progetto. Di conseguenza, l'interfaccia utente di Gestione pacchetti NuGet e il file di progetto non sono disordinati con dipendenze di livello inferiore.
• Miglioramenti delle prestazioni: quando si usa PackageReference, i pacchetti vengono mantenuti nella cartella global-packages (come descritto in Gestione dei pacchetti globali e delle cartelle della cache anziché in una packages cartella all'interno della soluzione). Di conseguenza, PackageReference esegue prestazioni più veloci e consuma meno spazio su disco.
• Controllo corretto sulle dipendenze e sul flusso di contenuto: l'uso delle funzionalità esistenti di MSBuild consente di fare riferimento condizionalmente a un pacchetto NuGet e di scegliere i riferimenti ai pacchetti per framework di destinazione, configurazione, piattaforma o altri pivot.

Limitazioni

• PackageReference NuGet non è disponibile in Visual Studio 2015 e versioni precedenti. I progetti migrati possono essere aperti solo in Visual Studio 2017 e versioni successive.
• La migrazione non è attualmente disponibile per i progetti C++ e ASP.NET.
• Alcuni pacchetti potrebbero non essere completamente compatibili con PackageReference. Per altre informazioni, vedere Problemi di compatibilità dei pacchetti.

Esistono inoltre alcune differenze nel funzionamento di PackageReferences rispetto a packages.config. Ad esempio, i vincoli per le versioni di aggiornamento non sono supportati da PackageReference, ma PackageReference aggiunge il supporto per le versioni mobili.

Problemi noti

1. L'opzione Migrate packages.config to PackageReference... non è disponibile nel menu di scelta rapida del clic con il pulsante destro del mouse

Problema

Quando un progetto viene aperto per la prima volta, NuGet potrebbe non aver inizializzato fino a quando non viene eseguita un'operazione NuGet. In questo modo l'opzione di migrazione non viene visualizzata nel menu di scelta rapida del pulsante destro del mouse su packages.config o References.

Soluzione

Eseguire una delle azioni NuGet seguenti:

• Aprire l'interfaccia utente di Gestione pacchetti - Fare clic con il pulsante destro del mouse su References e selezionare Manage NuGet Packages...
• Aprire la console di Gestione pacchetti - Da Tools > NuGet Package Manager, selezionare Package Manager Console
• Eseguire il ripristino nuGet: fare clic con il pulsante destro del mouse sul nodo della soluzione in Esplora soluzioni e selezionare Restore NuGet Packages
• Compilare il progetto che attiva anche il ripristino NuGet

A questo momento dovrebbe essere possibile visualizzare l'opzione di migrazione. Si noti che questa opzione non è supportata e non verrà visualizzata per i tipi di progetto ASP.NET e C++.

Passaggi per la migrazione

1. Aprire una soluzione contenente il progetto usando packages.config.

2. In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo Riferimenti o sul packages.config file e scegliere Esegui migrazione packages.config a PackageReference....

3. La migrazione analizza i riferimenti al pacchetto NuGet del progetto e tenta di classificarli in dipendenze di primo livello (pacchetti NuGet installati direttamente) e dipendenze transitive (pacchetti installati come dipendenze dei pacchetti di primo livello).

   Annotazioni

   PackageReference supporta il ripristino transitivo dei pacchetti e risolve le dipendenze in modo dinamico, ovvero le dipendenze transitive non devono essere installate in modo esplicito.

4. (Facoltativo) È possibile scegliere di considerare un pacchetto NuGet classificato come dipendenza transitiva come dipendenza di primo livello selezionando l'opzione Di primo livello per il pacchetto. Questa opzione viene impostata automaticamente per i pacchetti contenenti asset che non fluiscono in modo transitivo (quelli nelle cartelle build, buildCrossTargeting, contentFiles o analyzers) e quelli contrassegnati come dipendenza di sviluppo (developmentDependency = "true").

5. Esaminare eventuali problemi di compatibilità dei pacchetti.

6. Selezionare OK per avviare la migrazione.

7. Alla fine della migrazione, Visual Studio fornisce un report con un percorso al backup, l'elenco dei pacchetti installati (dipendenze di primo livello), un elenco di pacchetti a cui viene fatto riferimento come dipendenze transitive e un elenco di problemi di compatibilità identificati all'inizio della migrazione. Il report viene salvato nella cartella di backup.

8. Verificare che la soluzione venga compilata ed eseguita. In caso di problemi, segnalare un problema in GitHub.

Come ripristinare il file packages.config

1. Chiudere il progetto migrato.

2. Copiare il file di progetto e packages.config dal backup (solitamente <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) alla cartella del progetto. Eliminare la cartella obj, se presente nella directory radice del progetto.

3. Aprire il progetto.

4. Aprire la Console di Gestione pacchetti usando il comando del menu Strumenti NuGet Package Manager Console di Gestione pacchetti.

5. Eseguire il comando seguente nella console:

   update-package -reinstall
   

Creare un pacchetto dopo la migrazione

Al termine della migrazione, è consigliabile copiare i metadati del pacchetto da un .nuspec file alle proprietà di MSBuild e quindi usare msbuild -t:pack per creare il pacchetto. Se si usa Visual Studio 2022 o versioni precedenti, sarà necessario installare anche il pacchetto NuGet.Build.Tasks.Pack. Da Visual Studio 2026, pack è integrato in MSBuild.

Problemi di compatibilità dei pacchetti

Alcuni aspetti supportati in packages.config non sono supportati in PackageReference. Il migratore analizza e rileva tali problemi. Qualsiasi pacchetto con uno o più dei problemi seguenti potrebbe non comportarsi come previsto dopo la migrazione.

"install.ps1" i script vengono ignorati quando il pacchetto viene installato dopo la migrazione

• Descrizione: con PackageReference, install.ps1 e uninstall.ps1 script di PowerShell non vengono eseguiti durante l'installazione o la disinstallazione di un pacchetto.

• Potenziale impatto: i pacchetti che dipendono da questi script per configurare un comportamento nel progetto di destinazione potrebbero non funzionare come previsto.

Gli asset "content" non sono disponibili quando il pacchetto viene installato dopo la migrazione

• Descrizione: gli asset nella cartella di content un pacchetto non sono supportati con PackageReference e vengono ignorati. PackageReference aggiunge il supporto per consentire a contentFiles un miglior supporto transitivo e contenuti condivisi.

• Potenziale impatto: gli asset in content non vengono copiati nel progetto e nel codice del progetto che dipende dalla presenza di tali asset richiede il refactoring.

Le trasformazioni XDT non vengono applicate quando il pacchetto viene installato dopo l'aggiornamento

• Descrizione: le trasformazioni XDT non sono supportate con PackageReference e .xdt i file vengono ignorati durante l'installazione o la disinstallazione di un pacchetto.

• Potenziale impatto: le trasformazioni XDT non vengono applicate ad alcun file XML di progetto, in genere web.config.install.xdt e web.config.uninstall.xdt, il che significa che il file del web.config progetto non viene aggiornato quando il pacchetto viene installato o disinstallato.

Gli assembly nella radice lib vengono ignorati quando il pacchetto viene installato dopo la migrazione

• Descrizione: con PackageReference, gli assembly presenti nella radice della cartella senza una sottocartella specifica del framework di lib destinazione vengono ignorati. NuGet cerca una sottocartella che corrisponda al moniker del framework di destinazione (TFM) associato al framework target del progetto e installa i componenti corrispondenti nel progetto.

• Potenziale impatto: i pacchetti che non hanno una sottocartella corrispondente al moniker del framework di destinazione (TFM) corrispondente al framework di destinazione del progetto potrebbero non comportarsi come previsto dopo la transizione o l'installazione non riuscita durante la migrazione.

È stato rilevato un problema? Segnalalo!

Se si verifica un problema con l'esperienza di migrazione, segnalare un problema nel repository GitHub NuGet.