PackageReference proje dosyalarında

MSBuild öğelerini kullanarak <PackageReference> paket başvuruları, ayrı bir packages.config dosyasına sahip olmak yerine NuGet paket bağımlılıklarını doğrudan proje dosyaları içinde belirtir. PackageReference kullanımı, NuGet'in diğer yönlerini etkilemez; örneğin, NuGet.Config dosyalarındaki ayarlar (paket kaynakları dahil), Yaygın NuGet yapılandırmaları'nda açıklandığı gibi uygulanmaya devam eder.

PackageReference ile, hedef çerçeve başına paket başvurularını veya diğer gruplandırmaları seçmek için MSBuild koşullarını da kullanabilirsiniz. Ayrıca bağımlılıklar ve içerik akışı üzerinde ayrıntılı denetim sağlar. (Daha fazla bilgi için bkz. MSBuild hedefleri olarak NuGet paketleme ve geri yükleme.)

Proje türü desteği

PackageReference varsayılan olarak C++ UWP projeleri dışında Windows 10 Derleme 15063 (Creators Update) ve sonraki sürümleri hedefleyen .NET projeleri, .NET Standard projeleri ve UWP projeleri için kullanılır. .NET Framework projeleri PackageReference'ı destekler, ancak şu anda varsayılan packages.config'dir. PackageReference'ı bir .NET Framework projesinde kullanmak için, bağımlılıkları içinden proje dosyanıza packages.config, ardından packages.config dosyasını kaldırın.

Tam .NET Framework'leri hedefleyen ASP.NET uygulamalar PackageReference için yalnızca sınırlı destek içerir. C++ ve JavaScript proje türleri desteklenmez.

PackageReference Ekleme

Aşağıdaki söz dizimini kullanarak proje dosyanıza bir bağımlılık ekleyin:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Bağımlılık sürümünü denetleme

Bir paketin sürümünü belirtme kuralı, packages.config kullanılırkenkiyle aynıdır:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Yukarıdaki örnekte 3.6.0, Paket sürümü oluşturma bölümünde açıklandığı gibi en düşük sürümü tercih eden >=3.6.0 olan herhangi bir sürüm anlamına gelir.

Paket bağımlılığı olmayan bir proje için PackageReference kullanma

Gelişmiş: Projede yüklü paket yoksa (proje dosyasında PackageReference yoksa ve packages.config dosyası yoksa) ancak projenin PackageReference stili olarak geri yüklenmesini istiyorsanız, proje dosyanızda RestoreProjectStyle Proje özelliğini PackageReference olarak ayarlayabilirsiniz.

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>

PackageReference stilindeki projelere (mevcut csproj veya SDK stili projeler) başvurursanız bu yararlı olabilir. Bu, söz konusu projelerin atıfta bulunduğu paketlerin projeniz tarafından "geçişli" olarak atıfta bulunulmasını sağlar.

PackageReference ve kaynaklar

PackageReference projelerinde geçişli bağımlılık sürümleri geri yükleme zamanında çözümlenir. Bu nedenle, PackageReference projelerinde tüm kaynakların tüm geri yüklemeler için kullanılabilir olması gerekir.

Kayan Sürümler

Kayan sürümler, PackageReference ile desteklenir:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta.*" />
    <!-- ... -->
</ItemGroup>

Bağımlılık varlıklarını denetleme

Bir bağımlılığı yalnızca geliştirme koşumu olarak kullanıyor olabilirsiniz ve bunu paketinizi kullanacak projelere göstermek istemeyebilirsiniz. Bu senaryoda, bu davranışı denetlemek için PrivateAssets meta verilerini kullanabilirsiniz.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <PrivateAssets>all</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

Aşağıdaki meta veri etiketleri bağımlılık varlıklarını denetler:

Tag Description Varsayılan Değer
IncludeAssets Bu varlıklar tüketilecek all
ExcludeAssets Bu varlıklar tüketilmeyecek none
PrivateAssets Bu varlıklar kullanılacak ancak üst projeye akmayacak contentfiles;analyzers;build

Bu etiketler için izin verilen değerler aşağıda gösterildiği gibi ve dışında allnonetek başına görünmesi gereken noktalı virgülle ayrılmış birden çok değer vardır:

