NuGet paket bağımlılıklarını nasıl çözümler?

Bir paket geri yükleme işleminin parçası olarak yüklenmeyi de içeren herhangi bir paket yüklendiğinde veya yeniden yüklendiğinde, NuGet bu ilk paketin bağımlı olduğu tüm ek paketleri de yükler.

Bu anlık bağımlılıkların kendi bağımlılıkları da olabilir ve bu da rastgele bir derinliğe kadar devam edebilir. Bu, tüm düzeylerdeki paketler arasındaki ilişkileri açıklayan bağımlılık grafiği olarak adlandırılan bir grafik oluşturur.

Birden çok paket aynı bağımlılığına sahip olduğunda, aynı paket kimliği grafikte birden çok kez ve farklı sürüm kısıtlamalarıyla birlikte görünebilir. Ancak, projede belirli bir paketin yalnızca bir sürümü kullanılabilir, bu nedenle NuGet hangi sürümün kullanılacağını seçmelidir. Tam işlem, kullanılmakta olan paket yönetimi biçimine bağlıdır.

PackageReference ile bağımlılık çözümlemesi

PackageReference biçimini kullanarak projelere paket yüklerken, NuGet uygun dosyadaki düz bir paket grafiğine başvurular ekler ve çakışmaları önceden çözer. Bu işlem, geçişli geri yüklemeolarak adlandırılır. Paketlerin yeniden yüklenmesi veya geri yüklenmesi, grafikte listelenen paketleri indirme işlemidir ve bu da daha hızlı ve tahmin edilebilir derlemelere neden olur.

Projenin bir paketin en son sürümünü kullanacak şekilde değiştirilmesini önlemek için 2.8.* gibi kayan sürümlerden de yararlanabilirsiniz. Kayan sürümleri kullanırken, tekrarlanabilirliği sağlamak için kilit dosyası işlevselliği etkinleştirmenizi öneririz.

NuGet geri yükleme işlemi bir derlemeden önce çalıştırıldığında, önce bellekte bağımlılıkları çözer, ardından sonuçta elde edilen grafiği project.assets.jsonadlı bir dosyaya yazar.

Varlıklar dosyası, varsayılan olarak projenin 'obj' klasörüne sahip olan MSBuildProjectExtensionsPathkonumunda bulunur. MSBuild daha sonra bu dosyayı okur ve olası başvuruların bulunabileceği bir klasör kümesine çevirir ve sonra bunları bellekteki proje ağacına ekler.

project.assets.json dosyası geçicidir ve kaynak denetimine eklenmemelidir. Hem .gitignore hem de .tfignorevarsayılan olarak listelenir. Bkz. Paketler ve kaynak denetimi.

Bağımlılık çözümleme kuralları

Geçişli geri yükleme, bağımlılıkları çözmek için dört ana kural uygular: en düşük geçerli sürüm, değişken sürümler, doğrudan bağımlılık kazanırve kuzen bağımlılıkları.

En düşük uygulanabilir sürüm

Geçerli en düşük sürüm kuralı, bir paketin bağımlılıkları tarafından tanımlandığı şekilde mümkün olan en düşük sürümünü geri yükler. Ayrıca, kayanolarak bildirilmediği sürece uygulama veya sınıf kitaplığındaki bağımlılıklar için de geçerlidir.

Aşağıdaki şekilde, örneğin, 1.0-beta 1.0'dan düşük olarak kabul edilir, bu nedenle NuGet 1.0 sürümünü seçer:

Sonraki şekilde, sürüm kısıtlaması >= 2.1 olduğundan, 2.1 sürümü akışta kullanılamaz, ancak NuGet bulabileceği sonraki en düşük sürümü seçer, bu durumda 2.2:

Uygulama akışta bulunmayan 1.2 gibi tam bir sürüm numarası belirttiğinde, NuGet paketi yüklemeye veya geri yüklemeye çalışırken hatayla başarısız olur:

tam bir paket sürümü kullanılamadığında bir hata oluşturur

Kayan sürümler

* karakteriyle kayan bağımlılık sürümü belirtilir. Örneğin, 6.0.*. Bu sürüm belirtimi "en son 6.0.x sürümünü kullan" diyor; 4.* "en son 4.x sürümünü kullan" anlamına gelir. Kayan sürümün kullanılması proje dosyasındaki değişiklikleri azaltırken bağımlılığın en son sürümünü güncel tutar. Kayan sürümler yalnızca proje düzeyinde belirtilebilir.

Kayan sürüm kullanırken NuGet, bir paketin sürüm deseniyle eşleşen en yüksek sürümünü çözümler, örneğin 6.0.* paketin 6.0 ile başlayan en yüksek sürümünü alır:

Sürüm	Sunucuda mevcut sürümler	Çözünürlük	Sebep	Notlar
*	1.1.0 1.1.1 1.2.0 1.3.0-alfa	1.2.0	En yüksek kararlı sürüm.
1.1.*	1.1.0 1.1.1 1.1.2-alfa 1.2.0-alfa	1.1.1	Belirtilen desene saygı gösteren en yüksek kararlı sürüm.
*-*	1.1.0 1.1.1 1.1.2-alfa 1.3.0-beta	1.3.0-beta	Kararlı olmayan sürümler de dahil olmak üzere en yüksek sürüm.	Visual Studio sürüm 16.6, NuGet sürüm 5.6, .NET Core SDK sürüm 3.1.300'de kullanılabilir
1.1.*-*	1.1.0 1.1.1 1.1.2-alfa 1.1.2-beta 1.3.0-beta	1.1.2-beta	Desene saygılı ve kararlı olmayan sürümleri içeren en yüksek sürüm.	Visual Studio sürüm 16.6, NuGet sürüm 5.6, .NET Core SDK sürüm 3.1.300'de kullanılabilir
1.2.0-rc.*	1.1.0 1.2.0-rc.1 1.2.0-rc.2 1.2.0	1.2.0	Bu, yayın öncesi bir sürüm aralığı olmasına rağmen, kararlı sürümler kararlı kısmıyla eşleşiyorsa izin verilir. 1.2.0 > 1.2.0-rc.2 olduğu için seçildi.

Not

Kayan sürüm çözümlemesi, bir paketin listelenip listelenmediğini dikkate almaz. Koşulların Genel Paket Klasöründeki paketlerle karşılanabilmesi durumunda kayan sürüm çözümlemesi yerel olarak çözülür.

Doğrudan bağımlılık kazanır

Bir uygulamanın paket grafı aynı alt grafiğe ait bir paketin farklı sürümlerini içerdiğinde ve bu sürümlerden biri söz konusu alt grafiğe doğrudan bağımlılık olduğunda, söz konusu alt yazı için bu sürüm seçilir ve geri kalanı yoksayılır. Bu davranış, bir uygulamanın bağımlılık grafiğindeki belirli bir paket sürümünü geçersiz kılmasına olanak tanır.

Aşağıdaki örnekte, uygulama doğrudan >=2.0.0 sürüm kısıtlaması olan B Paketine bağlıdır. Uygulama ayrıca Paket A'ya da bağlıdır ve bu da paket B'ye bağlıdır, ancak >=1.0.0 kısıtlaması vardır. Paket B 2.0.0 bağımlılığı grafikteki uygulamaya doğrudan bağımlılık olduğundan, bu sürüm kullanılır:

Doğrudan bağımlılık kazanır kuralını kullanarak Uygulama

Uyarı

Doğrudan bağımlılık kazanan kuralı, paket sürümünün düşmesine ve böylece grafikteki diğer bağımlılıkların potansiyel olarak bozulmasına neden olabilir. Bir paket eski sürüme indirildiğinde, NuGet kullanıcıyı uyarmak için uyarısı ekler.

Bu kural ayrıca büyük bir bağımlılık grafiğiyle daha fazla verimlilik sağlar. Aynı alt grafiğe daha yakın bir bağımlılığın bir sonrakinden daha yüksek bir sürümü olduğunda, NuGet bu bağımlılığı yoksayar ve NuGet de grafın bu dalında kalan tüm bağımlılıkları yoksayar.

Örneğin, aşağıdaki diyagramda, Paket C 2.0.0 kullanıldığından, NuGet, o alt grafikte Paket C'nin önceki bir sürümüne başvuran dalları yoksayar.

Bu kural aracılığıyla NuGet, paket yazarının amacına saygı göstermeye çalışır. Aşağıdaki diyagramda, Paket A'nın yazarı, açıkça Paket C 2.0.0'dan Paket C 1.0.0'a düşürmüştür.

Uygulama sahibi, Paket C'yi 2.0.0'dan daha yüksek bir sürüme yükseltmeyi seçebilir, bu nedenle C Paketi sürümünü daha fazla düşürmez. Bu durumda uyarı alınmaz.

Kuzen bağımlılıkları

tr-TR: Uygulama grafiğindeki farklı altgrafiklerde farklı paket sürümlerine başvurulduğunda, NuGet, tüm sürüm gereksinimlerini karşılayan en düşük sürümü kullanır (bu, geçerli en düşük sürüm ve kayan sürümler kurallarıyla olduğu gibi). Aşağıdaki görüntüde, örneğin, B Paketinin 2.0.0 sürümü diğer >=1.0.0 kısıtlamasını karşılar ve bu nedenle kullanılır:

Kuzen bağımlılıklar kuralının uygulanması için paketlerin aynı mesafede olması gerekmediğini unutmayın. Aşağıdaki diyagramda, Paket C alt imzasında Paket D 2.0.0 ve Paket A'nın alt bölümünde D 3.0.0 paketi seçilmiştir. Uygulama alt grafisinde D Paketine doğrudan bağımlılık yoktur, bu nedenle en düşük geçerli sürüm kuralı uygulanır ve sürüm 3.0.0 seçilir.

Bazı durumlarda tüm sürüm gereksinimlerini karşılamak mümkün değildir. Aşağıda gösterildiği gibi, Paket A tam olarak B 1.0.0 paketini gerektiriyorsa ve C Paketi B >=2.0.0 paketini gerektiriyorsa NuGet bağımlılıkları çözümleyemez ve bir hata verir.

tam sürüm gereksinimi nedeniyle çözümlenemeyen bağımlılıkları

Bu gibi durumlarda en üst düzey tüketicinin (uygulama veya paket) B Paketine kendi doğrudan bağımlılığını eklemesi gerekir, böylece doğrudan bağımlılığı kazanır kuralı uygulanır.

PackageReference ile sürüm aralıkları ve yayın öncesi sürümler

Bir paketin hem kararlı hem de yayın öncesi sürümlerinin kullanılabilir olması olağan dışı değildir. Bir bağımlılık grafiğini çözerken NuGet, tek bir kurala dayalı olarak bir paket için yayın öncesi sürümlerin dikkate alınıp alınmayacağına karar verir: If the project or any packages within the graph request a prerelease version of a package, then include both prerelease or stable versions, otherwise consider stable versions only.

Pratikte, en düşük geçerli kural altında, bu şu anlama gelir:

Sürüm Aralığı	Kullanılabilir sürümler	Seçili sürüm
[1.0.0, 2.0.0)	1.2.0-beta.1, 1.2.0,	1.2.0
[1.0.0, 2.0.0-0)	1.2.0-beta.1, 1.2.0,	1.2.0-beta.1
[1.0.0, 2.0.0)	1.2.0-beta.1, 2.0.0-beta.3	Hiçbiri, NU1103 tetiklenir.
[1.0.0, 2.0.0-rc)	1.2.0-beta.1, 2.0.0-beta.3	1.2.0-beta.1

packages.config ile bağımlılık çözümü

packages.configile projenin bağımlılıkları packages.config düz liste olarak yazılır. Bu paketlerin tüm bağımlılıkları da aynı listeye yazılır. Paketler yüklendiğinde, NuGet .csproj dosyasını, app.config, web.configve diğer dosyaları da değiştirebilir.

packages.configile NuGet, her bir paketin yüklenmesi sırasında bağımlılık çakışmalarını çözmeyi dener. Yani, Paket A yükleniyorsa ve B Paketine bağlıysa ve B Paketi zaten packages.config'de başka bir şeyin bağımlılığı olarak listeleniyorsa, NuGet istenen B Paketinin sürümlerini karşılaştırır ve tüm sürüm kısıtlamalarına uygun bir sürüm bulmaya çalışır. Özellikle, NuGet bağımlılıkları karşılayan alt major.minor sürümünü seçer.

Varsayılan olarak, NuGet 2.8 en düşük düzeltme eki sürümünü arar (bkz. NuGet 2.8 sürüm notlarını ). Bu ayarı, DependencyVersion'daki NuGet.Config özniteliği ve komut satırındaki -DependencyVersion anahtarı aracılığıyla denetleyebilirsiniz.

Bağımlılıkları çözümlemeye yönelik packages.config işlemi, daha büyük bağımlılık grafikleri için karmaşık hale gelir. Her yeni paket yüklemesi, grafiğin tamamının çapraz geçişini gerektirir ve sürüm çakışmaları olasılığını yükseltir. Bir çakışma oluştuğunda, yükleme durdurulur ve özellikle proje dosyasının kendisinde olası değişikliklerle proje belirsiz bir durumda bırakılır. Bu, diğer paket yönetimi biçimleri kullanılırken bir sorun değildir.

packages.config ile sürüm aralıkları ve yayın öncesi sürümler

packages.config çözümleme, grafikte kararlı ve yayın öncesi bağımlılığın karıştırılmasını sağlamaz. Bir bağımlılık [1.0.0, 2.0.0)gibi bir aralıkla ifade edilirse, yayın öncesi paketlere grafikte izin verilmez.

Bağımlılık varlıklarını yönetme

PackageReference biçimini kullanırken, bağımlılıklardan hangi varlıkların en üst düzey projeye aktığını denetleyebilirsiniz. Ayrıntılar için bkz. PackageReference.

Üst düzey proje bir paket olduğunda, include dosyasında listelenen bağımlılıklara sahip exclude ve .nuspec özniteliklerini kullanarak da bu akış üzerinde denetim sahibi olursunuz. Bkz. .nuspec Referansı - Bağımlılıklar.

Referansları dışlama

