Manajemen Paket Pusat (CPM)

Artikel
04/18/2023

Manajemen dependensi adalah fitur inti dari NuGet. Mengelola dependensi untuk satu proyek bisa mudah. Mengelola dependensi untuk solusi multi-proyek dapat terbukti sulit karena mereka mulai menskalakan dalam ukuran dan kompleksitas. Dalam situasi di mana Anda mengelola dependensi umum untuk banyak proyek yang berbeda, Anda dapat memanfaatkan fitur manajemen paket pusat (CPM) NuGet untuk melakukan semua ini dari kemudahan satu lokasi.

Secara historis, dependensi paket NuGet telah dikelola di salah satu dari dua lokasi:

packages.config - File XML yang digunakan dalam jenis proyek yang lebih lama untuk mempertahankan daftar paket yang direferensikan oleh proyek.
<PackageReference /> - Elemen XML yang digunakan dalam proyek MSBuild mendefinisikan dependensi paket NuGet.

Dimulai dengan NuGet 6.2, Anda dapat mengelola dependensi Anda secara terpusat di proyek Anda dengan penambahan Directory.Packages.props file dan properti MSBuild.

Fitur ini tersedia di semua alat terintegrasi NuGet, dimulai dengan versi berikut.

Alat yang lebih lama akan mengabaikan konfigurasi dan fitur manajemen paket pusat. Untuk menggunakan fitur ini sepenuhnya, pastikan semua lingkungan build Anda menggunakan versi alat terbaru yang kompatibel.

Manajemen paket pusat berlaku untuk semua <PackageReference>proyek MSBuild berbasis (termasuk CSPROJ warisan) selama alat yang kompatibel digunakan.

Mengaktifkan Manajemen Paket Pusat

Untuk mulai menggunakan manajemen paket pusat, Anda harus membuat Directory.Packages.props file di akar repositori Anda dan mengatur properti ManagePackageVersionsCentrally MSBuild ke true.

Di dalamnya, Anda kemudian menentukan masing-masing versi paket yang diperlukan dari proyek Anda menggunakan <PackageVersion /> elemen yang menentukan ID dan versi paket.

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.1" />
  </ItemGroup>
</Project>

Untuk setiap proyek, Anda kemudian menentukan <PackageReference /> tetapi menghilangkan Version atribut karena versi akan dicapai dari item yang sesuai <PackageVersion /> .

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" />
  </ItemGroup>
</Project>

Sekarang Anda menggunakan manajemen paket pusat dan mengelola versi Anda di lokasi pusat!

Aturan Manajemen Paket Pusat

File Directory.Packages.props memiliki sejumlah aturan sehubungan dengan lokasinya di direktori repositori dan konteksnya. Demi kesederhanaan, hanya satu Directory.Packages.props file yang dievaluasi untuk proyek tertentu.

Artinya, jika Anda memiliki beberapa Directory.Packages.props file di repositori Anda, file yang paling dekat dengan direktori proyek Anda akan dievaluasi untuk itu. Ini memungkinkan Anda kontrol ekstra di berbagai tingkat repositori Anda.

Berikut adalah contohnya, pertimbangkan struktur repositori berikut:

Repository
 |-- Directory.Packages.props
 |-- Solution1
     |-- Directory.Packages.props
     |-- Project1
 |-- Solution2
     |-- Project2

Project1 akan mengevaluasi Directory.Packages.props file di Repository\Solution1\ direktori dan harus mengimpor file berikutnya secara manual jika diinginkan.

<Project>
  <Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
  <ItemGroup>
    <PackageVersion Update="Newtonsoft.Json" Version="12.0.1" />
  </ItemGroup>
</Project>

Project2 akan mengevaluasi Directory.Packages.props file di Repository\ direktori.

Catatan: MSBuild tidak akan secara otomatis mengimpor masing-masing Directory.Packages.props untuk Anda, hanya yang pertama yang paling dekat dengan proyek. Jika Anda memiliki beberapa Directory.Packages.props, Anda harus mengimpor induk satu secara manual sementara akar Directory.Packages.props tidak akan.

Memulai

Untuk sepenuhnya onboarding repositori Anda, pertimbangkan untuk mengambil langkah-langkah berikut:

Buat file baru di akar repositori Anda bernama Directory.Packages.props yang mendeklarasikan versi paket yang ditentukan secara terpusat dan atur properti ManagePackageVersionsCentrally MSBuild ke true.
Deklarasikan <PackageVersion /> item di .Directory.Packages.props
Deklarasikan <PackageReference /> item tanpa Version atribut dalam file proyek Anda.

Untuk gambaran tentang bagaimana manajemen paket pusat mungkin terlihat seperti, lihat repositori sampel kami.

Penyematan transitif

Anda dapat secara otomatis mengambil alih versi paket transitif bahkan tanpa tingkat <PackageReference /> atas eksplisit dengan memilih fitur yang dikenal sebagai penyematan transitif. Ini mempromosikan dependensi transitif ke dependensi tingkat atas secara implisit atas nama Anda jika perlu.

Anda dapat mengaktifkan fitur ini dengan mengatur properti CentralPackageTransitivePinningEnabled MSBuild ke true dalam proyek atau dalam Directory.Packages.props file atau Directory.Build.props impor:

<PropertyGroup>
  <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
</PropertyGroup>

Mengesampingkan versi paket

Anda dapat mengambil alih versi paket individual dengan menggunakan VersionOverride properti pada <PackageReference /> item. Ini mengambil alih setiap <PackageVersion /> yang ditentukan secara terpusat.

<Project>
  <ItemGroup>
    <PackageVersion Include="PackageA" Version="1.0.0" />
    <PackageVersion Include="PackageB" Version="2.0.0" />
  </ItemGroup>
</Project>

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="PackageA" VersionOverride="3.0.0" />
  </ItemGroup>
</Project>

Anda dapat menonaktifkan fitur ini dengan mengatur properti CentralPackageVersionOverrideEnabled MSBuild ke false dalam proyek atau dalam Directory.Packages.props file atau Directory.Build.props impor:

<PropertyGroup>
  <CentralPackageVersionOverrideEnabled>false</CentralPackageVersionOverrideEnabled>
</PropertyGroup>

Ketika fitur ini dinonaktifkan, menentukan VersionOverride pada item apa pun <PackageReference /> akan mengakibatkan kesalahan pada waktu pemulihan yang menunjukkan bahwa fitur dinonaktifkan.

Menonaktifkan Manajemen Paket Pusat

Jika Anda ingin menonaktifkan manajemen paket pusat untuk proyek tertentu, Anda dapat menonaktifkannya dengan mengatur properti ManagePackageVersionsCentrally MSBuild ke false:

<PropertyGroup>
  <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
</PropertyGroup>

Referensi Paket Global

Catatan

Fitur ini hanya tersedia di Visual Studio 2022 17.4 atau yang lebih tinggi, .NET SDK 7.0.100.preview7 atau yang lebih tinggi, dan NuGet 6.4 atau yang lebih tinggi.

Referensi paket global digunakan untuk menentukan bahwa paket akan digunakan oleh setiap proyek dalam repositori. Ini termasuk paket yang melakukan penerapan versi, memperluas build Anda, atau paket lain yang diperlukan oleh semua proyek. Referensi paket global ditambahkan ke grup item PackageReference dengan metadata berikut:

IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
Ini memastikan bahwa paket hanya digunakan sebagai dependensi pengembangan dan mencegah referensi rakitan waktu kompilasi.
PrivateAssets="All"
Ini mencegah referensi paket global diambil oleh dependensi hilir.

GlobalPackageReference item harus ditempatkan di Anda Directory.Packages.props untuk digunakan oleh setiap proyek di repositori:

<Project>
  <ItemGroup>
    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.5.109" />
  </ItemGroup>
</Project>

Peringatan saat menggunakan beberapa sumber paket

Saat menggunakan manajemen paket pusat, Anda akan melihat NU1507 peringatan jika Anda memiliki lebih dari satu sumber paket yang ditentukan dalam konfigurasi Anda. Untuk mengatasi peringatan ini, petakan sumber paket Anda dengan pemetaan sumber paket atau tentukan satu sumber paket.

There are 3 package sources defined in your configuration. When using central package management, please map your package sources with package source mapping (https://aka.ms/nuget-package-source-mapping) or specify a single package source.