Value Description
compile lib klasörünün içeriği ve projenizin bu klasördeki derlemelere göre derlenip derlenemeyeceğini kontrol eder.
runtime lib ve runtimes klasörlerinin içeriği ve bu derlemelerin derleme çıktı dizinine kopyalanıp kopyalanmayacağını denetler.
contentFiles contentfiles klasörünün içeriği
build .props ve .targetsbuild klasöründe
buildMultitargeting (4.0).props ve .targetsbuildMultitargeting klasöründe, çerçeveler arası hedefleme için
buildTransitive (5,0+) ve klasöründeki, herhangi bir tüketen projeye geçişli olarak aktarılan varlıklar için. Özellik sayfasına bakın.
analyzers .NET çözümleyicileri
native native klasörünün içeriği
none Yukarıdakilerin hiçbiri kullanılmaz.
all Yukarıdakilerin tümü (hariç none) 
<ItemGroup>
    <!-- ... -->
    <!-- Everything except the content files will be consumed by the project -->
    <!-- Everything except content files and analyzers will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets> <!-- Default is `all`, can be omitted-->
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>
    <!-- ... -->
    <!-- Everything except the compile will be consumed by the project -->
    <!-- Everything except contentFiles will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.SomeOtherUsefulStuff" Version="3.6.0">
        <ExcludeAssets>compile</ExcludeAssets>
        <PrivateAssets>contentFiles</PrivateAssets>
    </PackageReference>
    <!-- ... -->
</ItemGroup>

Unutmayın ki buildPrivateAssets ile birlikte dahil edilmediğinden, hedefler ve özellikler üst projeye akacaktır. Örneğin, yukarıdaki başvurunun AppLogger adlı bir NuGet paketi oluşturan bir projede kullanıldığını düşünün. AppLogger, AppLogger kullanan projeler gibi Contoso.Utility.UsefulStuff'den hedeflerini ve prop'larını tüketebilir.

Note

developmentDependency bir true dosyada .nuspec olarak ayarlandığında, bu işlem paketi yalnızca geliştirme için bağımlılık olarak işaretler ve bu, paketin diğer paketlere bağımlılık olarak eklenmesini önler. PackageReference (NuGet 4.8+) ile bu işaret, derleme zamanı varlıklarını derleme sürecinin dışında tutacağı anlamına gelir. Daha fazla bilgi için PackageReference için DevelopmentDependency desteğine bakınız.

Birden çok çerçeveyi hedefleme

SDK stilindeki projeler, özelliğindeki birden çok değeri listeleyerek çoklu hedeflemeyi TargetFrameworks destekler. Bir proje birden çok çerçeveyi hedeflediğinde, NuGet geri yükleme her çerçeve için ayrı bir bağımlılık grafiği oluşturur ve dotnet pack her hedef için çerçeveye özgü varlıklar içeren bir paket oluşturur.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>
</Project>

Çok hedefli bir proje ayarlamaya yönelik adım adım kılavuz için bkz. Proje dosyanızda birden çok .NET çerçevesini destekleme.

TargetFramework değerleri nasıl çalışır?

TargetFramework Proje dosyasındaki özellik, kurallı çerçeve kimliğine dönüştürülen bir takma addır (diğer bir deyişle, alternatif bir addır). .NET SDK, bu çeviriyi TargetFrameworkMoniker (TFM) ve uygun olduğunda TargetPlatformMoniker özelliklerini ayarlayarak gerçekleştirir.

NuGet, paket uyumluluk denetimleri için, TargetFramework dizisini değil, bu moniker özelliklerini kullanır. Bu, takma ad özellikleri doğru ayarlandığı sürece değerin herhangi bir dize olabileceği anlamına gelir TargetFramework .

Diğer ad oluşturma mekanizması hakkında daha fazla bilgi için TargetFramework değerleri, takma adlar olarak kullanılır bölümüne bakın.

PackageReference koşulu ekleme

Paketin dahil edilip edilmediğini denetlemek için bir koşul kullanabilirsiniz. Koşullar herhangi bir MSBuild değişkenini veya hedefler veya props dosyasında tanımlanan bir değişkeni kullanabilir. Ancak şu anda yalnızca TargetFramework değişkeni desteklenmektedir.

Örneğin, hem netstandard1.4 hem de net452 hedefliyorsunuz, ancak yalnızca net452 için geçerli olan bir bağımlılığınız var. Bu durumda, paketinizi kullanan bir netstandard1.4 projenin bu gereksiz bağımlılığı eklemesini istemezsiniz. Bunu önlemek için, PackageReference üzerinde aşağıdaki gibi bir şart belirtirsiniz:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

Bu proje kullanılarak oluşturulan bir paket, Newtonsoft.Json komponentinin yalnızca bir net452 hedefi için bağımlılık olarak dahil edildiğini gösterir.

