Eseguire la migrazione da packages.config a PackageReference

Articolo
04/18/2023

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 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 ingombri a causa delle 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 offre prestazioni migliori e utilizza 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.

Limiti

NuGet PackageReference 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 del tutto compatibili con PackageReference. Per altre informazioni, vedere i 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

L'opzione Migrate packages.config to PackageReference... non è disponibile nel menu di scelta rapida

Problema

Alla prima apertura di un progetto, NuGet potrebbe non essere inizializzato fino all'esecuzione di un'operazione NuGet. Per questo motivo, l'opzione di migrazione non viene visualizzata nel menu di scelta rapida per packages.config o References.

Soluzione alternativa

Eseguire una delle azioni NuGet seguenti:

Aprire l'interfaccia utente di Gestione pacchetti - fare clic con il pulsante destro del mouse su References e scegliere Manage NuGet Packages...
Aprire la console di Gestione pacchetti - Da Tools > NuGet Package Manager selezionare Package Manager Console
Eseguire un ripristino NuGet - Fare clic con il pulsante destro del mouse sul nodo della soluzione in Esplora soluzioni e scegliere Restore NuGet Packages
Compilare il progetto, ovvero un altro modo per attivare un ripristino NuGet

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

Passaggi per la migrazione

Nota

Prima dell'inizio della migrazione, Visual Studio crea un backup del progetto per consentire di eseguire il rollback a packages.config se necessario.

Aprire una soluzione contenente il progetto con packages.config.
In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo Riferimenti o sul file packages.config e scegliere Esegui la migrazione da packages.config a PackageReference.
L'utilità di migrazione analizza i riferimenti ai pacchetti NuGet del progetto e tenta di categorizzarli in Dipendenze di primo livello (pacchetti NuGet installati direttamente) e Dipendenze transitive (pacchetti installati come dipendenze dei pacchetti di primo livello).

Nota

PackageReference supporta il ripristino transitivo dei pacchetti e risolve le dipendenze in modo dinamico, vale a dire che non è necessario installare in modo esplicito le dipendenze transitive.
(Facoltativo) È possibile scegliere di considerare un pacchetto NuGet classificato come dipendenza transitiva come dipendenza di primo livello selezionando l'opzione Primo livello per il pacchetto. Questa opzione viene impostata automaticamente per i pacchetti contenenti asset che non vengono trasferiti in modo transitivo (ovvero quelli nelle cartelle build, buildCrossTargeting, contentFiles o analyzers) e quelli contrassegnati come dipendenza di sviluppo (developmentDependency = "true").
Esaminare eventuali problemi di compatibilità dei pacchetti.
Selezionare OK per avviare la migrazione.
Al termine della migrazione, Visual Studio fornisce un report con un percorso del backup, l'elenco dei pacchetti installati (dipendenze di primo livello), un elenco di pacchetti a cui si fa riferimento come dipendenze transitive e un elenco dei problemi di compatibilità identificati all'inizio della migrazione. Il report viene salvato nella cartella di backup.
Verificare che la soluzione venga compilata ed eseguita. Se si verificano problemi, registrare un problema in GitHub.

Come eseguire il rollback a packages.config

Chiudere il progetto migrato.
Copiare il file di progetto e packages.config dal backup (in genere <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) nella cartella del progetto. Eliminare la cartella obj se è presente nella directory radice del progetto.
Apri il progetto.
Aprire la console Gestione pacchetti usando il comando di menu Strumenti > NuGet Gestione pacchetti > Gestione pacchetti Console.
Eseguire il comando seguente nella console:
```
update-package -reinstall
```

Creare un pacchetto dopo la migrazione

Al termine della migrazione, è consigliabile aggiungere un riferimento al pacchetto NuGet nuget.build.tasks.pack e quindi usare msbuild -t:pack per creare il pacchetto. Sebbene in alcuni scenari sia possibile usare dotnet.exe pack invece di msbuild -t:pack, non è consigliabile.

Problemi di compatibilità dei pacchetti

Alcuni aspetti supportati in packages.config non sono supportati in PackageReference. L'utilità di migrazione analizza e rileva tali problemi. I pacchetti che presentano uno o più dei problemi seguenti potrebbero presentare comportamenti imprevisti dopo la migrazione.

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

Descrizione: con PackageReference, gli script install.ps1 e uninstall.ps1 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 contentFiles per ottenere supporto transitivo e contenuto condiviso migliori.
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 corrispondente al moniker framework di destinazione (TFM) corrispondente al framework di destinazione del progetto e installa gli assembly 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.

Segnalare i problemi riscontrati.

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