Centraal Pakketbeheer (CPM)

Artikel
02/05/2025

Afhankelijkheidsbeheer is een kernfunctie van NuGet. Het beheren van afhankelijkheden voor één project kan eenvoudig zijn. Het beheren van afhankelijkheden voor oplossingen voor meerdere projecten kan lastig blijken te zijn omdat ze beginnen met schalen in grootte en complexiteit. In situaties waarin u algemene afhankelijkheden voor veel verschillende projecten beheert, kunt u gebruikmaken van de CPM-functies (Central Package Management) van NuGet om dit allemaal te doen vanaf het gemak van één locatie.

In het verleden zijn nuGet-pakketafhankelijkheden beheerd op een van de twee locaties:

packages.config: een XML-bestand dat wordt gebruikt in oudere projecttypen om de lijst met pakketten waarnaar wordt verwezen door het project te onderhouden.
<PackageReference /> : een XML-element dat wordt gebruikt in MSBuild-projecten definieert NuGet-pakketafhankelijkheden.

Vanaf NuGet 6.2kunt u uw afhankelijkheden centraal beheren in uw projecten met toevoeging van een Directory.Packages.props-bestand en een MSBuild-eigenschap.

De functie is beschikbaar in alle geïntegreerde NuGet-hulpprogramma's, te beginnen met de volgende versies.

Oudere hulpprogramma's negeren centrale configuraties en functies voor pakketbeheer. Als u deze functie volledig wilt gebruiken, moet u ervoor zorgen dat al uw buildomgevingen de nieuwste compatibele hulpprogrammaversies gebruiken.

Centraal pakketbeheer is van toepassing op alle op <PackageReference>gebaseerde MSBuild-projecten (inclusief verouderde CSPROJ-) zolang compatibele hulpprogramma's worden gebruikt.

Central Package Management inschakelen

Als u aan de slag wilt gaan met centraal pakketbeheer, moet u een Directory.Packages.props-bestand maken in de hoofdmap van uw opslagplaats en de eigenschap MSBuild instellen ManagePackageVersionsCentrally op true.

U kunt deze handmatig maken of u kunt de dotnet CLI gebruiken:

dotnet new packagesprops

Vervolgens definieert u elk van de respectieve pakketversies die vereist zijn voor uw projecten met behulp van <PackageVersion /> elementen die de pakket-id en versie definiëren.

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

Voor elk project definieert u vervolgens een <PackageReference />, maar laat u het kenmerk Version weg, omdat de versie wordt verkregen uit een corresponderend <PackageVersion /> item.

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

Nu gebruikt u centraal pakketbeheer en beheert u uw versies op een centrale locatie.

Regels voor centraal pakketbeheer

Het Directory.Packages.props bestand heeft een aantal regels met betrekking tot waar het zich bevindt in de map van een opslagplaats en de bijbehorende context. Omwille van de eenvoud wordt slechts één Directory.Packages.props bestand geëvalueerd voor een bepaald project.

Dit betekent dat als u meerdere Directory.Packages.props bestanden in uw opslagplaats hebt, het bestand dat zich het dichtst bij de map van uw project bevindt, hiervoor wordt geëvalueerd. Hierdoor kunt u extra controle uitvoeren op verschillende niveaus van uw opslagplaats.

Hier volgt een voorbeeld van de volgende structuur van de opslagplaats:

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

Project1 evalueert het Directory.Packages.props-bestand in de Repository\Solution1\ map en moet indien gewenst handmatig het volgende bestand importeren.

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

Project2 evalueert het Directory.Packages.props bestand in de Repository\ map.

Opmerking: MSBuild importeert niet automatisch elke Directory.Packages.props voor u, alleen de eerste die het dichtst bij het project ligt. Als u meerdere Directory.Packages.propshebt, moet u de ouder Directory.Packages.propshandmatig importeren, terwijl de hoofdzakelijke Directory.Packages.props dat niet hoeft.

Begin nu

Als u uw opslagplaats volledig wilt onboarden, kunt u overwegen deze stappen uit te voeren:

Maak een nieuw bestand in de hoofdmap van uw opslagplaats met de naam Directory.Packages.props die uw centraal gedefinieerde pakketversies declareert en stel de MSBuild-eigenschap ManagePackageVersionsCentrally in op true.
Declareer <PackageVersion /> artikelen in uw Directory.Packages.props.
Declareer <PackageReference /> items zonder Version kenmerken in uw projectbestanden.