VS2017 ile PackageReference'ta bir Koşul uygulamanın sonucu

Koşullar, ItemGroup düzeyinde de uygulanabilir ve tüm alt PackageReference öğelerine uygulanacaktır:

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

GeneratePathProperty

Bu özellik NuGet 5.0 veya üzeri ve Visual Studio 2019 16.0 veya üzeri sürümlerde kullanılabilir.

Bazen bir MSBuild hedefinden, paket içindeki dosyalara başvurmak istenir. packages.config tabanlı projelerde, paketler proje dosyasına göre bir klasöre kurulur. Ancak PackageReference'ta paketler, makineden makineye farklılık gösterebilecek global-packages klasöründen kullanılır.

Bu boşluğu kapatmak için NuGet, paketin tüketileceği konuma işaret eden bir özellik sundu.

Example:

  <ItemGroup>
      <PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgSome_Package)\something.exe" />
  </Target>

Ayrıca NuGet, araçlar klasörünü içeren paketler için otomatik olarak özellikler oluşturur.

  <ItemGroup>
      <PackageReference Include="Package.With.Tools" Version="1.0.0" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
  </Target>

MSBuild özellikleri ve paket kimlikleri aynı kısıtlamalara sahip olmadığından, paket kimliğinin önüne Pkg kelimesi eklenerek MSBuild ile uyumlu bir ada dönüştürülmesi gerekir. Doğrulamak oluşturulan özelliğin tam adına bakmak için, oluşturulan nuget.g.props dosyasına göz atın.

PackageReference takma adlar

Bazı nadir durumlarda, farklı paketler aynı ad alanında sınıflar içerir. NuGet 5.7 ve Visual Studio 2019 Güncelleştirme 7'den itibaren, ProjectReference'a eşdeğer olarak PackageReference da Aliases'yı destekler. Varsayılan olarak, takma ad sağlanmaz. Bir diğer ad belirtildiğinde, açıklamalı paketten gelen tüm derlemelere bir diğer adla başvurulmalıdır.

Örnek kullanıma NuGet\Samples konumundan bakabilirsiniz.

Proje dosyasında diğer adları aşağıdaki gibi belirtin:

  <ItemGroup>
    <PackageReference Include="NuGet.Versioning" Version="5.8.0" Aliases="ExampleAlias" />
  </ItemGroup>

Kodda da aşağıdaki gibi kullanın:

extern alias ExampleAlias;

namespace PackageReferenceAliasesExample
{
...
        {
            var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0");
            Console.WriteLine($"Version : {version}");
        }
...
}

NuGet uyarıları ve hataları

Bu özellik NuGet 4.3 veya üzeri ve Visual Studio 2017 15.3 veya üzeri sürümlerde kullanılabilir.

Birçok paket ve geri yükleme senaryosu için tüm NuGet uyarıları ve hataları kodlanır ve NU**** ile başlar. Tüm NuGet uyarıları ve hataları, başvuru belgelerinde listelenir.

NuGet aşağıdaki uyarı özelliklerini gözlemler:

  • TreatWarningsAsErrors, tüm uyarıları hata olarak değerlendirin.
  • WarningsAsErrors, belirli uyarıları hata olarak değerlendirin.
  • NoWarn, proje genelinde veya paket genelinde belirli uyarıları gizler.

Examples:

<PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>

NuGet uyarılarını gizleme

Paketiniz ve geri yükleme işlemleriniz sırasında tüm NuGet uyarılarını çözmeniz önerilir ancak bazı durumlarda bunları gizlemeniz gerekir. Bir uyarı projesini geniş çapta engellemek için şunları yapmayı göz önünde bulundurun:

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
    <NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>

Bazen uyarılar yalnızca grafikteki belirli bir paket için geçerlidir. PackageReference öğesine bir NoWarn ekleyerek bu uyarıyı daha seçmeli olarak gizlemeyi seçebilirsiniz.

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>

Visual Studio'da NuGet paketi uyarılarını gizleme

Visual Studio'da, IDE aracılığıyla da uyarıları gizleyebilirsiniz.

Bağımlılıkları kilitleme

Bu özellik NuGet 4.9 veya üzeri ve Visual Studio 2017 15.9 veya üzeri sürümlerde kullanılabilir.

