Bagikan melalui

PackageReference dalam file proyek

Referensi paket, menggunakan <PackageReference> item MSBuild, menentukan dependensi paket NuGet langsung dalam file proyek, dibandingkan dengan memiliki file terpisah packages.config . Penggunaan PackageReference tidak memengaruhi aspek NuGet lainnya; misalnya, pengaturan dalam NuGet.Config file (termasuk sumber paket) masih diterapkan seperti yang dijelaskan dalam konfigurasi NuGet Umum.

Dengan PackageReference, Anda juga dapat menggunakan kondisi MSBuild untuk memilih referensi paket per kerangka kerja target, atau pengelompokan lainnya. Ini juga memungkinkan kontrol terperinci atas dependensi dan aliran konten. (Lihat untuk detail selengkapnya tentang paket dan pemulihan NuGet sebagai target MSBuild.)

Dukungan jenis proyek

Secara default, PackageReference digunakan untuk proyek .NET Core, proyek .NET Standard, dan proyek UWP yang menargetkan Windows 10 Build 15063 (Creators Update) dan yang lebih baru, dengan pengecualian proyek C++ UWP. Proyek .NET Framework mendukung PackageReference, tetapi saat ini default ke packages.config. Untuk menggunakan PackageReference, migrasikan dependensi dari ke dalam file proyek Anda, lalu hapus packages.config.

Aplikasi ASP.NET yang menargetkan Framework .NET penuh hanya menyertakan dukungan terbatas untuk PackageReference. Jenis proyek C++ dan JavaScript tidak didukung.

Penambahan PackageReference

Tambahkan dependensi dalam file proyek Anda menggunakan sintaks berikut:

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

Mengontrol versi dependensi

Konvensi untuk menetapkan versi paket sama seperti saat menggunakan packages.config:

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

Dalam contoh di atas, 3.6.0 berarti versi apa pun yang < 3.6.0 dengan preferensi untuk versi terendah, seperti yang dijelaskan pada Penentuan Versi Paket.

Menggunakan PackageReference untuk proyek tanpa dependensi paket

Tingkat Lanjut: Jika Anda tidak memiliki paket yang diinstal dalam proyek (tidak ada PackageReferences dalam file proyek dan tidak ada file packages.config), tetapi ingin proyek dipulihkan sebagai gaya PackageReference, Anda dapat mengatur properti Proyek RestoreProjectStyle ke PackageReference dalam file proyek Anda.

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

Ini dapat berguna, jika Anda mereferensikan proyek yang bergaya PackageReference (proyek csproj atau SDK yang ada). Ini akan memungkinkan paket yang dirujuk oleh proyek tersebut untuk secara transitif dirujuk oleh proyek Anda.

PackageReference dan sumber

Dalam proyek PackageReference, versi dependensi transitif diselesaikan pada waktu pemulihan. Dengan demikian, dalam proyek PackageReference semua sumber harus tersedia untuk semua pemulihan.

Versi Mengambang

Versi mengambang didukung dengan PackageReference:

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

Mengontrol aset dependensi

Anda mungkin menggunakan dependensi murni sebagai alat bantu pengembangan dan mungkin tidak ingin mengeksposnya ke proyek yang akan menggunakan paket Anda. Dalam skenario ini, Anda dapat menggunakan PrivateAssets metadata untuk mengontrol perilaku ini.

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

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

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

Tag metadata berikut mengontrol aset dependensi:

Tag Deskripsi Nilai Bawaan
SertakanAset Aset ini akan dikonsumsi semua
ExcludeAssets Aset ini tidak akan digunakan tidak ada
PrivateAssets Aset ini akan digunakan tetapi tidak akan mengalir ke proyek induk contentfiles; Analisis; membangun

Nilai yang diizinkan untuk tag ini adalah sebagai berikut, dengan beberapa nilai dipisahkan oleh titik koma kecuali dengan all dan none yang harus muncul sendiri:

Nilai Deskripsi
kompilasi lib Konten folder dan kontrol apakah proyek Anda dapat dikompilasi terhadap rakitan dalam folder
waktu proses Isi dari folder lib dan runtimes dan mengontrol apakah assembly ini akan disalin ke direktori hasil build
contentFiles Isi folder contentfiles
membangun .props dan .targets di folder build
buildMultitargeting (4.0).props dan .targets di folder buildMultitargeting, untuk kerangka kerja lintas penargetan.
buildTransitive (5.0+).props dan .targets di buildTransitive folder, untuk aset yang mengalir ke proyek apa pun yang menggunakan secara transitif. Lihat halaman fitur.
Penganalisis Penganalisis .NET
native contentfiles Isi folder
tidak ada Tidak ada dari yang di atas digunakan.
all Semua hal di atas (kecuali 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>

Perhatikan bahwa karena build tidak disertakan dengan PrivateAssets, target dan props akan mengalir ke proyek induk. Pertimbangkan, misalnya, bahwa referensi di atas digunakan dalam proyek yang membangun paket NuGet yang disebut AppLogger. AppLogger dapat menggunakan target dan atribut dari Contoso.Utility.UsefulStuff, sebagaimana proyek yang menggunakan AppLogger juga dapat melakukannya.

Catatan

Ketika developmentDependency disetel sebagai true dalam berkas .nuspec, ini menandai paket sebagai dependensi khusus pengembangan, yang mencegah paket tersebut disertakan sebagai dependensi di paket lain. Dengan PackageReference (NuGet 4.8+), bendera ini juga berarti bahwa akan mengecualikan aset waktu kompilasi dari proses kompilasi. Untuk informasi selengkapnya, lihat Dukungan DevelopmentDependency untuk PackageReference.

Menambahkan kondisi PackageReference

Anda dapat menggunakan kondisi untuk mengontrol apakah paket disertakan, di mana kondisi dapat menggunakan variabel MSBuild atau variabel yang didefinisikan dalam file target atau file properti. Namun, saat ini, hanya variabel TargetFramework yang didukung.

Misalnya, Anda menargetkan netstandard1.4 serta net452 tetapi memiliki dependensi yang hanya berlaku untuk net452. Dalam hal ini, Anda tidak ingin proyek netstandard1.4 yang menggunakan paket Anda untuk menambahkan ketergantungan yang tidak perlu. Untuk mencegah hal ini, Anda menentukan kondisi pada PackageReference sebagai berikut:

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

Paket yang dibangun menggunakan proyek ini akan menunjukkan bahwa Newtonsoft.Json disertakan sebagai dependensi hanya untuk net452 target:

The result of applying a Condition on PackageReference with VS2017Hasil penerapan Kondisi pada PackageReference dengan VS2017

Kondisi juga dapat diterapkan pada tingkat dan ItemGroup akan berlaku untuk semua elemen anak PackageReference :

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

GeneratePathProperty

Fitur ini tersedia dengan NuGet 5.0 atau lebih tinggi dan dengan Visual Studio 2019 16.0 atau lebih tinggi.

Terkadang diperlukan untuk merujuk file dalam paket dari target MSBuild. Dalam proyek-proyek berbasis packages.config, paket diinstal dalam folder relatif terhadap file proyek. Namun dalam PackageReference, paket digunakan dari folder global-packages, yang dapat bervariasi dari komputer ke komputer.

Untuk menjembatani kesenjangan itu, NuGet memperkenalkan properti yang menunjuk ke lokasi dari mana paket akan dikonsumsi.

Contoh:

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

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

Selain itu NuGet akan secara otomatis menghasilkan properti untuk paket yang berisi folder alat.

  <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>

Properti MSBuild dan identitas paket tidak memiliki batasan yang sama, sehingga identitas paket perlu diubah menjadi nama yang sesuai untuk MSBuild, diawali dengan "Pkg". Untuk memverifikasi nama properti yang dihasilkan, lihat file yang dihasilkan nuget.g.props.

Alias PackageReference

Dalam beberapa instans langka, paket yang berbeda akan berisi kelas di namespace yang sama. Dimulai dengan NuGet 5.7 dan Visual Studio 2019 Update 7, yang setara dengan ProjectReference, PackageReference mendukung Aliases. Secara default tidak ada alias yang disediakan. Ketika alias ditentukan, semua rakitan yang berasal dari paket anotasi perlu dirujuk dengan alias.

Anda dapat melihat penggunaan sampel di NuGet\Samples

Dalam file proyek, tentukan alias sebagai berikut:

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

dan dalam kode gunakan sebagai berikut:

extern alias ExampleAlias;

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

Peringatan dan kesalahan NuGet

Fitur ini tersedia dengan NuGet 4.3 atau lebih tinggi dan dengan Visual Studio 2017 15.3 atau lebih tinggi.

Untuk banyak skenario penyusunan paket dan pemulihan, semua peringatan dan kesalahan NuGet diberi kode, dan dimulai dengan NU****. Semua peringatan dan kesalahan NuGet tercantum dalam dokumentasi referensi.

NuGet mengamati properti peringatan berikut:

  • TreatWarningsAsErrors, perlakukan semua peringatan sebagai kesalahan.
  • WarningsAsErrors, perlakukan peringatan tertentu sebagai kesalahan
  • NoWarn, sembunyikan peringatan tertentu, baik secara keseluruhan proyek maupun paket.

Contoh:

<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>

Mengabaikan peringatan NuGet

Meskipun disarankan agar Anda menyelesaikan semua peringatan NuGet selama operasi paket dan pemulihan Anda, dalam situasi tertentu menekan peringatan tersebut bisa dibenarkan. Untuk menekan peringatan di seluruh proyek, pertimbangkan untuk melakukan:

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

Terkadang peringatan hanya berlaku untuk paket tertentu dalam grafik. Kita dapat memilih untuk menekan peringatan tersebut secara lebih selektif dengan menambahkan NoWarn pada item PackageReference.

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

Menyembunyikan peringatan paket NuGet di Visual Studio

Saat berada di Visual Studio, Anda juga bisa mengabaikan peringatan melalui IDE.

Mengunci dependensi

Fitur ini tersedia dengan NuGet 4.9 atau lebih tinggi dan dengan Visual Studio 2017 15.9 atau lebih tinggi.

Input untuk pemulihan NuGet adalah sekumpulan PackageReference item dari file proyek (dependensi tingkat atas atau langsung) dan outputnya adalah cakupan penuh dari semua dependensi paket termasuk dependensi transitif. NuGet mencoba untuk selalu menghasilkan penutupan penuh dependensi paket yang sama jika daftar PackageReference input tidak berubah. Namun, ada beberapa skenario di mana ia tidak dapat melakukannya. Contohnya:

  • Saat Anda menggunakan versi mengambang seperti <PackageReference Include="My.Sample.Lib" Version="4.*"/>. Meskipun niat di sini adalah untuk menggunakan versi terbaru setiap kali memulihkan paket, ada skenario di mana pengguna mengharuskan grafik harus dikunci ke versi tertentu dan beralih ke versi yang lebih baru, jika tersedia, dengan tindakan eksplisit.

  • Versi terbaru dari paket yang memenuhi persyaratan versi PackageReference telah diterbitkan. Misalnya.

    • Hari 1: jika Anda menentukan <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> tetapi versi yang tersedia di repositori NuGet adalah 4.1.0, 4.2.0 dan 4.3.0. Dalam hal ini, NuGet akan diselesaikan ke 4.1.0 (versi minimum terdekat)

    • Hari 2: Versi 4.0.0 akan diterbitkan. NuGet sekarang akan menemukan kecocokan yang tepat dan mulai menyelesaikan ke 4.0.0

  • Versi paket tertentu dihapus dari repositori. Meskipun nuget.org tidak mengizinkan penghapusan paket, tidak semua repositori paket memiliki batasan ini. Ini menghasilkan NuGet menemukan kecocokan terbaik ketika tidak dapat mengatasi versi yang dihapus.

Mengaktifkan file kunci

Untuk mempertahankan penutupan penuh dependensi paket, Anda dapat mengaktifkan fitur file kunci dengan mengatur properti RestorePackagesWithLockFile MSBuild untuk proyek Anda:

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

Jika properti ini diatur, pemulihan NuGet akan menghasilkan file kunci packages.lock.json di direktori root proyek yang mencantumkan semua dependensi paket.

Catatan

Setelah proyek memiliki packages.lock.json file di direktori akarnya, file kunci selalu digunakan dengan pemulihan meskipun properti RestorePackagesWithLockFile tidak diatur. Jadi cara lain untuk ikut serta dalam fitur ini adalah dengan membuat file kosong packages.lock.json dummy di direktori akar proyek.

restore perilaku dengan file kunci

Jika file kunci ada untuk proyek, NuGet menggunakan file kunci ini untuk menjalankan restore. NuGet melakukan pemeriksaan cepat untuk melihat apakah ada perubahan dalam dependensi paket seperti yang disebutkan dalam file proyek (atau file proyek dependen) dan jika tidak ada perubahan, itu hanya memulihkan paket yang disebutkan dalam file kunci. Tidak ada evaluasi ulang dependensi paket.

Jika NuGet mendeteksi perubahan dependensi yang ditentukan seperti yang disebutkan dalam file proyek, NuGet mengevaluasi kembali grafik paket dan memperbarui file kunci untuk mencerminkan penutupan paket baru untuk proyek.

Untuk CI/CD dan skenario lainnya, di mana Anda tidak ingin mengubah dependensi paket secara mendadak, Anda dapat melakukannya dengan mengatur lockedmode ke true:

Untuk dotnet.exe, jalankan:

> dotnet.exe restore --locked-mode

Untuk msbuild.exe, jalankan:

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

Anda juga dapat mengatur properti MSBuild kondisi ini dalam file proyek Anda:

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

Jika mode terkunci adalah true, pemulihan akan memulihkan paket yang tepat seperti yang tercantum dalam file penguncian atau gagal jika Anda memperbarui dependensi paket yang ditentukan untuk proyek setelah file penguncian dibuat.

Jadikan kunci file bagian dari repositori sumber Anda

Jika Anda membangun aplikasi, yang dapat dieksekusi dan proyek yang dimaksud adalah pada awal rantai dependensi, maka periksa file kunci ke repositori kode sumber sehingga NuGet dapat menggunakannya selama pemulihan.

Namun, jika proyek Anda adalah proyek pustaka yang tidak Anda distribusikan atau proyek kode umum yang diandalkan oleh proyek lain, Anda tidak boleh memasukkan berkas kunci sebagai bagian dari kode sumber Anda. Tidak ada salahnya menyimpan file kunci tetapi dependensi paket terkunci untuk proyek kode umum mungkin tidak digunakan, seperti yang tercantum dalam file kunci, selama pemulihan/build proyek yang bergantung pada proyek kode umum ini.

Ct.

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

Jika ProjectA memiliki dependensi pada PackageX versi 2.0.0 dan juga merujuk ProjectB yang bergantung pada PackageX versi 1.0.0, maka file kunci untuk ProjectB akan mencantumkan sebuah dependensi pada PackageX versi 1.0.0. Namun, ketika ProjectA dibangun, file kunci akan berisi dependensi pada PackageX versi 2.0.0 dan tidak1.0.0 seperti yang tercantum dalam file kunci untuk ProjectB. Dengan demikian, file kunci dari proyek kode umum memiliki sedikit pengaruh terhadap paket yang dipilih untuk proyek yang bergantung padanya.

Mengunci file sehingga dapat diperluas

Anda dapat mengontrol berbagai perilaku pemulihan dengan file kunci seperti yang dijelaskan di bawah ini:

opsi NuGet.exe opsi dotnet Opsi yang ekuivalen dengan MSBuild Deskripsi
-UseLockFile --use-lock-file MemulihkanPaketDenganBerkasPengunci Memilih opsi penggunaan file kunci.
-LockedMode --locked-mode RestoreLockedMode Mengaktifkan mode terkunci untuk pemulihan. Ini berguna dalam skenario CI/CD di mana Anda menginginkan build yang dapat diulang.
-ForceEvaluate --force-evaluate RestoreForceEvaluate Opsi ini berguna dengan paket dengan versi mengambang yang ditentukan dalam proyek. Secara default, pemulihan NuGet tidak akan memperbarui versi paket secara otomatis pada setiap pemulihan kecuali Anda menjalankan pemulihan dengan opsi ini.
-LockFilePath --lock-file-path NuGetLockFilePath Menentukan lokasi file kunci kustom untuk proyek. Secara default, NuGet mendukung packages.lock.json di direktori akar. Jika Anda memiliki beberapa proyek dalam direktori yang sama, NuGet mendukung file kunci spesifik proyek.

Pemecah Masalah Ketergantungan NuGet

Penyelesai dependensi NuGet mengikuti 4 aturan seperti yang dijelaskan dalam dokumen resolusi dependensi.

Untuk meningkatkan performa dan skalabilitas operasi pemulihan, algoritma pemulihan ditulis ulang dalam rilis 6.12. Pada rilis 6.12, algoritma pemulihan baru diaktifkan secara default untuk semua proyek PackageReference. Meskipun algoritma pemulihan baru secara fungsional setara dengan yang sebelumnya, seperti halnya perangkat lunak apa pun, bug dimungkinkan. Untuk kembali ke implementasi sebelumnya, setel properti MSBuild RestoreUseLegacyDependencyResolver ke true.

Jika Anda menghadapi kegagalan pemulihan di 6.12, .NET 9, atau 17.12, yang tidak terjadi di versi sebelumnya, silakan ajukan masalah di GitHub. Perbedaan antara algoritma lama dan baru mungkin memiliki dampak yang berbeda, seperti selama kompilasi atau pada runtime. Ada juga kemungkinan perubahan tidak menyebabkan kegagalan, tetapi versi paket yang berbeda dipulihkan. Jika Menurut Anda, Anda mungkin terpengaruh oleh perubahan apa pun, berikut adalah langkah-langkah yang dapat Anda ambil untuk memverifikasi apakah perubahan dalam algoritma pemulihan NuGet adalah akar penyebabnya.

Restore merekam hasilnya ke direktori MSBuildProjectExtensionsPath, yang dapat dibandingkan dengan algoritma baru dan lama untuk menemukan perbedaan. Biasanya ini adalah folder obj dari build Anda. Anda dapat menggunakan msbuild.exe atau dotnet.exe untuk langkah-langkah berikutnya.

  1. Hapus folder obj untuk proyek Anda.
  2. Jalankan msbuild -t:restore
  3. Simpan isi dari obj ke lokasi yang menunjukkan bahwa itu adalah perilaku new.
  4. Jalankan msbuild -t:restore
  5. Simpan isi dari obj ke lokasi yang menunjukkan bahwa itu adalah perilaku legacy.
  6. Bandingkan file di dua direktori, terutama project.assets.json. Alat yang dapat menyoroti perbedaan sangat berguna untuk ini (misalnya, Visual Studio Code, membuka kedua file, dan menggunakan klik kanan "pilih untuk membandingkan" dan "bandingkan dengan yang dipilih")

Jika Anda mengikuti metode di atas, harus hanya ada satu perbedaan antara file project.assets.json.

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

Jika ada lebih banyak perbedaan, silakan ajukan masalah di GitHub dengan semua detailnya.

AssetTargetFallback

Properti AssetTargetFallback memungkinkan Anda menentukan versi kerangka kerja tambahan yang kompatibel untuk proyek yang dirujuk oleh proyek Anda dan paket NuGet yang digunakan oleh proyek Anda.

Jika Anda menentukan dependensi paket menggunakan PackageReference, tetapi paket tersebut tidak berisi aset yang kompatibel dengan kerangka kerja target proyek Anda, maka properti AssetTargetFallback akan mulai berperan. Kompatibilitas paket yang direferensikan diperiksa ulang menggunakan setiap framework sasaran yang ditentukan dalam AssetTargetFallback. Ketika project atau package dirujuk melalui AssetTargetFallback, peringatan NU1701 akan muncul.

Lihat tabel di bawah ini untuk contoh bagaimana AssetTargetFallback memengaruhi kompatibilitas.

Kerangka kerja proyek AssetTargetFallback Kerangka kerja paket Hasil
.NET Framework 4.7.2 .NET Standar 2.0 .NET Standar 2.0
Aplikasi .NET Core 3.1 .NET Standard 2.0, .NET Framework 4.7.2 .NET Standar 2.0
Aplikasi .NET Core 3.1 .NET Framework 4.7.2 Tidak kompatibel, gagal dengan NU1202
Aplikasi .NET Core 3.1 net472; net471 .NET Framework 4.7.2 .NET Framework 4.7.2 dengan NU1701

Beberapa kerangka kerja dapat ditentukan menggunakan ; sebagai pembatas. Untuk menambahkan kerangka kerja fallback, Anda dapat melakukan hal berikut:

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

Anda dapat meninggalkan $(AssetTargetFallback) jika Anda ingin menimpa, alih-alih menambahkan ke nilai yang AssetTargetFallback ada.

Catatan

Jika Anda menggunakan proyek berbasis .NET SDK, nilai yang sesuai $(AssetTargetFallback) dikonfigurasi dan Anda tidak perlu mengaturnya secara manual.

$(PackageTargetFallback) adalah fitur sebelumnya yang mencoba mengatasi tantangan ini, tetapi pada dasarnya rusak dan tidak boleh digunakan. Untuk bermigrasi dari $(PackageTargetFallback) ke $(AssetTargetFallback), cukup ubah nama properti.

PrunePackageReference

Runtime .NET terus berkembang, dengan peningkatan performa dan API baru setiap rilis. Ada banyak fungsionalitas yang tersedia dalam runtime, tetapi juga sebagai paket, seperti System.Text.Json. Ini dapat sering kali menyebabkan System.Text.Json 8.0.0 dalam proyek yang menargetkan .NET 9 atau .NET 8. Dependensi ini tidak perlu dan resolusi konflik build tidak akan menggunakan assembly yang berasal dari paket karena sudah tersedia di .NET Runtime. Mulai dari NuGet versi 6.13 dan .NET SDK 9.0.200, PrunePackageReference memungkinkan pemangkasan paket ini pada waktu pemulihan untuk proyek berbasis .NET SDK.

Pemangkasan paket tersedia sebagai fitur opsional dengan .NET 9 SDK, dan akan diaktifkan secara default untuk semua kerangka kerja .NET dan >= .NET Standard 2.0 mulai dari .NET 10 SDK.

Pemangkasan paket hanya tersedia dengan penyelesai dependensi default ketika dirilis dalam versi 6.12.

Spesifikasi "PrunePackageReference"

Daftar paket yang akan dipangkas dengan item PrunePackageReference didefinisikan.

Atributs Deskripsi
Versi Menentukan versi maksimum yang akan dipangkas. 1.0.0 berarti bahwa semua paket hingga dan termasuk 1.0.0 akan dihapus. Untuk 1.0.0, 0.9.0 dan 1.0.0 akan dipangkas, tetapi 1.0.1 tidak akan.

Properti berikut dapat digunakan untuk memodifikasi perilaku pemangkasan.

Nama Properti Deskripsi
AktifkanPemulihanPemangkasanPaket Mengaktifkan pemangkasan paket untuk paket yang ditentukan dengan PrunePackageReference. Properti ini khusus untuk kerangka kerja target dan nilai yang berlaku adalah true dan false. Pengaturan default mungkin berbeda berdasarkan .NET SDK seperti yang didefinisikan di atas.

.NET SDK telah menetapkan daftar paket yang akan dipangkas untuk Anda.

Cara kerja PrunePackageReference

Ketika paket ditentukan untuk dipangkas selama pemulihan, paket dihapus dari grafik dependensi. Paket ini tidak diunduh dan tidak muncul di salah satu output NuGet. Ketika paket dipangkas, ada pesan verbositas terperinci yang menunjukkan bahwa paket telah dihapus untuk kerangka kerja target yang diberikan.

Pemangkasan hanya didukung untuk paket transitif, yang berarti paket yang dirujuk oleh paket atau proyek lain. Tabel berikut mengilustrasikan berbagai perilaku pemangkasan paket.

Pengelolaan Ketergantungan Perilaku
Cocok dengan ID paket transitif yang masuk melalui paket lain Pangkas
Cocok dengan ID paket transitif yang masuk melalui proyek lain Pangkas
Cocok dengan ID langsung PackageReference Naikkan peringatan NU1510 dan jangan pangkas
Mencocokkan dengan ID dari ProjectReference Naikkan peringatan NU1511 dan jangan pangkas

Aplikasi PrunePackageReference

Manfaat pemangkasan paket terdiri dari dua manfaat utama:

  • Manfaat performa, dengan mengurangi jumlah paket dalam grafik dependensi
  • Pengurangan positif palsu oleh pemindai komponen seperti NuGetAudit

Pemangkasan menjadi sangat berharga ketika melakukan audit pada paket dengan NuGetAuditMode yang diatur ke all. Jika Anda menggunakan .NET 9, kami sarankan Anda mencoba pemangkasan dengan mengatur RestoreEnablePackagePruning ke true.