Migrace z packages.config na PackageReference

Článek
10/18/2023

Visual Studio 2017 verze 15.7 a novější podporuje migraci projektu z formátu packages.config management do formátu PackageReference .

Výhody používání PackageReference

Spravujte všechny závislosti projektu na jednom místě: Stejně jako odkazy na projekt a odkazy na sestavení se odkazy na balíčky NuGet (pomocí PackageReference uzlu) spravují přímo v souborech projektu místo použití samostatného souboru packages.config.
Nezařazené zobrazení závislostí nejvyšší úrovně: Na rozdíl od packages.config obsahuje PackageReference seznam pouze těch balíčků NuGet, které jste přímo nainstalovali v projektu. Výsledkem je, že uživatelské rozhraní NuGet Správce balíčků a soubor projektu nejsou nepřehledné se závislostmi nižší úrovně.
Vylepšení výkonu: Při použití PackageReference se balíčky uchovávají ve složce globálních balíčků (jak je popsáno při správě globálních balíčků a složek mezipaměti, nikoli ve packages složce v rámci řešení. V důsledku toho PackageReference funguje rychleji a spotřebovává méně místa na disku.
Přesnou kontrolu nad závislostmi a tokem obsahu: Použití existujících funkcí nástroje MSBuild umožňuje podmíněně odkazovat na balíček NuGet a zvolit odkazy na balíčky na každou cílovou architekturu, konfiguraci, platformu nebo jiné pivoty.

Omezení

Balíček NuGet není v sadě Visual Studio 2015 a starší k dispozici. Migrované projekty je možné otevřít jenom v sadě Visual Studio 2017 a novějších verzích.
Migrace v současné době není k dispozici pro projekty C++ a ASP.NET.
Některé balíčky nemusí být plně kompatibilní s PackageReference. Další informace najdete v tématu Problémy s kompatibilitou balíčků.

Kromě toho existují určité rozdíly v tom, jak PackageReferences fungují v porovnání s packages.config. PackageReference například nepodporuje omezení verzí upgradu, ale PackageReference přidává podporu pro plovoucí verze.

Známé problémy

Možnost Migrate packages.config to PackageReference... není dostupná v místní nabídce po kliknutí pravým tlačítkem myši.

Problém

Při prvním otevření projektu nemusí být NuGet inicializován, dokud se neprovede operace NuGet. To způsobí, že se možnost migrace nezobrazí v místní nabídce nebo v místní nabídce po kliknutí pravým tlačítkem myši packages.configReferences.

Alternativní řešení

Proveďte některou z následujících akcí NuGet:

Otevřete uživatelské rozhraní Správce balíčků – klikněte pravým tlačítkem a References vyberteManage NuGet Packages...
Otevřete konzolu Správce balíčků - From Tools > NuGet Package Manager, vybertePackage Manager Console
Spusťte obnovení NuGet – Klikněte pravým tlačítkem na uzel řešení v Průzkumník řešení a vyberteRestore NuGet Packages
Sestavení projektu, který také aktivuje obnovení NuGet

Teď byste měli vidět možnost migrace. Upozorňujeme, že tato možnost není podporovaná a nezobrazí se pro typy projektů ASP.NET a C++.

Kroky migrace

Poznámka:

Před zahájením migrace sada Visual Studio vytvoří zálohu projektu, abyste v případě potřeby mohli vrátit zpět na packages.config .

Otevřete řešení obsahující projekt pomocí packages.config.
V Průzkumník řešení klikněte pravým tlačítkem myši na uzel Reference nebo soubor packages.config a vyberte Migrate packages.config to PackageReference....
Nástroj pro migraci analyzuje odkazy na balíčky NuGet projektu a pokusí se je zařadit do závislostí nejvyšší úrovně (balíčky NuGet, které jste nainstalovali přímo) a tranzitivní závislosti (balíčky nainstalované jako závislosti balíčků nejvyšší úrovně).

Poznámka:

PackageReference podporuje přechodné obnovení balíčků a dynamicky řeší závislosti, což znamená, že přechodné závislosti není nutné explicitně instalovat.
(Volitelné) Balíček NuGet klasifikovaný jako tranzitivní závislost můžete považovat za závislost nejvyšší úrovně výběrem možnosti Nejvyšší úroveň balíčku. Tato možnost je automaticky nastavena pro balíčky obsahující prostředky, které neprotékají tranzitivně (ty v buildbuildCrossTargeting, , contentFilesnebo analyzers složek) a ty, které jsou označené jako vývojová závislost (developmentDependency = "true").
Zkontrolujte všechny problémy s kompatibilitou balíčků.
Pokud chcete zahájit migraci, vyberte OK .
Na konci migrace sada Visual Studio poskytuje sestavu s cestou k zálohování, seznam nainstalovaných balíčků (závislosti nejvyšší úrovně), seznam balíčků odkazovaných na přechodné závislosti a seznam problémů s kompatibilitou identifikovaných na začátku migrace. Sestava se uloží do záložní složky.
Ověřte, že se řešení sestaví a spustí. Pokud narazíte na problémy, zapište problém na GitHubu.

Postup vrácení zpět na packages.config

Zavřete migrovaný projekt.
Zkopírujte soubor projektu a packages.config ze zálohy (obvykle <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) do složky projektu. Odstraňte složku obj, pokud existuje v kořenovém adresáři projektu.
Otevřete projekt.
Otevřete konzolu Správce balíčků pomocí příkazu nabídky Nástroje > NuGet Správce balíčků > Správce balíčků konzoly.
V konzole spusťte následující příkaz:
```
update-package -reinstall
```

Vytvoření balíčku po migraci

Po dokončení migrace doporučujeme přidat odkaz na balíček nuget.build.tasks.pack nuget a pak balíček vytvořit pomocí msbuild -t:pack . I když v některých scénářích byste místo nich mohli použít dotnet.exe packmsbuild -t:pack, nedoporučuje se.

Problémy s kompatibilitou balíčků

Některé aspekty podporované v packages.config nejsou v PackageReference podporované. Migrace tyto problémy analyzuje a detekuje. Každý balíček, který má jeden nebo více následujících problémů, se po migraci nemusí chovat podle očekávání.

Skripty install.ps1 se při instalaci balíčku po migraci ignorují.

Popis: Při instalaci nebo odinstalaci balíčku se nespustí skripty PowerShellu install.ps1 a uninstall.ps1.
Potenciální dopad: Balíčky, které závisí na těchto skriptech a konfigurují určité chování v cílovém projektu, nemusí fungovat podle očekávání.

Prostředky "obsahu" nejsou k dispozici, pokud je balíček nainstalován po migraci.

Popis: Prostředky ve složce balíčku content nejsou podporovány packageReference a jsou ignorovány. PackageReference přidává podporu, contentFiles aby měla lepší tranzitivní podporu a sdílený obsah.
Potenciální dopad: Prostředky se content nekopírují do projektu a kódu projektu, které závisí na přítomnosti těchto prostředků, vyžadují refaktoring.

Transformace XDT nejsou použity při instalaci balíčku po upgradu.

Popis: Transformace XDT nejsou podporovány u PackageReference a .xdt soubory se při instalaci nebo odinstalaci balíčku ignorují.
Potenciální dopad: Transformace XDT nejsou použity na žádné soubory XML projektu, nejčastěji a web.config.uninstall.xdt, což znamená, web.config.install.xdt že soubor projektu web.config se při instalaci nebo odinstalaci balíčku neaktualizuje.

Sestavení v kořenovém adresáři knihovny lib se při instalaci balíčku po migraci ignorují.

Popis: U PackageReference jsou sestavení přítomná v kořenové složce lib složky bez podsložky specifické pro cílovou architekturu ignorována. NuGet hledá podsložku odpovídající monikeru cílového rozhraní (TFM) odpovídající cílovému rozhraní projektu a nainstaluje odpovídající sestavení do projektu.
Potenciální dopad: Balíčky, které nemají podsložku odpovídající monikeru cílového rozhraní (TFM) odpovídající cílovému rozhraní projektu, se nemusí chovat podle očekávání po přechodu nebo selhání instalace během migrace.

Našli jste problém? Nahlašte ho!

Pokud narazíte na problém s prostředím migrace, vytvořte problém v úložišti GitHub NuGet.