NuGet geri yükleme için giriş, proje dosyasındaki PackageReference öğelerinin (üst düzey veya doğrudan bağımlılıklar) bir setidir ve çıkış, geçişli bağımlılıklar da dahil olmak üzere tüm paket bağımlılıklarının tam bir kapatmasıdır. Giriş PackageReference listesi değişmediyse NuGet her zaman paket bağımlılıklarının tam kapanışını oluşturmaya çalışır. Ancak, bunu yapamadığı bazı senaryolar vardır. Örneğin:

  • gibi kayan sürümleri kullandığınızda. Burada amaç paketlerin her geri yüklemesinde en son sürüme geçmek olsa da, kullanıcıların açık bir hareketle grafiğin belirli bir en son sürüme kilitlenmesini ve varsa daha sonraki bir sürüme kaydırılması gerektiğini gerektiren senaryolar vardır.

  • PackageReference sürüm gereksinimleriyle eşleşen paketin daha yeni bir sürümü yayımlanır. Örneğin:

    • 1. Gün: Belirttiyseniz <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> ancak NuGet depolarında kullanılabilen sürümler 4.1.0, 4.2.0 ve 4.3.0'dı. Bu durumda NuGet 4.1.0 (en yakın en düşük sürüm) olarak çözümlenebilirdi.

    • 2. Gün: Sürüm 4.0.0 yayımlanır. NuGet artık tam eşleşmeyi bulacak ve 4.0.0 ile çözümlemeye başlayacaktır.

  • Belirli bir paket sürümü depodan kaldırılır. nuget.org paket silme işlemlerine izin vermese de, tüm paket depolarında bu kısıtlama yoktur. Bu, Silinen sürüme çözümlenemediğinde NuGet'in en iyi eşleşmeyi bulmasına neden olur.

Kilit dosyasını etkinleştirme

Paket bağımlılıklarının tam olarak kapatılmasını kalıcı hale getirmek için projeniz için MSBuild özelliğini ayarlayarak kilit dosyası özelliğini RestorePackagesWithLockFile kabul edebilirsiniz:

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>

Bu özellik ayarlanırsa NuGet geri yükleme, proje kök dizininde tüm paket bağımlılıklarını listeleyen bir kilit dosyası (packages.lock.json) oluşturur.

packages.lock.json biçimi sürümlendirilmiştir. Biçim sürümü, Merkezi Paket Yönetimi'nin geçişli sabitleme veya yinelenen etkin hedef çerçeveleri gibi kullandığınız özelliklere bağlıdır.

Note

Bir projenin kök dizininde bir kilit dosyası bulunduğunda, özellik packages.lock.json ayarlanmasa bile kilit dosyası her zaman geri yükleme işlemiyle kullanılır. Bu özelliği etkinleştirmenin bir diğer yolu, projenin kök dizininde sahte bir boş packages.lock.json dosyası oluşturmaktır.

restore kilit dosyasıyla davranış

Proje için bir kilit dosyası varsa, NuGet çalıştırmak restoreiçin bu kilit dosyasını kullanır. NuGet, proje dosyasında (veya bağımlı projelerin dosyalarında) belirtildiği gibi paket bağımlılıklarında herhangi bir değişiklik olup olmadığını görmek için hızlı bir denetim yapar ve hiçbir değişiklik yoksa, yalnızca kilit dosyasında belirtilen paketleri geri yükler. Paket bağımlılıkları yeniden değerlendirilmez.

NuGet, proje dosyalarında belirtildiği gibi tanımlı bağımlılıklarda bir değişiklik algılarsa, paket grafiğini yeniden değerlendirir ve kilit dosyasını projenin yeni paket kapanışını yansıtacak şekilde güncelleştirir.

CI/CD ve paket bağımlılıklarını anında değiştirmek istemediğiniz diğer senaryolarda, lockedmode'yı true olarak ayarlayarak bunu yapabilirsiniz.

dotnet.exe için şunu çalıştırın:

> dotnet.exe restore --locked-mode

msbuild.exe için şunu çalıştırın:

> msbuild.exe -t:restore -p:RestoreLockedMode=true

Bu koşullu MSBuild özelliğini proje dosyanızda da ayarlayabilirsiniz:

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup>

Kilitli mod true ise, geri yükleme ya kilit dosyasında listelenen tam paketleri geri yükler ya da kilit dosyası oluşturulduktan sonra proje için tanımlanan paket bağımlılıklarını güncellediyseniz başarısız olur.

Dosyaları ve PrunePackageReference'ı kilitleme

