Migrieren von „packages.config“ zu „PackageReference“

Artikel
03/15/2024

Visual Studio 2017 Version 15.7 und höher unterstützt die Migration eines Projekts vom Verwaltungsformat packages.config zum Format PackageReference.

Vorteile der Verwendung von PackageReference

Verwalten aller Projektabhängigkeiten an zentraler Stelle: Ebenso wie Verweise zwischen Projekten und Assemblyverweise werden NuGet-Paketverweise (über den Knoten PackageReference) direkt in Projektdateien und nicht mithilfe einer separaten Datei „packages.config“ verwaltet.
Übersichtliche Anzeige der Abhängigkeiten der obersten Ebene: Im Gegensatz zu einer packages.config-Datei listet PackageReference nur solche NuGet-Pakete auf, die Sie direkt im Projekt installiert haben. Daher werden die Benutzeroberfläche des NuGet-Paket-Managers und die Projektdatei nicht mit untergeordneten Abhängigkeiten überladen.
Leistungsverbesserungen: Bei Verwendung von PackageReference werden Pakete im Ordner global-packages verwaltet (wie unter Verwalten des Ordners „global-packages“ und des Cacheordners beschrieben), nicht in einem packages-Ordner in der Projektmappe. Aus diesem Grund ist PackageReference schneller und beansprucht weniger Speicherplatz.
Feine Kontrolle über Abhängigkeiten und Inhaltsfluss: Mithilfe der vorhandenen Features von MSBuild können Sie bedingte Verweise für ein NuGet-Paket verwenden und Paketverweise nach Zielframework, Konfiguration, Plattform und anderen Pivotdokumenten auswählen.

Begrenzungen

NuGet PackageReference ist in Visual Studio 2015 und früheren Versionen nicht verfügbar. Migrierte Projekte können nur in Visual Studio 2017 und höher geöffnet werden.
Für C++- und ASP.NET-Projekte ist momentan keine Migration verfügbar.
Einige Pakete sind möglicherweise nicht vollständig kompatibel mit PackageReference. Weitere Informationen finden Sie unter Probleme mit der Paketkompatibilität.

Darüber hinaus gibt es einige Unterschiede in der Funktionsweise von PackageReferences im Vergleich zu packages.config. Beispielsweise werden Einschränkungen für Upgrade-Versionen von PackageReference nicht unterstützt, PackageReference bietet jedoch Unterstützung für unverankerte Versionen.

Bekannte Probleme

Die Option Migrate packages.config to PackageReference... ist nicht im Kontextmenü (Rechtsklick) verfügbar.

Abgang

Wenn ein Projekt zum ersten Mal geöffnet wird, kann es sein, dass NuGet erst mit dem ersten NuGet-Vorgang gestartet wird. Deshalb wird die Option zur Migration nicht im Kontextmenü (Rechtsklick) von packages.config oder References angezeigt.

Problemumgehung

Führen Sie eine der folgenden NuGet-Aktionen durch:

Öffnen Sie die Benutzeroberfläche des Paket-Managers. Klicken Sie mit der rechten Maustaste auf References, und wählen Sie Manage NuGet Packages....
Öffnen Sie die Paket-Manager-Konsole. Klicken Sie unter Tools > NuGet Package Manager auf Package Manager Console.
Stellen Sie NuGet-Pakete wieder her. Klicken Sie dazu im Projektmappen-Explorer mit der rechten Maustaste auf den Projektmappenknoten, und wählen Sie Restore NuGet Packages aus.
Erstellen Sie ein Projekt. Dadurch wird die Wiederherstellung von NuGet auch ausgelöst.

Jetzt sollten Sie die Option zur Migration sehen. Beachten Sie, dass diese Option für ASP.NET- und C++-Projekte nicht unterstützt und auch nach dem Durchführen dieser Schritte nicht angezeigt wird.

Schritte bei der Migration

Hinweis

Vor Beginn der Migration erstellt Visual Studio eine Sicherung des Projekts, sodass Sie ggf. ein Rollback zu „packages.config“ ausführen können.

Öffnen Sie eine Projektmappe mit einem Projekt, das packages.config verwendet.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Knoten Verweise oder die Datei packages.config, und wählen Sie „packages.config“ zu „PackageReference“ migrieren... aus.
Die Migrationsfunktion analysiert die NuGet-Paketverweise des Projekts und versucht, sie in Abhängigkeiten auf oberster Ebene (direkt installierte NuGet-Pakete) und Transitive Abhängigkeiten (Pakete, die als Abhängigkeiten von Paketen der obersten Ebene installiert wurden) zu kategorisieren.

Hinweis

