Migrowanie z pliku packages.config do elementu PackageReference

Artykuł
10/18/2023

Program Visual Studio 2017 w wersji 15.7 lub nowszej obsługuje migrowanie projektu z formatu zarządzania packages.config do formatu PackageReference .

Zalety korzystania z funkcji PackageReference

Zarządzaj wszystkimi zależnościami projektu w jednym miejscu: podobnie jak projekt do odwołań do projektu i odwołań do zestawów, odwołania pakietów NuGet (przy użyciu węzła PackageReference ) są zarządzane bezpośrednio w plikach projektu, a nie przy użyciu oddzielnego pliku packages.config.
Widok niecluttered zależności najwyższego poziomu: w przeciwieństwie do packages.config, PackageReference wyświetla tylko te pakiety NuGet zainstalowane bezpośrednio w projekcie. W związku z tym interfejs użytkownika Menedżer pakietów NuGet i plik projektu nie są zaśmiecone zależnościami na poziomie obniżania poziomu.
Ulepszenia wydajności: w przypadku korzystania z funkcji PackageReference pakiety są przechowywane w folderze global-packages (zgodnie z opisem w temacie Zarządzanie pakietami globalnymi i folderami pamięci podręcznej, a nie w packages folderze w rozwiązaniu. W rezultacie narzędzie PackageReference działa szybciej i zużywa mniej miejsca na dysku.
Precyzyjna kontrola nad zależnościami i przepływem zawartości: korzystanie z istniejących funkcji programu MSBuild pozwala warunkowo odwoływać się do pakietu NuGet i wybierać odwołania do pakietów na platformę docelową, konfigurację, platformę lub inne elementy przestawne.

Ograniczenia

Funkcja NuGet PackageReference nie jest dostępna w programie Visual Studio 2015 i starszych wersjach. Migrowane projekty można otwierać tylko w programie Visual Studio 2017 lub nowszym.
Migracja nie jest obecnie dostępna dla projektów C++ i ASP.NET.
Niektóre pakiety mogą nie być w pełni zgodne z funkcją PackageReference. Aby uzyskać więcej informacji, zobacz problemy ze zgodnością pakietów.

Ponadto istnieją pewne różnice w sposobie działania funkcji PackageReferences w porównaniu z pakietami.config. Na przykład ograniczenia dotyczące wersji uaktualnienia nie są obsługiwane przez funkcję PackageReference, ale funkcja PackageReference dodaje obsługę wersji zmiennoprzecinkowych.

Znane problemy

Opcja jest niedostępna Migrate packages.config to PackageReference... w menu kontekstowym kliknij prawym przyciskiem myszy

Problem

Po pierwszym otwarciu projektu pakiet NuGet może nie zostać zainicjowany do momentu wykonania operacji NuGet. Powoduje to, że opcja migracji nie jest wyświetlana w menu kontekstowym prawym przyciskiem myszy w packages.config menu kontekstowym lub References.

Rozwiązanie

Wykonaj jedną z następujących akcji NuGet:

Otwórz interfejs użytkownika Menedżer pakietów — kliknij prawym przyciskiem myszy References i wybierz polecenieManage NuGet Packages...
Otwórz konsolę Menedżer pakietów — z Tools > NuGet Package Managerpozycji wybierz pozycjęPackage Manager Console
Uruchom przywracanie NuGet — kliknij prawym przyciskiem myszy węzeł rozwiązania w Eksplorator rozwiązań i wybierz polecenieRestore NuGet Packages
Kompilowanie projektu, który wyzwala również przywracanie NuGet

Teraz powinna być widoczna opcja migracji. Należy pamiętać, że ta opcja nie jest obsługiwana i nie będzie wyświetlana dla typów projektów ASP.NET i C++.

Kroki migracji

Uwaga

Przed rozpoczęciem migracji program Visual Studio tworzy kopię zapasową projektu, aby w razie potrzeby przywrócić plik packages.config .

Otwórz rozwiązanie zawierające projekt przy użyciu polecenia packages.config.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł Odwołania lub packages.config plik, a następnie wybierz pozycję Migruj pakiety.config do pozycji PackageReference....
Narzędzie migrator analizuje odwołania do pakietu NuGet projektu i próbuje podzielić je na zależności najwyższego poziomu (pakiety NuGet zainstalowane bezpośrednio) i zależności przechodnie (pakiety przejściowe zainstalowane jako zależności pakietów najwyższego poziomu).

Uwaga

Funkcja PackageReference obsługuje przejściowe przywracanie pakietów i dynamicznie rozwiązuje zależności, co oznacza, że zależności przechodnie nie muszą być instalowane jawnie.
(Opcjonalnie) Możesz traktować pakiet NuGet sklasyfikowany jako zależność przechodnia jako zależność najwyższego poziomu, wybierając opcję Najwyższego poziomu dla pakietu. Ta opcja jest automatycznie ustawiana dla pakietów zawierających zasoby, które nie przepływają przechodnio (te w buildfolderach , , buildCrossTargeting, contentFileslub analyzers ) i te oznaczone jako zależność programowa (developmentDependency = "true").
Przejrzyj wszelkie problemy ze zgodnością pakietów.
Wybierz przycisk OK , aby rozpocząć migrację.
Po zakończeniu migracji program Visual Studio udostępnia raport ze ścieżką do kopii zapasowej, listę zainstalowanych pakietów (zależności najwyższego poziomu), listę pakietów, do których odwołuje się zależność przechodnia, oraz listę problemów ze zgodnością zidentyfikowanych na początku migracji. Raport jest zapisywany w folderze kopii zapasowej.
Sprawdź, czy rozwiązanie kompiluje i uruchamia. Jeśli wystąpią problemy, zgłoś problem w usłudze GitHub.

Jak przywrócić plik packages.config

Zamknij zmigrowany projekt.
Skopiuj plik projektu i packages.config z kopii zapasowej (zazwyczaj <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) do folderu projektu. Usuń folder obj, jeśli istnieje w katalogu głównym projektu.
Otwórz projekt.
Otwórz konsolę Menedżer pakietów przy użyciu narzędzia NuGet > Menedżer pakietów > Menedżer pakietów konsoli polecenia.
Uruchom następujące polecenie w konsoli:
```
update-package -reinstall
```

Tworzenie pakietu po migracji

Po zakończeniu migracji zalecamy dodanie odwołania do pakietu nuget.build.tasks.pack nuget, a następnie użycie pakietu msbuild -t:pack . Chociaż w niektórych scenariuszach można użyć dotnet.exe pack zamiast msbuild -t:pack, nie jest to zalecane.

Problemy ze zgodnością pakietów

Niektóre aspekty obsługiwane w pliku packages.config nie są obsługiwane w elemencie PackageReference. Migracja analizuje i wykrywa takie problemy. Każdy pakiet, który ma co najmniej jeden z następujących problemów, może nie zachowywać się zgodnie z oczekiwaniami po migracji.

Skrypty "install.ps1" są ignorowane po zainstalowaniu pakietu po migracji

Opis: W przypadku polecenia PackageReference skrypty install.ps1 i uninstall.ps1 programu PowerShell nie są wykonywane podczas instalowania ani odinstalowywania pakietu.
Potencjalny wpływ: pakiety zależne od tych skryptów w celu skonfigurowania pewnego zachowania w projekcie docelowym mogą nie działać zgodnie z oczekiwaniami.

Zasoby "content" nie są dostępne po zainstalowaniu pakietu po migracji

Opis: Zasoby w folderze pakietu content nie są obsługiwane z funkcją PackageReference i są ignorowane. Funkcja PackageReference dodaje obsługę contentFiles lepszej obsługi przechodniej i udostępnionej zawartości.
Potencjalny wpływ: zasoby w content obiekcie nie są kopiowane do projektu i kodu projektu, który zależy od obecności tych zasobów, wymaga refaktoryzacji.

Przekształcenia XDT nie są stosowane po zainstalowaniu pakietu po uaktualnieniu

Opis: przekształcenia XDT nie są obsługiwane w przypadku funkcji PackageReference i .xdt pliki są ignorowane podczas instalowania lub odinstalowywania pakietu.
Potencjalny wpływ: przekształcenia XDT nie są stosowane do żadnych plików XML projektu, najczęściej i web.config.uninstall.xdt, co oznacza, web.config.install.xdt że plik projektu web.config nie jest aktualizowany podczas instalowania lub odinstalowywania pakietu.

Zestawy w katalogu głównym lib są ignorowane po zainstalowaniu pakietu po migracji

Opis: W przypadku funkcji PackageReference zestawy obecne w folderze głównym folderu bez podfolderu lib specyficznego dla platformy docelowej są ignorowane. NuGet wyszukuje podfolder zgodny z monikerem platformy docelowej (TFM) odpowiadającym strukturze docelowej projektu i instaluje pasujące zestawy do projektu.
Potencjalny wpływ: pakiety, które nie mają podfolderu pasującego do nazwy docelowej platformy docelowej (TFM) odpowiadającej strukturze docelowej projektu, mogą nie zachowywać się zgodnie z oczekiwaniami po przejściu lub nieudanej instalacji podczas migracji.

Znaleziono problem? Zgłoś go!

Jeśli wystąpi problem ze środowiskiem migracji, zgłoś problem w repozytorium NuGet GitHub.