Migrieren von „packages.config“ zu PackageReferenceMigrate from packages.config to PackageReference

Visual Studio 2017 Version 15.7 und höher unterstützt die Migration eines Projekts vom Verwaltungsformat packages.config zum Format PackageReference.Visual Studio 2017 Version 15.7 and later supports migrating a project from the packages.config management format to the PackageReference format.

Vorteile der Verwendung von PackageReferenceBenefits of using PackageReference

  • Verwalten aller Projektabhängigkeiten an einem zentralen Ort : Ebenso wie Verweise zwischen Projekten und Assemblyverweise werden NuGet-Paketverweise (über den Knoten PackageReference) direkt in Projektdateien verwaltet, nicht mithilfe einer separaten packages.config-Datei.Manage all project dependencies in one place : Just like project to project references and assembly references, NuGet package references (using the PackageReference node) are managed directly within project files rather than using a separate packages.config file.
  • Ü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.Uncluttered view of top-level dependencies : Unlike packages.config, PackageReference lists only those NuGet packages you directly installed in the project. Daher werden die Benutzeroberfläche des NuGet-Paket-Managers und die Projektdatei nicht mit untergeordneten Abhängigkeiten überladen.As a result, the NuGet Package Manager UI and the project file aren't cluttered with down-level dependencies.
  • 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.Performance improvements : When using PackageReference, packages are maintained in the global-packages folder (as described on Managing the global packages and cache folders rather than in a packages folder within the solution. Aus diesem Grund ist PackageReference schneller und beansprucht weniger Speicherplatz.As a result, PackageReference performs faster and consumes less disk space.
  • Präzise 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 Aspekten auswählen.Fine control over dependencies and content flow : Using the existing features of MSBuild allows you to conditionally reference a NuGet package and choose package references per target framework, configuration, platform, or other pivots.
  • PackageReference befindet sich in der aktiven Entwicklung : Informationen dazu finden Sie unter PackageReference-Issues auf GitHub.PackageReference is under active development : See PackageReference issues on GitHub. „packages.config“ befindet sich nicht mehr in der aktiven Entwicklung.packages.config is no longer under active development.

EinschränkungenLimitations

  • NuGet PackageReference ist in Visual Studio 2015 und früheren Versionen nicht verfügbar.NuGet PackageReference is not available in Visual Studio 2015 and earlier. Migrierte Projekte können nur in Visual Studio 2017 und höher geöffnet werden.Migrated projects can be opened only in Visual Studio 2017 and later.
  • Für C++- und ASP.NET-Projekte ist momentan keine Migration verfügbar.Migration is not currently available for C++ and ASP.NET projects.
  • Einige Pakete sind möglicherweise nicht vollständig kompatibel mit PackageReference.Some packages may not be fully compatible with PackageReference. Weitere Informationen finden Sie unter Probleme mit der Paketkompatibilität.For more information, see package compatibility issues.

Außerdem gibt es einige Unterschiede bei der Funktionsweise zwischen PackageReferences und packages.config. Die Einschränkung von Upgradeversionen wird beispielsweise von PackageReference nicht unterstützt, es wird vielmehr eine Unterstützung für unverankerte Versionen hinzugefügt.In addition, there are some differences in how PackageReferences work compared to packages.config. For example - constraining upgrade versions is not supprted by PackageReference but add support for Floating Versions.

Bekannte ProblemeKnown Issues

  1. Die Option Migrate packages.config to PackageReference... ist nicht im Kontextmenü (Rechtsklick) verfügbar.The Migrate packages.config to PackageReference... option is not available in the right-click context menu

ProblemIssue

Wenn ein Projekt zum ersten Mal geöffnet wird, kann es sein, dass NuGet erst mit dem ersten NuGet-Vorgang gestartet wird.When a project is first opened, NuGet may not have initialized until a NuGet operation is performed. Deshalb wird die Option zur Migration nicht im Kontextmenü (Rechtsklick) von packages.config oder References angezeigt.This causes the migration option to not show up in the right-click context menu on packages.config or References.

ProblemumgehungWorkaround

Führen Sie eine der folgenden NuGet-Aktionen durch:Perform any one of the following NuGet actions:

  • Öffnen Sie die Benutzeroberfläche des Paket-Managers. Klicken Sie mit der rechten Maustaste auf References, und wählen Sie Manage NuGet Packages....Open the Package Manager UI - Right-click on References and select Manage NuGet Packages...
  • Öffnen Sie die Paket-Manager-Konsole. Klicken Sie unter Tools > NuGet Package Manager auf Package Manager Console.Open the Package Manager Console - From Tools > NuGet Package Manager, select 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.Run NuGet restore - Right-click on the solution node in the Solution Explorer and select Restore NuGet Packages
  • Erstellen Sie ein Projekt. Dadurch wird die Wiederherstellung von NuGet auch ausgelöst.Build the project which also triggers NuGet restore

Jetzt sollten Sie die Option zur Migration sehen.You should now be able to see the migration option. 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.Note that this option is not supported and will not show up for ASP.NET and C++ project types.

Schritte bei der MigrationMigration steps

Hinweis

Vor Beginn der Migration erstellt Visual Studio eine Sicherung des Projekts, sodass Sie ggf. ein Rollback zu „packages.config“ ausführen können.Before migration begins, Visual Studio creates a backup of the project to allow you to roll back to packages.config if necessary.

  1. Öffnen Sie eine Projektmappe mit einem Projekt, das packages.config verwendet.Open a solution containing project using packages.config.

  2. 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.In Solution Explorer , right-click on the References node or the packages.config file and select Migrate packages.config to PackageReference....

  3. 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.The migrator analyzes the project's NuGet package references and attempts to categorize them into Top-level dependencies (NuGet packages that you installed directly) and Transitive dependencies (packages that were installed as dependencies of top-level packages).

    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.PackageReference supports transitive package restore and resolves dependencies dynamically, meaning that transitive dependencies need not be installed explicitly.

  4. (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.(Optional) You may choose to treat a NuGet package classified as a transitive dependency as a top-level dependency by selecting the Top-Level option for the package. 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.This option is automatically set for packages containing assets that do not flow transitively (those in the build, buildCrossTargeting, contentFiles, or analyzers folders) and those marked as a development dependency (developmentDependency = "true").

  5. Überprüfen Sie alle Probleme mit der Paketkompatibilität.Review any package compatibility issues.

  6. Wählen Sie OK aus, um die Migration zu starten.Select OK to begin the migration.

  7. 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.At the end of the migration, Visual Studio provides a report with a path to the backup, the list of installed packages (top-level dependencies), a list of packages referenced as transitive dependencies, and a list of compatibility issues identified at the start of migration. Der Bericht wird im Sicherungsordner gespeichert.The report is saved to the backup folder.

  8. Überprüfen Sie, ob die Projektmappe erstellt und ausgeführt werden kann.Validate that the solution builds and runs. Wenn Probleme auftreten, eröffnen Sie ein Issue auf GitHub.If you encounter problems, file an issue on GitHub.

Ausführen eines Rollbacks zu „packages.config“How to roll back to packages.config

  1. Schließen Sie das migrierte Projekt.Close the migrated project.

  2. Kopieren Sie die Projektdatei und die packages.config-Datei aus der Sicherung (üblicherweise <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) in den Projektordner.Copy the project file and packages.config from the backup (typically <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) to the project folder. Löschen Sie den Ordner „obj“ aus dem Stammverzeichnis des Projekts, sofern er vorhanden ist.Delete the obj folder if it exists in the project root directory.

  3. Öffnen Sie das Projekt.Open the project.

  4. Öffnen Sie die Paket-Manager-Konsole mit dem Menübefehl Extras > NuGet-Paket-Manager > Paket-Manager-Konsole.Open the Package Manager Console using the Tools > NuGet Package Manager > Package Manager Console menu command.

  5. Führen Sie in der Konsole den folgenden Befehl aus:Run the following command in the Console:

    update-package -reinstall
    

Erstellen eines Pakets nach der MigrationCreate a package after 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.Once the migration is complete, we recommend that you add a reference to the nuget.build.tasks.pack nuget package, and then use msbuild -t:pack to create the package. Sie können zwar in einigen Szenarien dotnet.exe pack anstelle von msbuild -t:pack verwenden, dies wird jedoch nicht empfohlen.Although in some scenarios you could use dotnet.exe pack instead of msbuild -t:pack, it is not recommended.

Probleme mit der PaketkompatibilitätPackage compatibility issues

Einige Aspekte, die in „packages.config“ unterstützt wurden, werden in PackageReference nicht unterstützt.Some aspects that were supported in packages.config are not supported in PackageReference. Die Migrationsfunktion analysiert und erkennt solche Probleme.The migrator analyzes and detects such issues. Ein Paket, das mindestens eins der folgenden Probleme aufweist, verhält sich nach der Migration möglicherweise nicht erwartungsgemäß.Any package that has one or more of the following issues may not behave as expected after the migration.

install.ps1-Skripts werden ignoriert, wenn das Paket nach der Migration installiert wird."install.ps1" scripts are ignored when the package is installed after the migration

BeschreibungDescription Bei Verwendung von PackageReference werden die PowerShell-Skripts „install.ps1“ und „uninstall.ps1“ beim Installieren oder Deinstallieren eines Pakets nicht ausgeführt.With PackageReference, install.ps1 and uninstall.ps1 PowerShell scripts are not executed while installing or uninstalling a package.
Mögliche AuswirkungPotential impact Pakete, die von diesen Skripts abhängig sind, um ein bestimmtes Verhalten im Zielprojekt zu konfigurieren, funktionieren möglicherweise nicht wie erwartet.Packages that depend on these scripts to configure some behavior in the destination project might not work as expected.

Objekte im Ordner „content“ sind nicht verfügbar, wenn das Paket nach der Migration installiert wird."content" assets are not available when the package is installed after the migration

BeschreibungDescription Objekte im Ordner content eines Pakets werden von PackageReference nicht unterstützt und daher ignoriert.Assets in a package's content folder are not supported with PackageReference and are ignored. PackageReference fügt Unterstützung für contentFiles hinzu, um transitive Abhängigkeiten und freigegebene Inhalte besser zu unterstützen.PackageReference adds support for contentFiles to have better transitive support and shared content.
Mögliche AuswirkungPotential impact Objekte in content werden nicht in das Projekt kopiert, und für Projektcode, der von solchen Objekten abhängig ist, ist ein Refactoring erforderlich.Assets in content are not copied into the project and project code that depends on the presence of those assets requires refactoring.

XDT-Transformationen werden nicht angewendet, wenn das Paket nach dem Upgrade installiert wird.XDT transforms are not applied when the package is installed after the upgrade

BeschreibungDescription XDT-Transformationen werden von PackageReference nicht unterstützt, und .xdt-Dateien werden beim Installieren oder Deinstallieren eines Pakets ignoriert.XDT transforms are not supported with PackageReference and .xdt files are ignored when installing or uninstalling a package.
Mögliche AuswirkungPotential impact XDT-Transformationen werden nicht auf XML-Projektdateien angewendet – zumeist web.config.install.xdt und web.config.uninstall.xdt. Daher wird die web.config-Datei des Projekts nicht aktualisiert, wenn das Paket installiert oder deinstalliert wird.XDT transforms are not applied to any project XML files, most commonly, web.config.install.xdt and web.config.uninstall.xdt, which means the project's web.config file is not updated when the package is installed or uninstalled.

Assemblys im lib-Stammverzeichnis werden ignoriert, wenn das Paket nach der Migration installiert wird.Assemblies in the lib root are ignored when the package is installed after the migration

BeschreibungDescription PackageReference ignoriert Assemblys, die ohne zielframeworkspezifischen Unterordner im Stammverzeichnis des lib-Ordners vorhanden sind.With PackageReference, assemblies present at the root of lib folder without a target framework specific sub-folder are ignored. NuGet sucht nach einem Unterordner, der dem Zielframeworkmoniker (Target Framework Moniker, TFM) des Zielframeworks des Projekts entspricht, und installiert die entsprechenden Assemblys im Projekt.NuGet looks for a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework and installs the matching assemblies into the project.
Mögliche AuswirkungPotential impact 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.Packages that do not have a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework may not behave as expected after the transition or fail installation during the migration

Haben Sie ein Problem gefunden?Found an issue? Melden Sie es.Report it!

Wenn während der Migration ein Problem auftritt, eröffnen Sie ein Issue im NuGet-GitHub-Repository.If you run into a problem with the migration experience, please file an issue on the NuGet GitHub repository.