Central pakethantering (CPM)

Artikel
02/05/2025

Beroendehantering är en viktig funktion i NuGet. Det kan vara enkelt att hantera beroenden för ett enskilt projekt. Det kan visa sig vara svårt att hantera beroenden för lösningar med flera projekt när de börjar skalas i storlek och komplexitet. I situationer där du hanterar vanliga beroenden för många olika projekt kan du använda NuGets CPM-funktioner (Central Package Management) för att göra allt detta från en enda plats.

Tidigare har NuGet-paketberoenden hanterats på någon av två platser:

packages.config – en XML-fil som används i äldre projekttyper för att underhålla listan över paket som refereras av projektet.
<PackageReference /> – Ett XML-element som används i MSBuild-projekt definierar NuGet-paketberoenden.

Från och med NuGet 6.2kan du centralt hantera dina beroenden i dina projekt med tillägg av en Directory.Packages.props-fil och en MSBuild-egenskap.

Funktionen är tillgänglig för alla NuGet-integrerade verktyg, från och med följande versioner.

Äldre verktyg ignorerar konfigurationer och funktioner för central pakethantering. Om du vill använda den här funktionen fullt ut kontrollerar du att alla byggmiljöer använder de senaste kompatibla verktygsversionerna.

Central pakethantering gäller för alla <PackageReference>-baserade MSBuild-projekt (inklusive äldre CSPROJ-) så länge kompatibla verktyg används.

Aktivera central pakethantering

För att komma igång med central pakethantering måste du skapa en Directory.Packages.props fil i roten på lagringsplatsen och ange egenskapen MSBuild ManagePackageVersionsCentrally till true.

Du kan skapa den manuellt eller så kan du använda dotnet CLI:

dotnet new packagesprops

Inuti definierar du sedan var och en av de respektive paketversioner som krävs av dina projekt med hjälp av <PackageVersion /> element som definierar paket-ID och version.

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

För varje projekt definierar du sedan ett <PackageReference /> men utelämnar attributet Version eftersom versionen uppnås från motsvarande <PackageVersion /> objekt.

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

Nu använder du central pakethantering och hantering av dina versioner på en central plats!

Centrala pakethanteringsregler

Den Directory.Packages.props filen har ett antal regler för var den finns i en lagringsplatss katalog och dess kontext. För enkelhetens skull utvärderas endast en Directory.Packages.props fil för ett visst projekt.

Detta innebär att om du har flera Directory.Packages.props-filer i ditt arkiv kommer den fil som ligger närmast din projektmapp att utvärderas för detta ändamål. På så sätt kan du få extra kontroll på olika nivåer på lagringsplatsen.

Här är ett exempel på följande lagringsplatsstruktur:

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

Project1 utvärderar Directory.Packages.props-filen i katalogen Repository\Solution1\ och måste importera nästa manuellt om så önskas.

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

Project2 utvärderar Directory.Packages.props-filen i katalogen Repository\.

Obs! MSBuild importerar inte automatiskt varje Directory.Packages.props åt dig, bara den första som är närmast projektet. Om du har flera Directory.Packages.propsmåste du importera den överordnade manuellt medan roten Directory.Packages.props inte behöver importeras manuellt.

Sätta igång

Om du vill publicera lagringsplatsen fullt ut kan du överväga att vidta följande steg:

Skapa en ny fil i roten på lagringsplatsen med namnet Directory.Packages.props som deklarerar dina centralt definierade paketversioner och ange egenskapen MSBuild ManagePackageVersionsCentrally till true.
Deklarera <PackageVersion /> föremål i din Directory.Packages.props.
Deklarera <PackageReference /> objekt utan Version attribut i projektfilerna.

För att få en uppfattning om hur central pakethantering kan se ut, hänvisa till vårt arkiv med -exempel.

Transitiv fästning

Du kan automatiskt åsidosätta en transitiv paketversion även utan en specifik <PackageReference /> på toppnivån genom att aktivera en funktion som kallas transitiv fixering. Detta höjer ett transitivt beroende till ett toppnivåberoende automatiskt för din räkning när det behövs. Observera att nedgraderingar tillåts när du fäster ett paket transitivt. Om du försöker fästa ett paket på en lägre version än den som begärs av dina beroenden, skapar återställningen ett NU1109- fel.

Du kan aktivera den här funktionen genom att ange egenskapen MSBuild CentralPackageTransitivePinningEnabled till true i ett projekt eller i en Directory.Packages.props- eller Directory.Build.props importfil:

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

Transitiv fästning och paket

När ett paket är transitivt låst använder ditt projekt en högre version än den som begärs av dina beroenden. Om du skapar ett paket från projektet kommer NuGet att höja de transitivt fästa beroendena till explicita beroenden i nuspecen för att säkerställa att paketet fungerar.

I följande exempel har PackageA 1.0.0 ett beroende av 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>

När du använder packkommandot för att skapa ett paket visas båda paketen i beroendegruppen.

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

Därför bör användningen av transitiv fastlåsning noggrant utvärderas när du skapar ett bibliotek eftersom det kan leda till beroenden som du inte förväntade dig.

Åsidosätta paketversioner

Du kan åsidosätta en enskild paketversion med hjälp av egenskapen VersionOverride på ett <PackageReference /> objekt. Detta åsidosätter alla <PackageVersion /> som definierats centralt.

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

Du kan inaktivera den här funktionen genom att ange egenskapen MSBuild CentralPackageVersionOverrideEnabled till false i ett projekt eller i en Directory.Packages.props- eller Directory.Build.props importfil:

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

När den här funktionen är inaktiverad resulterar det i ett fel vid återställningstillfället som anger att funktionen är inaktiverad om du anger en VersionOverride på ett <PackageReference /> objekt.

Inaktivera central pakethantering

Om du vill inaktivera central pakethantering för ett visst projekt kan du inaktivera det genom att ange egenskapen MSBuild ManagePackageVersionsCentrally till false:

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

Globala paketreferenser

Not

Den här funktionen är endast tillgänglig i Visual Studio 2022 17.4 eller senare, .NET SDK 7.0.100.preview7 eller senare och NuGet 6.4 eller senare.

En global paketreferens används för att ange att ett paket ska användas av varje projekt i en lagringsplats. Detta inkluderar paket som utför versionshantering, utökar din version eller andra paket som behövs av alla projekt. Globala paketreferenser läggs till i objektgruppen PackageReference med följande metadata:

IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
Detta säkerställer att paketet endast används som ett utvecklingsberoende och förhindrar referenser till sammansättningar vid kompileringstid.
PrivateAssets="All"
Detta förhindrar att globala paketreferenser hämtas av underordnade beroenden.

GlobalPackageReference objekt ska placeras i er Directory.Packages.props för att kunna användas av varje projekt i ett arkiv:

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

Varning vid användning av flera paketkällor

När du använder central pakethantering visas en NU1507 varning om du har mer än en paketkälla definierad i konfigurationen. Lös den här varningen genom att mappa dina paketkällor med paketkällans mappning eller ange en enda paketkälla.

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.

Note

Central pakethantering är i aktiv utveckling. Vi uppskattar att du provar det och ger all feedback du kan ha på NuGet/Home.

Dela via