PackageReference unterstützt die Wiederherstellung von transitiven Paketen und löst Abhängigkeiten dynamisch auf. Das bedeutet, dass transitive Abhängigkeiten nicht explizit installiert werden müssen.
(Optional) Sie können ein als transitive Abhängigkeit klassifiziertes NuGet-Paket als Abhängigkeit der obersten Ebene behandeln, indem Sie für dieses Paket die Option Oberste Eben auswählen. Für Pakete mit Objekten, die nicht transitiv übertragen werden (in den Ordnern build, buildCrossTargeting, contentFiles oder analyzers), und für Pakete, die als Entwicklungsabhängigkeit gekennzeichnet sind (developmentDependency = "true"), ist diese Option automatisch festgelegt.
Überprüfen Sie alle Probleme mit der Paketkompatibilität.
Wählen Sie OK aus, um die Migration zu starten.
Am Ende der Migration stellt Visual Studio einen Bericht bereit, der Folgendes enthält: einen Pfad zur Sicherung, die Liste der installierten Pakete (Abhängigkeiten auf oberster Ebene), eine Liste der Pakete, auf die in Form von transitiven Abhängigkeiten verwiesen wird, und eine Liste mit Kompatibilitätsproblemen, die bei Beginn der Migration ermittelt wurden. Der Bericht wird im Sicherungsordner gespeichert.
Überprüfen Sie, ob die Projektmappe erstellt und ausgeführt werden kann. Wenn Probleme auftreten, eröffnen Sie ein Issue auf GitHub.

Ausführen eines Rollbacks zu „packages.config“

Schließen Sie das migrierte Projekt.
Kopieren Sie die Projektdatei und die packages.config-Datei aus der Sicherung (üblicherweise <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) in den Projektordner. Löschen Sie den Ordner „obj“ aus dem Stammverzeichnis des Projekts, sofern er vorhanden ist.
Öffnen Sie das Projekt.
Öffnen Sie die Paket-Manager-Konsole mit dem Menübefehl Extras > NuGet-Paket-Manager > Paket-Manager-Konsole.
Führen Sie in der Konsole den folgenden Befehl aus:
```
update-package -reinstall
```

Erstellen eines Pakets nach der Migration

Sobald die Migration abgeschlossen ist, empfiehlt es sich, einen Verweis auf das NuGet-Paket nuget.build.tasks.pack hinzuzufügen und dann msbuild -t:pack zum Erstellen des Pakets zu verwenden. Sie können zwar in einigen Szenarien dotnet.exe pack anstelle von msbuild -t:pack verwenden, dies wird jedoch nicht empfohlen.

Probleme mit der Paketkompatibilität

Einige Aspekte, die in „packages.config“ unterstützt wurden, werden in PackageReference nicht unterstützt. Die Migrationsfunktion analysiert und erkennt solche Probleme. Ein Paket, das mindestens eins der folgenden Probleme aufweist, verhält sich nach der Migration möglicherweise nicht erwartungsgemäß.

install.ps1-Skripts werden ignoriert, wenn das Paket nach der Migration installiert wird.

Beschreibung: Mit PackageReference, install.ps1 und uninstall.ps1 werden PowerShell-Skripts während der (De-)Installation eines Pakets nicht ausgeführt.
Mögliche Auswirkung: Pakete, die von diesen Skripts abhängig sind, um ein bestimmtes Verhalten im Zielprojekt zu konfigurieren, funktionieren möglicherweise nicht wie erwartet.

Objekte im Ordner „content“ sind nicht verfügbar, wenn das Paket nach der Migration installiert wird.

Beschreibung: Objekte im Ordner content eines Pakets werden von PackageReference nicht unterstützt und daher ignoriert. PackageReference fügt Unterstützung für contentFiles hinzu, um transitive Abhängigkeiten und freigegebene Inhalte besser zu unterstützen.
Mögliche Auswirkung: Objekte in content werden nicht in das Projekt kopiert, und für Projektcode, der von solchen Objekten abhängig ist, ist ein Refactoring erforderlich.

XDT-Transformationen werden nicht angewendet, wenn das Paket nach dem Upgrade installiert wird.

Beschreibung: XDT-Transformationen werden von PackageReference nicht unterstützt, und .xdt-Dateien werden beim Installieren oder Deinstallieren eines Pakets ignoriert.
Mögliche Auswirkung: XDT-Transformationen werden nicht auf XML-Projektdateien angewendet – zumeist web.config.install.xdt und web.config.uninstall.xdt. Daher wird die Datei web.config des Projekts nicht aktualisiert, wenn das Paket installiert oder deinstalliert wird.

Assemblys im lib-Stammverzeichnis werden ignoriert, wenn das Paket nach der Migration installiert wird.

Beschreibung: PackageReference ignoriert Assemblys, die ohne zielframeworkspezifischen Unterordner im Stammverzeichnis des Ordners lib enthalten sind. NuGet sucht nach einem Unterordner, der dem Zielframeworkmoniker (Target Framework Moniker, TFM) des Zielframeworks des Projekts entspricht, und installiert die entsprechenden Assemblys im Projekt.
Mögliche Auswirkung: Pakete, die keinen Unterordner aufweisen, der dem Zielframeworkmoniker des Zielframeworks des Projekts entspricht, verhalten sich nach dem Übergang möglicherweise nicht wie erwartet oder können während der Migration nicht installiert werden.

Haben Sie ein Problem gefunden? Melden Sie es.

Wenn während der Migration ein Problem auftritt, eröffnen Sie ein Issue im NuGet-GitHub-Repository.

Freigeben über