Központi csomagkezelés (CPM)

A függőségkezelés a NuGet alapvető funkciója. Egy projekt függőségeinek kezelése egyszerű lehet. A többprojektes megoldások függőségeinek kezelése nehéznek bizonyulhat, amikor elkezdenek méretezni és összetettebbé tenni őket. Olyan helyzetekben, amikor számos különböző projekt közös függőségeit kezeli, a NuGet központi csomagkezelési (CPM) funkcióival mindezt egyetlen helyről végezheti el.

A NuGet-csomagfüggőségeket korábban két helyen kezelték:

• packages.config – Régebbi projekttípusokban használt XML-fájl a projekt által hivatkozott csomagok listájának fenntartásához.
• <PackageReference /> – Az MSBuild-projektekben használt XML-elem határozza meg a NuGet-csomag függőségeit.

A NuGet 6.2 kezdve központilag kezelheti a projektek függőségeit egy Directory.Packages.props fájl és egy MSBuild tulajdonság hozzáadásával.

A funkció az összes NuGet-integrált eszközkészletben elérhető, kezdve az alábbi verziókkal.

• Visual Studio 2022 17.2
• .NET SDK 6.0.300
• nuget.exe 6.2.0

A régebbi eszközök figyelmen kívül hagyják a központi csomagkezelési konfigurációkat és funkciókat. A funkció teljes körű használatához győződjön meg arról, hogy az összes buildkörnyezet a legújabb kompatibilis eszközverziókat használja.

A központi csomagkezelés az összes <PackageReference>-alapú MSBuild-projektre vonatkozik (beleértve régi CSPROJ-) mindaddig, amíg kompatibilis eszközt használ.

Központi csomagkezelés engedélyezése

A központi csomagkezelés első lépéseihez létre kell hoznia egy Directory.Packages.props fájlt az adattár gyökerében, és az MSBuild tulajdonság ManagePackageVersionsCentrallytrueértékre kell állítania.

Manuálisan is létrehozhatja, vagy használhatja a dotnet parancssori felületét:

dotnet new packagesprops

Ezután a projektekhez szükséges csomagverziókat <PackageVersion /> a csomagazonosítót és a verziót meghatározó elemek használatával határozza meg.

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

Minden projekthez definiáljon egy <PackageReference />, de hagyja ki a Version attribútumot, mivel a verzió egy megfelelő <PackageVersion /> elemből lesz elérhető.

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

Most központi csomagkezelést használ, és központi helyen kezeli a verziókat!

Központi csomagkezelési szabályok

A Directory.Packages.props fájl számos szabállyal rendelkezik az adattár könyvtárában elfoglalt helyét és környezetét illetően. Az egyszerűség kedvéért a rendszer csak egy Directory.Packages.props fájlt értékel ki egy adott projekthez.

Ez azt jelenti, hogy ha több Directory.Packages.props fájl található az adattárban, a projekt könyvtárához legközelebbi fájl lesz kiértékelve. Ez lehetővé teszi az adattár különböző szintjein történő további vezérlést.

Íme egy példa, tekintsük át az alábbi adattárszerkezetet:

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

• A Project1 kiértékeli a Directory.Packages.props fájlt a Repository\Solution1\ könyvtárban, és szükség esetén manuálisan kell importálnia a következőt.

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

• A Project2 kiértékeli a Directory.Packages.props fájlt a Repository\ könyvtárban.

Megjegyzés: Az MSBuild nem importálja automatikusan Önnek mindegyik Directory.Packages.props-t, csak az elsőt, amely a legközelebb van a projekthez. Ha több Directory.Packages.props-ja van, manuálisan kell importálnia a szülőt, de a gyökér Directory.Packages.props-re nem lesz szükség.

Kezdje el

A tárhely teljes integrálásához fontolja meg az alábbi lépéseket:

1. Hozzon létre egy új fájlt a Directory.Packages.props nevű adattár gyökerénél, amely deklarálja a központilag definiált csomagverziókat, és állítsa az MSBuild tulajdonság ManagePackageVersionsCentrallytrueértékre.
2. Jelentse be a <PackageVersion /> elemeket a Directory.Packages.props.
3. Deklaráljon <PackageReference /> elemeket Version attribútumok nélkül a projektfájlokban.

