packages.config dosyasından PackageReference'a geçiş

  • Makale

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önetin: 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.config'in aksine PackageReference yalnızca projeye doğrudan 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 packages klasör yerine genel paketleri ve önbellek klasörlerini yönetme 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.config arasındaki farklar da 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, geçiş seçeneğinin veya Referencesüzerindeki sağ tıklama bağlam menüsünde gösterilmemesine packages.config neden olur.

Geçici çözüm

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

  • Paket Yöneticisi kullanıcı arabirimini açma - Sağ tıklayın References veManage NuGet Packages...
  • Paket Yöneticisi Konsolunu açın - Kimden Tools > NuGet Package Manageröğesini seçinPackage Manager Console
  • NuGet geri yüklemesini çalıştırma - Çözüm Gezgini çözüm düğümüne sağ tıklayın veRestore 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.

Geçiş adımları

Not

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

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

  2. Çözüm Gezgini'da, Başvurular düğümüne veya dosyaya packages.config sağ tıklayın ve Packages.config öğesini 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.

    Not

    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ı (, , veya klasörlerdekilerbuild) ve geliştirme bağımlılığı (developmentDependency = "true") olarak işaretlenmiş varlıkları içeren paketler için otomatik olarak ayarlanır.analyzerscontentFilesbuildCrossTargeting

  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'e geri dönme

  1. Geçirilen projeyi kapatın.

  2. Proje dosyasını ve packages.config 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 nuget.build.tasks.pack nuget paketine bir başvuru eklemenizi ve ardından msbuild -t:pack kullanarak paketi oluşturmanızı öneririz. Bazı senaryolarda yerine msbuild -t:packkullanabilirsinizdotnet.exe pack, ancak önerilmez.

Paket uyumluluğu sorunları

Packages.config dosyasında desteklenen bazı özellikler PackageReference'da desteklenmez. Geçiş oluşturucu 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 yoksayılır

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

  • 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, en yaygın olarak ve proje XML dosyalarına uygulanmaz. web.config.uninstall.xdtBu, web.config.install.xdt paket yüklendiğinde veya kaldırıldığında projenin web.config dosyasının güncelleştirilmediğ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.