packages.config'dan PackageReference'a geçiş

Visual Studio 2017 Sürüm 15.7 ve üzeri, bir projenin packages.config yönetim biçiminden PackageReference biçimine geçirilmesini destekler.

PackageReference kullanmanın avantajları

• Tüm proje bağımlılıklarını tek bir yerde yönetme: Projeden projeye başvurular ve derleme başvuruları gibi NuGet paket başvuruları da (düğümü kullanarak PackageReference ) ayrı bir packages.config dosyası kullanmak yerine doğrudan proje dosyaları içinde yönetilir.
• Üst düzey bağımlılıkların dağınık görünümü: packages.configaksine PackageReference yalnızca doğrudan projeye yüklediğiniz NuGet paketlerini listeler. Sonuç olarak, NuGet Paket Yöneticisi kullanıcı arabirimi ve proje dosyası alt düzey bağımlılıklarla karmaşık hale gelmez.
• Performans iyileştirmeleri: PackageReference kullanılırken paketler genel paketler klasöründe tutulur (çözüm içindeki bir klasör yerine packages konusunda açıklandığı gibi). Sonuç olarak PackageReference daha hızlı çalışır ve daha az disk alanı kullanır.
• Bağımlılıklar ve içerik akışı üzerinde hassas denetim: MSBuild'in mevcut özelliklerini kullanmak , bir NuGet paketine koşullu olarak başvurmanıza ve hedef çerçeve, yapılandırma, platform veya diğer özetler başına paket başvuruları seçmenize olanak tanır.

Sınırlamalar

• NuGet PackageReference, Visual Studio 2015 ve önceki sürümlerde kullanılamaz. Geçirilen projeler yalnızca Visual Studio 2017 ve sonraki sürümlerde açılabilir.
• Geçiş şu anda C++ ve ASP.NET projelerde kullanılamaz.
• Bazı paketler PackageReference ile tam olarak uyumlu olmayabilir. Daha fazla bilgi için bkz. paket uyumluluğu sorunları.

Ayrıca, PackageReferences'ın çalışma şekliyle packages.configkarşılaştırıldığında bazı farklılıklar vardır. Örneğin, yükseltme sürümlerindeki kısıtlamalar PackageReference tarafından desteklenmez, ancak PackageReference Kayan Sürümler için destek ekler.

Bilinen Sorunlar

1. Sağ Migrate packages.config to PackageReference... tıklama bağlam menüsünde bu seçenek kullanılamaz

Sorun

Bir proje ilk açıldığında, NuGet işlemi gerçekleştirilinceye kadar NuGet başlatılmamış olabilir. Bu durum, packages.config veya References üzerindeki sağ tıklama bağlam menüsünde geçiş seçeneğinin gösterilmemesine neden olur.

Geçici çözüm

Aşağıdaki NuGet eylemlerinden herhangi birini gerçekleştirin:

• Paket Yöneticisi Kullanıcı Arayüzünü açın - References üzerine sağ tıklayın ve Manage NuGet Packages... seçin
• Paket Yöneticisi Konsolu'nu açın - Menüden Tools > NuGet Package Manager, Package Manager Console öğesini seçin
• NuGet geri yükleme işlemini başlatın - Çözüm Gezgini'nde çözüm düğümüne sağ tıklayın ve Restore NuGet Packages
• NuGet geri yüklemesini de tetikleyen projeyi oluşturma

Artık geçiş seçeneğini görebilmeniz gerekir. Bu seçeneğin desteklenmediğini ve ASP.NET ve C++ proje türleri için gösterilmeyeceğini unutmayın.

Göç Adımları

Uyarı

Geçiş başlamadan önce Visual Studio, gerekirse packages.configgeri dönmenizi sağlamak için projenin bir yedeğini oluşturur.

1. packages.config kullanarak proje içeren bir proje çözümü açın.

2. Çözüm Gezgini'ndeBaşvurular düğümüne veya dosyaya packages.config sağ tıklayın ve packages.config PackageReference... öğesine geçir'i seçin.

3. Geçişci, projenin NuGet paket başvurularını analiz eder ve bunları Üst düzey bağımlılıklara (doğrudan yüklediğiniz NuGet paketleri) ve Geçişli bağımlılıklara (üst düzey paketlerin bağımlılıkları olarak yüklenen paketler) kategorilere ayırmaya çalışır.

   Uyarı

   PackageReference geçişli paket geri yüklemesini destekler ve bağımlılıkları dinamik olarak çözer, yani geçişli bağımlılıkların açıkça yüklenmesi gerekmez.