A központi csomagkezelés megjelenésének megismeréséhez tekintse meg minta adattárunkat.

Tranzitív rögzítés

A tranzitív csomagverziók automatikusan felülbírálhatók explicit legfelső szintű <PackageReference /> nélkül is, ha egy tranzitív rögzítésnek nevezett funkciót választ. Ez a tranzitív függőséget egy legfelső szintű függőséggé előlépteti, ha szükséges, hallgatólagosan az Ön nevében. Vegye figyelembe, hogy a csomag átmeneti rögzítése esetén a verziócsökkentések engedélyezettek. Ha egy csomagot a függőségei által kértnél alacsonyabb verzióra próbál rögzíteni, a visszaállítás NU1109 hibát okoz.

Ezt a funkciót úgy engedélyezheti, hogy az MSBuild tulajdonság CentralPackageTransitivePinningEnabled értékét true-re állítja egy projektben, vagy egy Directory.Packages.props vagy Directory.Build.props importfájlban.

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

Tranzitív rögzítés és csomagolás

Ha egy csomag tranzitív módon van rögzítve, a projekt a függőségek által kértnél magasabb értéket használ. Ha a projektből csomagot hoz létre, annak érdekében, hogy a csomag működjön, a NuGet a tranzitív függőségeket kifejezetten függőségként fogja megjelölni a nuspec fájlban.

Az alábbi példában PackageA 1.0.0 függ a PackageB 1.0.0.

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

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

Ha a csomagparancs használatával hoz létre csomagot, mindkét csomag megjelenik a függőségi csoportban.

      <group targetFramework="net6.0">
        <dependency id="PackageA" version="1.0.0" exclude="Build,Analyzers" />
        <dependency id="PackageB" version="2.0.0" exclude="Build,Analyzers" />
      </group>

Emiatt a tranzitív rögzítést alaposan ki kell értékelni egy könyvtár létrehozásakor, mivel olyan függőségekhez vezethet, amire nem számítottál.

Csomagverziók felülírása

Az egyes csomag verzióját felülbírálhatja úgy, hogy használja a VersionOverride tulajdonságot egy <PackageReference /> elemen. Ez felülírja a központilag definiált <PackageVersion />-t.

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

Úgy tilthatja le ezt a funkciót, hogy beállítja az MSBuild tulajdonságot CentralPackageVersionOverrideEnabled értékét false-re egy projektben vagy egy Directory.Packages.props vagy Directory.Build.props importálási fájlban.

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

Amikor ez a funkció le van tiltva, bármely <PackageReference /> elemhez való VersionOverride megadása visszaállításkor hibát eredményez, amely jelzi, hogy a funkció le van tiltva.

Központi csomagkezelés letiltása

Ha egy adott projekt központi csomagkezelését szeretné letiltani, letilthatja az MSBuild tulajdonság ManagePackageVersionsCentrally beállításával false:

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

Globális csomaghivatkozások

A rendszer globális csomaghivatkozást használ annak megadására, hogy egy csomagot egy adattár minden projektje használjon. Ide tartoznak azok a csomagok, amelyek verziószámozást végeznek, kibővítik a buildet, vagy az összes projekthez szükséges egyéb csomagokat. Globális csomaghivatkozások kerülnek a PackageReference elemcsoportba a következő metaadatokkal:

• IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
  Ez biztosítja, hogy a csomagot csak fejlesztési függőségként használják, és megakadályozza a fordítási idő alatti szerelvényhivatkozásokat.
• PrivateAssets="All"
  Ez megakadályozza, hogy a globális csomaghivatkozásokat az alsóbb rétegbeli függőségek átvenjék.

GlobalPackageReference elemeket a Directory.Packages.props-be kell helyeznie, hogy minden projekt használhassa az adattárban.

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

Figyelmeztetés több csomagforrás használatakor

Központi csomagkezelés használatakor NU1507 figyelmeztetés jelenik meg, ha több csomagforrás van definiálva a konfigurációban. A figyelmeztetés megoldásához képezze le a csomagforrásokat csomagforrás-leképezési vagy adjon meg egyetlen csomagforrást.

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.