.NET 10 NU1510 paket budaması CI restore işlemlerini başarısız kılabilir; çözüm hedef framework'lerinize bağlı

.NET 10 SDK'sına yükseltme, rutin bir restore işlemini CI hatasına dönüştürebilir; çünkü NuGet paket budaması artık .NET 10 veya sonrasını hedefleyen projelerde varsayılan olarak etkin. dev.to'da yayınlanan bir yazı, NU1510 tanılamasının neden ortaya çıktığını, işaretlenen paket referansının her yerden silmenin neden yanlış bir refleks olduğunu ve sorunun hedef framework bazında nasıl çözüleceğini açıklıyor.

NU1510 nasıl bir CI hatasına dönüşür

dev.to makalesine göre NuGet, budama için kaydedilmiş bir pakete yapılan doğrudan referans tamamen kaldırılabildiğinde NU1510'u yükseltiyor; çünkü hedeflenen SDK zaten aynı veya daha yüksek bir assembly sürümünü sağlıyor. Tanılama bilinçli olarak dardır: genel amaçlı bir kullanılmayan paket algılayıcısı değildir ve rastgele üçüncü taraf paketlere uygulanmaz.

Hata, birçok deponun TreatWarningsAsErrors ayarını global olarak belirlemesi nedeniyle CI'da ortaya çıkıyor. Makaledeki örnekte net10.0 projesine System.Text.Json 10.0.11'e doğrudan bir referans ekleniyor; stabil .NET SDK 10.0.303 ile restore, NU1510 uyarıdan hataya yükseltildiği için kod 1 ile çıkıyor. Uyarıların hata sayıldığı bir politika olmadığında, aynı durum normalde yalnızca bir uyarı üretir.

Makale, Microsoft'un .NET 10 kırıcı değişiklik kılavuzunun, her hedef referansı budaabiliyorsa referansı kaldırmayı, daha eski bir hedefin hâlâ ihtiyaç duyduğu durumlarda ise referansı koşullandırmayı önerdiğini belirtiyor.

Doğru çözüm hedefe bağlı

Yalnızca net10.0 hedefleyen bir uygulama için çözüm basitçe PackageReference'ı silmektir. Framework System.Text.Json'ı hâlâ sağlıyor ve örnek uygulama, referans kaldırıldıktan sonra da onu içe aktarmaya ve aynı yükü seri hale getirmeye devam ediyor.

Çok hedefli bir kütüphane farklı bir çözüm gerektiriyor. Örnek hem netstandard2.0 hem de net10.0'ı desteklediğinden, referansı global olarak kaldırmak eski hedefin gerektirdiği bir bağımlılığı ortadan kaldırırdı. Çözüm, PackageReference'ı yalnızca hedef framework netstandard2.0 olduğunda geçerli olacak şekilde koşullandırarak gerekliliği MSBuild'de açık hale getirmektir.

NuGet restore her hedef framework için ayrı bir bağımlılık grafiği oluşturur ve dotnet pack framework'e özgü bağımlılık meta verisi üretir. Yazar, bir hedefin hâlâ ihtiyaç duyduğu koşulsuz bir referansın NU1510 üretmediğini belirtiyor; çünkü her hemek değil her hedeften kaldırılamaz; açık koşul, niyetin gözden geçirilebilir olmasını sağlamak için var. Mevcut pack davranışı, budanabilir bir bağımlılığı net10.0 grubundan çıkarırken eski hedef için tutuyor. Daha büyük bir framework matrisi için uyumluluk temelli bir koşul bakımı daha kolay olabilir, ancak yine de desteklenen her hedefe karşı doğrulanması gerekir.

Yalnızca uyarıyı değil, bağımlılık grafiğini doğrulayın

Makalede kaybolan bir uyarı yeterli kanıt olarak görülmüyor. Yazar dokuz davranışı kontrol eden bir doğrulayıcı oluşturuyor: bozuk restore NU1510 ile başarısız oluyor, tanılama System.Text.Json'ı adlandırıyor, düzeltilmiş uygulama çalışıyor, build asset'lerinde paket kopyası bulunmuyor ve çok hedefli asset'ler ile paketlenen nuspec bağımlılığı yalnızca netstandard2.0 için koruyor. Doğrulayıcı PASS 9/9 raporluyor ve beş tekrarlanan çalıştırma bayt bayt aynı çıktı üretti.

Makale ayrıca bir sınırlamaya da açıkça değiniyor: örnek modern uygulamayı çalıştırıyor, eski kütüphane hedefi ise restore, build, asset meta verisi ve paketlenen nuspec üzerinden doğrulanıyor. Netstandard2.0 uygulaması çalıştırdığı iddiasında bulunmuyor.

Bir referansın ne zaman kaldırılmaması gerekiyor

Bu yaklaşım yalnızca SDK veya referans verilen bir framework bir paketi budama için kaydettiğinde geçerlidir. Özel bir paket, yalnızca ad alanı framework işlevselliğine benzediği için gereksiz hale gelmez. Örnek yalnızca SDK'nın sağladığı System.Text.Json durumunu kapsıyor; tanılama belgelerinde açıklanan ayrı FrameworkReference ve geçişli ProjectReference senaryosunu modellemiyor ve restore boyutu ya da hızı hakkında hiçbir iddiada bulunmuyor.

Yazar, gerçek bir kütüphanede referans kaldırmadan önce desteklenen her hedefi restore etmeyi, build etmeyi, test etmeyi ve pack yapmayı, ardından ortaya çıkan bağımlılık gruplarını incelemeyi öneriyor; özellikle merkezi paket yönetimi veya daha karmaşık MSBuild koşulları söz konusuysa. NU1510'u bastırmak bir geçişi geçici olarak engelden kurtarabilir, ancak yayınlanan bağımlılık sözleşmesinin doğru olup olmadığını kanıtlamaz.

Neden önemli

Hatalara yükseltilen uyarılar, SDK yükseltmelerinin CI hatlarını bozmasının en yaygın yollarından biri; ve cazip gelen çözüm, işaretlenen referansı her yerden silmek, hâlâ netstandard2.0 hedefleyen bir kütüphanenin tüketicilerini sessizce kırıyor. NU1510'u hedef bazında bir bağımlılık kararı olarak ele almak, restore'ları yeşil tutarken eski runtime'lar için uyumluluğu koruyor ve paketlenmiş çıktıyı doğrulamak, uyarının kaybolması ile yayınlanan paketin gerçekten doğru olması arasındaki boşluğu kapatıyor.