PrunePackageReference , gereksiz geçişli paketleri kaldırarak projenin bağımlılıklarını değiştirir. Bu paketlerin kaldırılması çalışma zamanında bir etkiye sahip olmamalıdır, ancak kilit dosyalarını etkiler. Mevcut bir proje için ayıklamayı etkinleştirirseniz, kilit dosyası her yeniden oluşturulduğunda, ayıklama öncesinden daha az pakete yol açabilir. Kilit dosyasının güncellik denetimi kilitli modda, budama işlemini dikkate alır. Başka bir deyişle, projede budamayı etkinleştirdiyseniz, denetim budanan paketleri hesaba katar. Ancak kilit dosyası bir sonraki yeniden oluşturulduğunda ayıklanmış paketleri dışlar, bu nedenle normalden daha büyük bir fark görebilirsiniz.

Kilit dosyasını kaynak deponuzun parçası yapma

Bir uygulama, yürütülebilir dosya oluşturuyorsanız ve söz konusu proje bağımlılık zincirinin başındaysa NuGet'in geri yükleme sırasında kullanabilmesi için dosyayı kaynak kod deposuna iade edin.

Ancak, projeniz dağıtmadığınız bir kütüphane projesiyse veya diğer projelerin bağımlı olduğu ortak bir kod projesiyse, kaynak kodunuzun bir parçası olarak kilit dosyasını commit etmemelisiniz. Kilit dosyasını tutmanın bir zararı yoktur, ancak ortak kod projesinin kilitli paket bağımlılıkları, bu ortak kod projesine bağlı bir projenin geri yüklenmesi/oluşturulması sırasında kilit dosyasında listelendiği gibi kullanılamaz.

Example:

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

Eğer ProjectA'ün bir PackageX sürüm 2.0.0 bağımlılığı varsa ve ProjectB'ü de referans alıyorsa, bu da PackageX sürüm 1.0.0'e bağımlıysa, o zaman ProjectB için kilit dosyasında PackageX sürüm 1.0.0 bağımlılığı listelenir. Ancak, ProjectA oluşturulduğunda, kilit dosyası PackageX sürüm 2.0.0 bağımlılığını içerecektir ve için kilit dosyasında listelendiği gibi 1.0.0ProjectB. Bu nedenle, ortak bir kod projesinin kilit dosyası, buna bağlı projeler için çözümlenen paketler üzerinde çok az söz sahibidir.

Dosya genişletilebilirliğini kilitle

Aşağıda açıklandığı gibi kilit dosyasıyla çeşitli geri yükleme davranışlarını denetleyebilirsiniz:

NuGet.exe seçeneği dotnet seçeneği MSBuild eşdeğeri seçeneği Description
-UseLockFile --use-lock-file RestorePackagesWithLockFile Kilit dosyasının kullanımını kabul eder.
-LockedMode --locked-mode RestoreLockedMode Geri yükleme için kilitli modu etkinleştirir. Bu, yinelenebilir derlemeler istediğiniz CI/CD senaryolarında kullanışlıdır.
-ForceEvaluate --force-evaluate RestoreForceEvaluate Bu seçenek, projede tanımlanan kayan sürüme sahip paketlerde kullanışlıdır. Varsayılan olarak, bu seçenekle geri yüklemeyi çalıştırmadığınız sürece NuGet geri yükleme her geri yüklemede paket sürümünü otomatik olarak güncelleştirmez.
-LockFilePath --lock-file-path NuGetLockFilePath Proje için özel bir kilit dosyası konumu tanımlar. Varsayılan olarak, NuGet kök dizininde packages.lock.json destekler. Aynı dizinde birden çok projeniz varsa, NuGet projeye özgü kilit dosyasını packages..lock.json şeklinde destekler.

NuGet Bağımlılık Çözümleyicisi

NuGet bağımlılık çözümleyicisi, bağımlılık çözümleme belgesinde açıklandığı gibi dört kuralı izler.

Geri yükleme işleminin performansını ve ölçeklenebilirliğini geliştirmek için, geri yükleme algoritması 6.12 sürümünde yeniden yazıldı. 6.12 sürümünden itibaren, yeni geri yükleme algoritması tüm PackageReference projeleri için varsayılan olarak etkinleştirilir. Yeni geri yükleme algoritması, herhangi bir yazılımda olduğu gibi işlevsel olarak öncekine eşdeğer olsa da, hatalar mümkündür. Önceki uygulamaya dönmek için MSBuild özelliğini RestoreUseLegacyDependencyResolver olarak true ayarlayın.