Raadpleeg onze opslagplaats met voorbeeldenvoor een idee van hoe centraal pakketbeheer eruit kan zien.

Transitief vastpinnen

U kunt automatisch een transitieve pakketversie overschrijven, zelfs zonder expliciete <PackageReference /> op het hoogste niveau door te kiezen voor een functie die transitief vastmaken wordt genoemd. Dit bevordert een transitieve afhankelijkheid naar een afhankelijkheid op het hoogste niveau impliciet namens u wanneer dat nodig is. Houd er rekening mee dat downgrades zijn toegestaan bij het transitief vastzetten van een pakket. Als u probeert een pakket vast te maken aan een lagere versie dan het pakket dat door uw afhankelijkheden is aangevraagd, wordt er een NU1109-fout gegenereerd.

U kunt deze functie inschakelen door de eigenschap MSBuild in te stellen CentralPackageTransitivePinningEnabled op true in een project of in een Directory.Packages.props of Directory.Build.props importbestand:

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

Transitief vastzetten en verpakken

Wanneer een pakket transitief is vastgezet, gebruikt uw project een hogere versie dan de versie die door de afhankelijkheden van uw project is aangevraagd. Als u een pakket maakt op basis van uw project, om ervoor te zorgen dat uw pakket werkt, promoveert NuGet de transitieve vastgemaakte afhankelijkheden naar expliciete afhankelijkheden in de nuspec.

In het volgende voorbeeld heeft PackageA 1.0.0 een afhankelijkheid van 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>

Wanneer u de opdracht Pack gebruikt om een pakket te maken, worden beide pakketten weergegeven in de afhankelijkheidsgroep.

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

Daarom moet het gebruik van transitieve verankering zorgvuldig worden geëvalueerd bij het maken van een bibliotheek, omdat dit kan leiden tot afhankelijkheden die u niet had verwacht.

Pakketversies overschrijven

U kunt een afzonderlijke pakketversie overschrijven met behulp van de eigenschap VersionOverride op een <PackageReference /> item. Dit overschrijft alle centraal gedefinieerde <PackageVersion />.

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

U kunt deze functie uitschakelen door de eigenschap MSBuild in te stellen CentralPackageVersionOverrideEnabled op false in een project of in een Directory.Packages.props of Directory.Build.props importbestand:

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

Wanneer deze functie is uitgeschakeld, resulteert het opgeven van een VersionOverride voor elk <PackageReference />-item in een fout tijdens het herstellen die aangeeft dat de functie is uitgeschakeld.

Central Package Management uitschakelen

Als u centraal pakketbeheer voor een bepaald project wilt uitschakelen, kunt u dit uitschakelen door de eigenschap MSBuild in te stellen ManagePackageVersionsCentrally op false:

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

Algemene pakketverwijzingen

Notitie

Deze functie is alleen beschikbaar in Visual Studio 2022 17.4 of hoger, .NET SDK 7.0.100.preview7 of hoger en NuGet 6.4 of hoger.

Er wordt een algemene pakketreferentie gebruikt om op te geven dat een pakket door elk project in een opslagplaats wordt gebruikt. Dit omvat pakketten die versiebeheer uitvoeren, uw build uitbreiden of andere pakketten die nodig zijn voor alle projecten. Globale pakketverwijzingen worden toegevoegd aan de groep PackageReference-items met de volgende metagegevens:

IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
Dit zorgt ervoor dat het pakket alleen wordt gebruikt als een ontwikkelingsafhankelijkheid en voorkomt het gebruik van compileertijd-assemblyverwijzingen.
PrivateAssets="All"
Dit voorkomt dat globale pakketverwijzingen worden opgehaald door downstream-afhankelijkheden.

GlobalPackageReference items moeten in uw Directory.Packages.props worden geplaatst, zodat ze door elk project in een opslagplaats kunnen worden gebruikt.

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

Waarschuwing bij het gebruik van meerdere pakketbronnen

Wanneer u centraal pakketbeheer gebruikt, ziet u een NU1507 waarschuwing als er meer dan één pakketbron is gedefinieerd in uw configuratie. Als u deze waarschuwing wilt oplossen, wijst u uw pakketbronnen toe met pakketbrontoewijzing of geeft u één pakketbron op.

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.