Aynı ada sahip derlemelere bir projede birden çok kez başvurulabilecek ve bu da tasarım zamanı ve derleme zamanı hatalarına neden olabilecek senaryolar vardır. C.dllözel sürümünü içeren ve C.dlliçeren C Paketine başvuran bir proje düşünün. Aynı zamanda proje, C Paketine ve C.dllde bağlı olan B Paketine de bağlıdır. Sonuç olarak, NuGet hangi C.dll kullanılacağını belirleyemez, ancak B Paketi de buna bağlı olduğundan projenin C Paketi bağımlılığını kaldıramazsınız.

Bu sorunu çözmek için doğrudan istediğiniz C.dll'a başvurmanız (veya doğru pakete başvuran başka bir paket kullanmanız) ve ardından tüm varlıklarını hariç tutan Paket C'ye bir bağımlılık eklemeniz gerekir. Bu, kullanımdaki paket yönetimi biçimine bağlı olarak aşağıdaki gibi yapılır:

• PackageReference: bağımlılığa ExcludeAssets="All" ekle:

  <PackageReference Include="PackageC" Version="1.0.0" ExcludeAssets="All" />
  

• packages.config: .csproj dosyasındaki PackageC referansını kaldırın ve sadece istediğiniz C.dll sürümüne başvurduğundan emin olun.

Paket yükleme sırasında bağımlılık güncelleştirmeleri

Bir bağımlılık sürümü zaten karşılandıysa, diğer paket yüklemeleri sırasında bağımlılık güncelleştirilmez. Örneğin, B paketine bağlı olan ve sürüm numarası için 1.0'ı belirten A paketini göz önünde bulundurun. Kaynak depo B paketinin 1.0, 1.1 ve 1.2 sürümlerini içerir. A zaten B sürüm 1.0 içeren bir projeye yüklenmişse, sürüm kısıtlamasını karşıladığı için B 1.0 kullanımda kalır. Ancak, A paketinin B'nin 1.1 veya üzeri bir sürümünü istemesi durumunda B 1.2 yüklenir.

Uyumsuz paket hatalarını çözme

Paket geri yükleme işlemi sırasında "Bir veya daha fazla paket uyumlu değil..." hatasını görebilirsiniz veya bir paketin projenin hedef çerçevesiyle "uyumlu olmadığını" belirtir.

Projenizde başvuruda bulunılan paketlerden biri veya daha fazlası projenin hedef çerçevesini desteklediğini belirtmediğinde bu hata oluşur; başka bir ifadeyle paket, projeyle uyumlu bir hedef çerçeve için lib klasöründe uygun bir DLL içermez. (Bkz. Hedef çerçevelerin listesi için.)

Örneğin, bir proje netstandard1.6 hedeflediyse ve yalnızca lib\net20 ve \lib\net45 klasörlerinde DLL'ler içeren bir paket yüklemeye çalışırsanız, paket ve büyük olasılıkla bağımlıları için aşağıdaki gibi iletiler görürsünüz:

Restoring packages for myproject.csproj...
Package ContosoUtilities 2.1.2.3 is not compatible with netstandard1.6 (.NETStandard,Version=v1.6). Package ContosoUtilities 2.1.2.3 supports:
  - net20 (.NETFramework,Version=v2.0)
  - net45 (.NETFramework,Version=v4.5)
Package ContosoCore 0.86.0 is not compatible with netstandard1.6 (.NETStandard,Version=v1.6). Package ContosoCore 0.86.0 supports:
  - 11 (11,Version=v0.0)
  - net20 (.NETFramework,Version=v2.0)
  - sl3 (Silverlight,Version=v3.0)
  - sl4 (Silverlight,Version=v4.0)
One or more packages are incompatible with .NETStandard,Version=v1.6.
Package restore failed. Rolling back package changes for 'MyProject'.

Uyumsuzlukları çözmek için aşağıdakilerden birini yapın:

• Projenizi, kullanmak istediğiniz paketler tarafından desteklenen bir çerçeveye yeniden hedefleyin.
• Paketlerin yazarına başvurun ve seçtiğiniz çerçeve için destek eklemek için onlarla birlikte çalışın. nuget.org'daki her paket listeleme sayfasında bu amaçla bir Paket Sahipleriyle İletişim bağlantısı bulunmaktadır.

Tavsiye

Alternatif çözüm: NuGetSolver, Microsoft DevLabs tarafından geliştirilen ve bağımlılık çakışmalarının çözülmesine yardımcı olmak için tasarlanmış bir Visual Studio Uzantısıdır. Bu sorunları tanımlama ve çözme sürecini otomatikleştirir. Diğer ayrıntılar için Visual Studio Market'in NuGetSolver sayfasını ziyaret edin ve deneyiminiz hakkındaki geri bildirimlerinizi duymak isteriz.