Önceki sürümlerde oluşmayan 6.12, .NET 9 veya 17.12 sürümlerinde geri yükleme hatalarıyla karşılaşırsanız, lütfen GitHub'da bir sorun açın. Eski ve yeni algoritmalar arasındaki farklar, derleme sırasında veya çalışma zamanında olduğu gibi farklı etkilere sahip olabilir. Değişikliklerin hatalara değil, farklı paket sürümlerinin geri yüklenmesine neden olma olasılığı da vardır. Tüm değişikliklerden etkilenmiş olabileceğinizi düşünüyorsanız, NuGet geri yükleme algoritmasındaki değişikliklerin kök neden olup olmadığını doğrulamak için uygulayabileceğiniz adımlar aşağıdadır.

Geri yükleme, sonuçlarını MSBuildProjectExtensionsPath dizinine yazar. Bu, farkları bulmak için yeni ve eski algoritmalarla karşılaştırılabilir. Bu genellikle derlemenizin klasörüdür obj . Bir sonraki adımlar için msbuild.exe veya dotnet.exe kullanabilirsiniz.

  1. obj Projenizin klasörünü kaldırın.

  2. Çalıştır msbuild -t:restore

  3. obj öğesinin içeriğini, bunun new davranışı olduğunu belirten bir konuma kaydedin.

  4. msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true"'i çalıştırın.

  5. obj öğesinin içeriğini, bunun legacy davranışı olduğunu belirten bir konuma kaydedin.

  6. özellikle project.assets.json olmak üzere iki dizindeki dosyaları karşılaştırın.

    Farkları vurgulayan araçlar özellikle bunun için yararlıdır (örneğin, Visual Studio Code'da her iki dosyayı da açın ve sağ tıklayarak "karşılaştırma için seç" ve "seçiliyle karşılaştır") kullanın.

Yukarıdaki yöntemi izlerseniz, project.assets.json dosyaları arasında tam olarak 1 fark olmalıdır.

      "projectStyle": "PackageReference",
+     "restoreUseLegacyDependencyResolver": true,
      "fallbackFolders": [

Başka farklar varsa lütfen GitHub'da tüm ayrıntıları içeren bir sorun oluşturun.

AssetTargetFallback

AssetTargetFallback özelliği, projenizin başvurduğu projeler ve tükettiği NuGet paketleri için ek uyumlu çerçeve sürümleri belirtmenize olanak tanır.

Eğer PackageReference kullanarak bir paket bağımlılığı belirtirseniz ancak bu paket projelerinizin hedef framework'üyle uyumlu varlıklar içermiyorsa, AssetTargetFallback özelliği devreye girer. Başvurulan paketin uyumluluğu, içinde AssetTargetFallback belirtilen her hedef çerçeve kullanılarak yeniden kontrol edilir. project veya package aracılığıyla başvuruda bulunulduğunda, AssetTargetFallback nedeniyle NU1701 uyarısı oluşturulacaktır.

Aşağıdaki tabloya, AssetTargetFallback'ın uyumluluğu nasıl etkilediğine dair örnekler için bakın.

Proje çerçevesi AssetTargetFallback Paket çerçeveleri Result
.NET Framework 4.7.2 .NET Standard 2.0 .NET Standard 2.0
.NET Core Uygulaması 3.1 .NET Standard 2.0, .NET Framework 4.7.2 .NET Standard 2.0
.NET Core Uygulaması 3.1 .NET Framework 4.7.2 Uyumsuz, NU1202 ile başarısızlık
.NET Core Uygulaması 3.1 net472;net471 .NET Framework 4.7.2 .NET Framework 4.7.2 ile NU1701 uyarısı hakkında daha fazla bilgi için lütfen belirtilen bağlantıya tıklayın.

Sınırlayıcı olarak ; kullanılarak birden çok çerçeve belirtilebilir. Geri dönüş çerçevesi eklemek için aşağıdakileri yapabilirsiniz:

<AssetTargetFallback Condition=" '$(TargetFramework)'=='netcoreapp3.1' ">
    $(AssetTargetFallback);net472;net471
</AssetTargetFallback>

Eğer mevcut $(AssetTargetFallback) değerlerine ekleme yapmak yerine üzerine yazmayı tercih ederseniz, AssetTargetFallback'yi devre dışı bırakabilirsiniz.

Note

.NET SDK tabanlı bir proje kullanıyorsanız, uygun değerler yapılandırılmıştır ve bunları manuel olarak ayarlamanıza gerek yoktur.

$(PackageTargetFallback) bu zorluğu ele almak için bir girişimde bulunan eski bir özellikti, ancak temelde hatalıdır ve kullanılmamalıdır. $(PackageTargetFallback)'den $(AssetTargetFallback)'e geçiş yapmak için sadece özellik adını değiştirin.

Yinelenen çerçevelerle çoklu hedefleme

Bu özellik Için NuGet 7.6 / .NET SDK 10.0.300 veya üzeri gerekir.

TargetFramework Değerler diğer adlar olduğundan, birden çok diğer ad aynı etkili çerçeveye bağlanabilir. NuGet 7.6 / .NET SDK 10.0.300'den başlayarak NuGet ve .NET SDK bu senaryoyu destekler.

Bu, aşağıdaki gibi kullanım örneklerini etkinleştirir:

  • Çoklu RID derlemeleri: Tek bir projeden platforma özgü derlemeler oluşturun.

    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0;linux;ios</TargetFrameworks>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TargetFramework)' == 'linux' OR '$(TargetFramework)' == 'ios' OR '$(TargetFramework)' == 'net10.0'">
    <TargetFrameworkIdentifier>.NETCoreApp</TargetFrameworkIdentifier>
    <TargetFrameworkVersion>v10.0</TargetFrameworkVersion>
    <TargetFrameworkMoniker>.NETCoreApp,Version=v10.0</TargetFrameworkMoniker>
  </PropertyGroup>
</Project>

  • Paketin farklı sürümlerini karşılaştırma

    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>benchmark7.0;benchmark8.0</TargetFrameworks>
  </PropertyGroup>

  <!-- Frameworks omitted for brevity-->

  <ItemGroup>
    <PackageReference Include="BenchmarkDotNet" Version="0.13.9" />
    <PackageReference Include="Contoso.FastLibrary" Version="7.0" Condition="'$(TargetFramework)' == 'benchmark7.0' "/>
    <PackageReference Include="Contoso.FastLibrary" Version="8.0" Condition="'$(TargetFramework)' == 'benchmark8.0' "/>
  </ItemGroup>
</Project>

Paket

NuGet paketi, etkili çerçeve başına yalnızca bir derleme çıkışı kümesi ve bir bağımlılık grubu içerebilir. Bir projeyi çift etkili çerçevelerle paketlerken, NuGet'e bu varlıklara hangi takma adın katkıda bulunduğunu söylemelisiniz yoksa paket NU5051 hatası verir. Çözüm adımları ve örnekler için bkz . NU5051 .

Proje referansları

Bir proje aynı çerçeveye çözümleyen birden çok diğer adı olan başka bir projeye başvurduğunda, NuGet diğer adı bir ayırıcı olarak kullanır. Referans veren projede, referans alınan projedeki ile aynı ada sahip bir diğer ad varsa, bu diğer ad tercih edilir. Eşleşen ad yoksa ve birden çok aday varsa NuGet bir hata bildirir.

Sınırlamalar

  • Yalnızca SDK stilindeki projeler yinelenen etkili çerçeveleri destekler.
  • Yol ayırıcı karakterleri (/ veya \) içeren diğer adlar engellenir.
  • Visual Studio'nun Paket Yöneticisi kullanıcı arabirimi yinelenen çerçeveler için özel desteğe sahip değildir, ancak paketleri doğrudan proje dosyasını düzenleyerek veya CLI kullanarak dotnet yönetebilirsiniz.

PrunePackageReference

Her sürümde performans geliştirmeleri ve yeni API'ler ile .NET Çalışma Zamanı sürekli gelişmektedir. .NET'e eklenen yeni özellikler de bazen paket olarak sağlanır; böylece eski hedef çerçeveleri kullanan geliştiriciler System.Text.Json gibi kitaplığı kullanabilir. Bu genellikle System.Text.Json 8.0.0 veya .NET 9'yi hedefleyen bir projede .NET 8'a yol açabilir. Bu bağımlılık gereksizdir ve derleme çakışması çözümü .NET Çalışma Zamanı'nda zaten kullanılabilir olduğundan paketten gelen derlemeyi kullanmaz. NuGet sürüm 6.13 ve .NET SDK 9.0.200'den başlayarak, PrunePackageReference .NET SDK tabanlı projeler için geri yükleme zamanında bu paketlerin ayıklamasını sağlar. Ayıklama işleminin ilk yinelenmesi yalnızca geçişli paketleri etkiledi, ancak .NET SDK 10'dan başlayarak paket ayıklama doğrudan paketleri de etkiler.

Paket ayıklama .NET 9 SDK'sı ile bir katılım özelliği olarak kullanılabilir ve .NET 10 SDK'sını hedefleyen bir projenin tüm çerçeveleri >= .NET 10.0 için varsayılan olarak etkinleştirilir.

Paket ayıklama, 6.12 sürümünde yayımlanan, yalnızca varsayılan bağımlılık çözümleyicisiyle kullanılabilir.

PrunePackageReference spesifikasyonu

Ayıklama yapılacak paketlerin listesi PrunePackageReference öğesiyle tanımlanır.

Attributes Description
Version Ayıklama yapılacak en yüksek sürümü belirtir. 1.0.0, 1.0.0 dahil olmak üzere tüm paketlerin budanacağı anlamına gelir. 1.0.0için, 0.9.0 ve 1.0.0 budanacak, ancak 1.0.1 budanmayacak.

Ayıklama davranışını değiştirmek için aşağıdaki özellikler kullanılabilir.

PropertyName Description
RestoreEnablePackagePruning PrunePackageReferenceile belirtilen paketler için paket ayıklamayı etkinleştirir. Bu özellik hedef çerçeveye göredir ve geçerli değerler true ve false. Varsayılan değerler yukarıda tanımlandığı gibi .NET SDK'sı temelinde farklılık gösterebilir.

.NET SDK'sı, sizin için ayıklama yapılacak paketlerin listesini önceden açıklar. Bu liste, projenizde belirtilen paylaşılan çerçeveleri temel alır. Yalnızca doğrudan çerçeve başvuruları dikkate alınır ve paketler aracılığıyla getirilen çerçeveler için ayıklama verileri eklenmez.

PrunePackageReference nasıl çalışır?

Geri yükleme sırasında ayıklamak üzere bir paket belirtildiğinde, bağımlılık grafiğinden kaldırılır. Bir paket budandığında, belirli bir hedef çerçeve için kaldırıldığını belirten ayrıntılı düzeyde görünür bir mesaj vardır.

Diğer paketlerin veya projelerin bağımlılıkları anlamına gelen geçişli paketler için paketler indirılmaz ve NuGet çıktılarının hiçbirinde görünmez.

Doğrudan paketler için PrivateAssets='all' ve IncludeAssets='none' örtük olarak uygulanır.

  • IncludeAssets='none' derleme sırasında bu paketten derlemelerin kullanılmamasını sağlar. Ayıklama mevcut olmadan önce, derleme sırasındaki çakışma çözümü, paketlerden gelenlere göre platform derlemelerinin tercih edilmesini sağladı.
  • PrivateAssets='all' paketlerin diğer paketlere veya proje başvuruları üzerinden dahil olmamasını sağlar.

Example:

Aşağıdaki gibi bir proje:

  <PropertyGroup>
    <TargetFrameworks>net9.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="System.Text.Json" Version="9.0.4" />
  </ItemGroup>

aşağıdaki bağımlılıklara sahip bir nuspec'e sahip olacaktır:

<dependencies>
    <group targetFramework=".NETFramework4.7.2">
        <dependency id="System.Text.Json" version="9.0.4" />
    </group>
    <group targetFramework="net9.0">
    </group>
</dependencies>

Doğrudan bir PackageReference projenizden tamamen kaldırılabildiğinde ve proje çerçevelerinden biri .NET 10 veya daha yeniyse, NU1510 hatası paketi kaldırmanızı ister. Bu önerinin ardından proje grafınızın karmaşıklığı azaltılır.

Aşağıdaki tabloda tüm paket ayıklama davranışları özetlemektedir.

Bağımlılık yönetimi Behavior
Başka bir paketten gelen geçişli paketin kimliğiyle eşleşir Prune
Başka bir projeden gelen geçişli paketin kimliğiyle eşleşir Prune
Doğrudan PackageReference kimliğiyle eşleşir Paket tüm çerçevelerden kaldırılabildiğinde ve proje .NET PrivateAssets='all' 10'u hedeflediğinde, IncludeAssets='none' uyarısını uygulayın ve uyarısını yükseltin.
ProjectReference ID'siyle eşleşir Proje .NET 10'u hedeflediğinde NU1511 uyarısını budamayın ve kaldırın

PrunePackageReference uygulamaları

Paket ayıklamanın avantajları iki katlıdır:

  • Bağımlılık grafı içindeki paket sayısını azaltmanın getirdiği performans avantajları
  • NuGetAudit gibi bileşen tarayıcıları tarafından hatalı pozitiflerin azaltılması

Budama, özellikle denetim paketlerinde olarak ayarlandığında değerlidir. .NET 9 kullanıyorsanız, RestoreEnablePackagePruning'yi true olarak ayarlayarak ayıklamayı denemenizi öneririz.

  • Last updated on