4. (İsteğe bağlı) Geçişli bağımlılık olarak sınıflandırılan bir NuGet paketini, paket için Üst Düzey seçeneğini belirleyerek en üst düzey bağımlılık olarak ele almayı seçebilirsiniz. Bu seçenek, geçişli olarak akmayan varlıkların bulunduğu build, buildCrossTargeting, contentFiles veya analyzers klasörlerindeki ve geliştirme bağımlılığı olarak işaretlenmiş olan developmentDependency = "true" varlıkları içeren paketler için otomatik olarak ayarlanır.

5. Paket uyumluluğu sorunlarını gözden geçirin.

6. Geçişi başlatmak için Tamam'ı seçin.

7. Geçişin sonunda, Visual Studio yedeklemenin yolunu, yüklü paketlerin listesini (üst düzey bağımlılıklar), geçiş bağımlılıkları olarak başvuruda bulunılan paketlerin listesini ve geçiş başlangıcında tanımlanan uyumluluk sorunlarının listesini içeren bir rapor sağlar. Rapor yedekleme klasörüne kaydedilir.

8. Çözümün derlendiğini ve çalıştığını doğrulayın. Sorunlarla karşılaşırsanız GitHub'da bir sorun oluşturun.

packages.config'a geri dönme

1. Taşınmış projeyi kapatın.

2. Proje dosyasını ve packages.config'yi yedeklemeden (genellikle <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) proje klasörüne kopyalayın. Proje kök dizininde varsa obj klasörünü silin.

3. Projeyi açın.

4. Araçlar > NuGet Paket Yöneticisi Paket Yöneticisi Konsolu menü komutunu kullanarak Paket Yöneticisi > Konsolu'nu açın.

5. Konsolda aşağıdaki komutu çalıştırın:

   update-package -reinstall
   

Geçiş sonrasında paket oluşturma

Geçiş tamamlandıktan sonra, paket meta verilerinizi bir .nuspec dosyasından MSBuild özelliklerine kopyalayıp ardından msbuild -t:pack kullanarak paketi oluşturabilirsiniz. Visual Studio 2022 veya önceki bir sürümünü kullanıyorsanız NuGet.Build.Tasks.Pack paketini de yüklemeniz gerekir. Visual Studio 2026'da paket, MSBuild'de yerleşik olarak bulunur.

Paket uyumluluğu sorunları

packages.config'de desteklenen bazı özellikler PackageReference'ta desteklenmez. Taşıyıcı bu tür sorunları analiz eder ve algılar. Aşağıdaki sorunlardan birine veya daha fazlasına sahip herhangi bir paket, geçiş sonrasında beklendiği gibi davranmayabilir.

Geçiş sonrasında paket yüklendiğinde "install.ps1" betikleri dikkate alınmaz.

• Açıklama: PackageReference ile install.ps1 ve uninstall.ps1 PowerShell betikleri paket yüklenirken veya kaldırılırken yürütülmez.

• Olası etki: Hedef projedeki bazı davranışları yapılandırmak için bu betiklere bağımlı paketler beklendiği gibi çalışmayabilir.

Geçiş sonrasında paket yüklendiğinde "içerik" varlıkları kullanılamaz

• Açıklama: Paketin content klasöründeki varlıklar PackageReference ile desteklenmez ve yoksayılır. PackageReference, daha iyi geçişli desteğe ve paylaşılan içeriğe sahip olmak için contentFiles desteği ekler.

• Olası etki: içindeki content varlıklar projeye kopyalanmaz ve bu varlıkların varlığına bağlı olarak proje kodu yeniden düzenleme gerektirir.

Yükseltmeden sonra paket yüklendiğinde XDT dönüşümleri uygulanmaz

• Açıklama: XDT dönüşümleri PackageReference ile desteklenmez ve .xdt paket yüklenirken veya kaldırılırken dosyalar yoksayılır.

• Olası etki: XDT dönüşümleri, proje XML dosyalarından en yaygın olanlarına, ve 'ye, uygulanmaz. Bu, paketi yüklendiğinde veya kaldırıldığında projenin dosyasının güncellenmediği anlamına gelir.

Paket geçiş sonrasında yüklendiğinde lib kökündeki derlemeler yoksayılır

• Açıklama: PackageReference ile, hedef çerçeveye özgü bir alt klasör olmadan klasörün kökünde lib bulunan derlemeler yoksayılır. NuGet, projenin hedef çerçevesine karşılık gelen hedef çerçeve adıyla (TFM) eşleşen bir alt klasör arar ve eşleşen derlemeleri projeye yükler.

• Olası etki: Projenin hedef çerçevesine karşılık gelen hedef çerçeve adıyla (TFM) eşleşen bir alt klasörü olmayan paketler, geçiş sonrasında beklendiği gibi davranmayabilir veya geçiş sırasında yükleme başarısız olabilir.

Bir sorun mu buldunuz? Rapor edin!

Geçiş deneyimiyle ilgili bir sorunla karşılaşırsanız lütfen NuGet GitHub deposunda bir sorun oluşturun.