Centralne zarządzanie pakietami (CPM)

Artykuł
10/18/2023

Zarządzanie zależnościami to podstawowa funkcja narzędzia NuGet. Zarządzanie zależnościami dla pojedynczego projektu może być łatwe. Zarządzanie zależnościami dla rozwiązań wieloprojektowych może okazać się trudne, ponieważ zaczynają skalować rozmiar i złożoność. W sytuacjach, w których zarządzasz typowymi zależnościami dla wielu różnych projektów, możesz korzystać z funkcji zarządzania pakietami centralnymi (CPM) nuGet, aby to zrobić z łatwości pojedynczej lokalizacji.

W przeszłości zależności pakietów NuGet były zarządzane w jednej z dwóch lokalizacji:

packages.config — Plik XML używany w starszych typach projektów do obsługi listy pakietów, do których odwołuje się projekt.
<PackageReference /> — Element XML używany w projektach MSBuild definiuje zależności pakietów NuGet.

Począwszy od nuGet 6.2, można centralnie zarządzać zależnościami w projektach przy użyciu dodawania Directory.Packages.props pliku i właściwości MSBuild.

Funkcja jest dostępna we wszystkich zintegrowanych narzędziach NuGet, począwszy od następujących wersji.

Starsze narzędzia ignorują centralne konfiguracje i funkcje zarządzania pakietami. Aby korzystać z tej funkcji w najszerszym zakresie, upewnij się, że wszystkie środowiska kompilacji korzystają z najnowszych zgodnych wersji narzędzi.

Centralne zarządzanie pakietami ma zastosowanie do wszystkich <PackageReference>opartych na programie MSBuild projektów (w tym starszych csPROJ), o ile jest używane zgodne narzędzia.

Włączanie centralnego zarządzania pakietami

Aby rozpocząć zarządzanie pakietami centralnymi, należy utworzyć Directory.Packages.props plik w katalogu głównym repozytorium i ustawić właściwość ManagePackageVersionsCentrally MSBuild na true.

Następnie zdefiniuj każdą z odpowiednich wersji pakietów wymaganych przez projekty przy użyciu <PackageVersion /> elementów definiujących identyfikator pakietu i wersję.

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

Dla każdego projektu należy zdefiniować atrybut , ale <PackageReference />Version pominąć go, ponieważ wersja zostanie osiągnięta z odpowiedniego <PackageVersion /> elementu.

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

Teraz używasz centralnego zarządzania pakietami i zarządzania wersjami w centralnej lokalizacji!

Centralne reguły zarządzania pakietami

Plik Directory.Packages.props zawiera szereg reguł dotyczących lokalizacji w katalogu repozytorium i jego kontekście. Dla uproszczenia tylko jeden Directory.Packages.props plik jest oceniany dla danego projektu.

Oznacza to, że jeśli w repozytorium znajduje się wiele Directory.Packages.props plików, zostanie obliczony plik, który znajduje się najbliżej katalogu projektu. Umożliwia to dodatkową kontrolę na różnych poziomach repozytorium.

Oto przykład, aby wziąć pod uwagę następującą strukturę repozytorium:

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

Program Project1 oceni Directory.Packages.props plik w Repository\Solution1\ katalogu i musi ręcznie zaimportować następny w razie potrzeby.

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

Program Project2 oceni Directory.Packages.props plik w Repository\ katalogu.

Uwaga: program MSBuild nie zaimportuje automatycznie każdego Directory.Packages.props z nich, tylko pierwszego znajdującego się najbliżej projektu. Jeśli masz wiele Directory.Packages.propselementów , musisz zaimportować element nadrzędny ręcznie, gdy katalog główny Directory.Packages.props nie będzie.

Rozpocznij

Aby w pełni dołączyć repozytorium, rozważ wykonanie następujących kroków:

Utwórz nowy plik w katalogu głównym repozytorium o nazwie Directory.Packages.props , który deklaruje centralnie zdefiniowane wersje pakietów i ustaw właściwość ManagePackageVersionsCentrally MSBuild na true.
Zadeklaruj <PackageVersion /> elementy w obiekcie Directory.Packages.props.
Zadeklaruj <PackageReference /> elementy bez Version atrybutów w plikach projektu.

Aby dowiedzieć się, jak może wyglądać centralne zarządzanie pakietami, zapoznaj się z naszym repozytorium przykładów.

Przypinanie przechodnie

Możesz automatycznie zastąpić przechodnią wersję pakietu nawet bez jawnego najwyższego poziomu <PackageReference /> , decydując się na funkcję znaną jako przejściowe przypinanie. W razie potrzeby zwiększa to zależność przechodnią do zależności najwyższego poziomu niejawnie w Twoim imieniu.

Tę funkcję można włączyć, ustawiając właściwość CentralPackageTransitivePinningEnabled MSBuild na true w projekcie lub w Directory.Packages.props pliku importu lub Directory.Build.props w pliku:

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

Zastępowanie wersji pakietów

Możesz zastąpić pojedynczą wersję pakietu przy użyciu VersionOverride właściwości w elemencie <PackageReference /> . Spowoduje to przesłonięcia wszystkich <PackageVersion /> zdefiniowanych centralnie.

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

Tę funkcję można wyłączyć, ustawiając właściwość CentralPackageVersionOverrideEnabled MSBuild na false w projekcie lub w Directory.Packages.props pliku importu lub Directory.Build.props w pliku:

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

Gdy ta funkcja jest wyłączona, określenie VersionOverride elementu na dowolnym <PackageReference /> elemencie spowoduje błąd podczas przywracania wskazujący, że funkcja jest wyłączona.

Wyłączanie centralnego zarządzania pakietami

Jeśli chcesz wyłączyć centralne zarządzanie pakietami dla dowolnego określonego projektu, możesz go wyłączyć, ustawiając właściwość ManagePackageVersionsCentrally MSBuild na :false

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

Odwołania do pakietów globalnych

Uwaga

Ta funkcja jest dostępna tylko w programie Visual Studio 2022 17.4 lub nowszym, zestawie .NET SDK 7.0.100.preview7 lub nowszym oraz nuGet 6.4 lub nowszym.

Globalne odwołanie do pakietu służy do określania, że pakiet będzie używany przez każdy projekt w repozytorium. Obejmuje to pakiety, które wykonują przechowywanie wersji, rozszerzanie kompilacji lub inne pakiety wymagane przez wszystkie projekty. Odwołania do pakietów globalnych są dodawane do grupy elementów PackageReference z następującymi metadanymi:

IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
Gwarantuje to, że pakiet jest używany tylko jako zależność programistyczne i zapobiega wszelkim odwołaniom zestawów w czasie kompilacji.
PrivateAssets="All"
Uniemożliwia to pobieranie odwołań do pakietów globalnych przez zależności podrzędne.

GlobalPackageReference elementy należy umieścić w pliku Directory.Packages.props , aby były używane przez każdy projekt w repozytorium:

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

Ostrzeżenie dotyczące korzystania z wielu źródeł pakietów

W przypadku korzystania z centralnego zarządzania pakietami zostanie wyświetlone NU1507 ostrzeżenie, jeśli w konfiguracji zdefiniowano więcej niż jedno źródło pakietu. Aby rozwiązać to ostrzeżenie, zamapuj źródła pakietów za pomocą mapowania źródła pakietu lub określ pojedyncze źródło pakietu.

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.