Migrasi dari packages.config ke PackageReference

Artikel
04/18/2023

Visual Studio 2017 Versi 15.7 dan yang lebih baru mendukung migrasi proyek dari format manajemen packages.config ke format PackageReference .

Manfaat menggunakan PackageReference

Mengelola semua dependensi proyek di satu tempat: Sama seperti referensi proyek ke referensi proyek dan referensi perakitan, referensi paket NuGet (menggunakan simpul PackageReference ) dikelola langsung dalam file proyek daripada menggunakan file packages.config terpisah.
Tampilan dependensi tingkat atas yang tidak berantakan: Tidak seperti packages.config, PackageReference hanya mencantumkan paket NuGet yang langsung Anda instal dalam proyek. Akibatnya, UI Manajer Paket NuGet dan file proyek tidak berantakan dengan dependensi tingkat bawah.
Peningkatan performa: Saat menggunakan PackageReference, paket dipertahankan di folder paket global (seperti yang dijelaskan pada Mengelola paket global dan folder cache daripada dalam folder dalam packages solusi. Akibatnya, PackageReference berkinerja lebih cepat dan mengonsumsi lebih sedikit ruang disk.
Kontrol halus atas dependensi dan alur konten: Menggunakan fitur MSBuild yang ada memungkinkan Anda mereferensikan paket NuGet secara kondisional dan memilih referensi paket per kerangka kerja target, konfigurasi, platform, atau pivot lainnya.

Batasan

NuGet PackageReference tidak tersedia di Visual Studio 2015 dan yang lebih lama. Proyek yang dimigrasikan hanya dapat dibuka di Visual Studio 2017 dan yang lebih baru.
Migrasi saat ini tidak tersedia untuk proyek C++ dan ASP.NET.
Beberapa paket mungkin tidak sepenuhnya kompatibel dengan PackageReference. Untuk informasi selengkapnya, lihat masalah kompatibilitas paket.

Selain itu, ada beberapa perbedaan dalam cara kerja PackageReferences dibandingkan dengan packages.config. Misalnya, Batasan pada versi peningkatan tidak didukung oleh PackageReference, tetapi PackageReference menambahkan dukungan untuk Versi Floating.

Masalah Umum

Opsi Migrate packages.config to PackageReference... tidak tersedia di menu konteks klik kanan

Masalah

Ketika proyek pertama kali dibuka, NuGet mungkin belum diinisialisasi hingga operasi NuGet dilakukan. Ini menyebabkan opsi migrasi tidak muncul di menu konteks klik kanan pada packages.config atau References.

Solusi Sementara

Lakukan salah satu tindakan NuGet berikut:

Buka UI Manajer Paket - Klik kanan References dan pilih Manage NuGet Packages...
Buka Konsol Manajer Paket - Dari Tools > NuGet Package Manager, pilih Package Manager Console
Jalankan pemulihan NuGet - Klik kanan pada simpul solusi di Penjelajah Solusi dan pilihRestore NuGet Packages
Membangun proyek yang juga memicu pemulihan NuGet

Anda sekarang dapat melihat opsi migrasi. Perhatikan bahwa opsi ini tidak didukung dan tidak akan muncul untuk jenis proyek ASP.NET dan C++.

Langkah migrasi

Catatan

Sebelum migrasi dimulai, Visual Studio membuat cadangan proyek untuk memungkinkan Anda kembali ke packages.config jika perlu.

Buka solusi yang berisi proyek menggunakan packages.config.
Di Penjelajah Solusi, klik kanan pada simpul Referensi atau packages.config file dan pilih Migrasikan packages.config ke PackageReference....
Migrasi menganalisis referensi paket NuGet proyek dan mencoba mengategorikannya ke dalam dependensi tingkat atas (paket NuGet yang Anda instal secara langsung) dan dependensi Transitif (paket yang diinstal sebagai dependensi paket tingkat atas).

Catatan

PackageReference mendukung pemulihan paket transitif dan menyelesaikan dependensi secara dinamis, yang berarti bahwa dependensi transitif tidak perlu diinstal secara eksplisit.
(Opsional) Anda dapat memilih untuk memperlakukan paket NuGet yang diklasifikasikan sebagai dependensi transitif sebagai dependensi tingkat atas dengan memilih opsi Tingkat Atas untuk paket. Opsi ini secara otomatis diatur untuk paket yang berisi aset yang tidak mengalir secara transitif (yang ada di buildfolder , , buildCrossTargetingcontentFiles, atau analyzers ) dan yang ditandai sebagai dependensi pengembangan (developmentDependency = "true").
Tinjau masalah kompatibilitas paket apa pun.
Pilih OK untuk memulai migrasi.
Di akhir migrasi, Visual Studio menyediakan laporan dengan jalur ke cadangan, daftar paket yang diinstal (dependensi tingkat atas), daftar paket yang direferensikan sebagai dependensi transitif, dan daftar masalah kompatibilitas yang diidentifikasi pada awal migrasi. Laporan disimpan ke folder cadangan.
Validasi bahwa solusi dibangun dan dijalankan. Jika Anda mengalami masalah, ajukan masalah di GitHub.

Cara menggulung balik ke packages.config

Tutup proyek yang dimigrasikan.
Salin file proyek dan packages.config dari cadangan (biasanya <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) ke folder proyek. Hapus folder obj jika ada di direktori akar proyek.
Buka proyek.
Buka Konsol Manajer Paket menggunakan perintah menu Konsol Manajer Paket Manajer > Paket Alat > NuGet.
Jalankan perintah berikut di Konsol:
```
update-package -reinstall
```

Membuat paket setelah migrasi

Setelah migrasi selesai, kami sarankan Anda menambahkan referensi ke paket nuget.build.tasks.pack nuget, lalu gunakan msbuild -t:pack untuk membuat paket. Meskipun dalam beberapa skenario Anda dapat menggunakan dotnet.exe pack alih-alih msbuild -t:pack, tidak disarankan.

Masalah kompatibilitas paket

Beberapa aspek yang didukung dalam packages.config tidak didukung di PackageReference. Migrasi menganalisis dan mendeteksi masalah tersebut. Paket apa pun yang memiliki satu atau beberapa masalah berikut mungkin tidak beresiko seperti yang diharapkan setelah migrasi.

Skrip "install.ps1" diabaikan saat paket diinstal setelah migrasi

Deskripsi: Dengan PackageReference, skrip PowerShell install.ps1 dan uninstall.ps1 tidak dijalankan saat menginstal atau menghapus instalasi paket.
Dampak potensial: Paket yang bergantung pada skrip ini untuk mengonfigurasi beberapa perilaku dalam proyek tujuan mungkin tidak berfungsi seperti yang diharapkan.

Aset "konten" tidak tersedia saat paket diinstal setelah migrasi

Deskripsi: Aset dalam folder paket content tidak didukung dengan PackageReference dan diabaikan. PackageReference menambahkan dukungan untuk contentFiles memiliki dukungan transitif dan konten bersama yang lebih baik.
Dampak potensial: Aset di tidak disalin content ke dalam kode proyek dan proyek yang bergantung pada keberadaan aset tersebut memerlukan pemfaktoran ulang.

Transformasi XDT tidak diterapkan saat paket diinstal setelah peningkatan

Deskripsi: Transformasi XDT tidak didukung dengan PackageReference dan .xdt file diabaikan saat menginstal atau menghapus instalasi paket.
Dampak potensial: Transformasi XDT tidak diterapkan ke file XML proyek apa pun, paling umum, web.config.install.xdt dan web.config.uninstall.xdt, yang berarti file proyek web.config tidak diperbarui saat paket diinstal atau dihapus instalasinya.

Rakitan di akar lib diabaikan ketika paket diinstal setelah migrasi

Deskripsi: Dengan PackageReference, rakitan yang ada di akar lib folder tanpa sub-folder khusus kerangka kerja target diabaikan. NuGet mencari sub-folder yang cocok dengan moniker kerangka kerja target (TFM) yang sesuai dengan kerangka kerja target proyek dan menginstal rakitan yang cocok ke dalam proyek.
Dampak potensial: Paket yang tidak memiliki sub-folder yang cocok dengan moniker kerangka kerja target (TFM) yang sesuai dengan kerangka kerja target proyek mungkin tidak beresiko seperti yang diharapkan setelah transisi atau penginstalan gagal selama migrasi.

Menemukan masalah? Laporkan!

Jika Anda mengalami masalah dengan pengalaman migrasi, silakan ajukan masalah pada repositori NuGet GitHub.

Share via