Správa centrálních balíčků (CPM)

Článek
02/05/2025

Správa závislostí je základní funkcí NuGetu. Správa závislostí pro jeden projekt může být snadná. Správa závislostí pro řešení s více projekty může být obtížná, protože se začnou škálovat velikostí a složitostí. V situacích, kdy spravujete běžné závislosti pro mnoho různých projektů, můžete využít funkce centrální správy balíčků (CPM) NuGetu k tomu, abyste to udělali snadno z jednoho umístění.

V minulosti byly závislosti balíčků NuGet spravovány v jednom ze dvou umístění:

packages.config – soubor XML použitý ve starších typech projektů k udržování seznamu balíčků odkazovaných projektem.
<PackageReference /> – element XML použitý v projektech MSBuild definuje závislosti balíčků NuGet.

Počínaje NuGet 6.2můžete centrálně spravovat závislosti v projektech přidáním souboru Directory.Packages.props a vlastnosti MSBuild.

Tato funkce je dostupná napříč všemi integrovanými nástroji NuGet počínaje následujícími verzemi.

Starší nástroje budou ignorovat konfigurace a funkce správy centrálních balíčků. Pokud chcete tuto funkci používat v plném rozsahu, ujistěte se, že všechna vaše prostředí sestavení používají nejnovější kompatibilní verze nástrojů.

Centrální správa balíčků se vztahuje na všechny projekty MSBuild založené na <PackageReference>(včetně starší verzeCSPROJ), pokud se použijí kompatibilní nástroje.

Povolení správy centrálních balíčků

Pokud chcete začít s centrální správou balíčků, musíte vytvořit soubor Directory.Packages.props v kořenovém adresáři úložiště a nastavit vlastnost MSBuild ManagePackageVersionsCentrally na true.

Můžete ho vytvořit ručně nebo můžete použít rozhraní příkazového řádku dotnet:

dotnet new packagesprops

Uvnitř pak definujete každou z odpovídajících verzí balíčků vyžadovaných pro vaše projekty pomocí <PackageVersion /> prvků, které definují ID a verzi balíčku.

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

Pro každý projekt pak definujete <PackageReference /> ale vynecháte atribut Version, protože verze bude dosažena z odpovídající položky <PackageVersion />.

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

Teď používáte centrální správu balíčků a správu verzí v centrálním umístění.

Pravidla správy centrálních balíčků

Soubor Directory.Packages.props obsahuje řadu pravidel, pokud jde o umístění v adresáři úložiště a jeho kontextu. Kvůli jednoduchosti se pro daný projekt vyhodnocuje jenom jeden soubor Directory.Packages.props.

To znamená, že pokud máte v úložišti více Directory.Packages.props souborů, vyhodnotí se pro něj soubor, který je nejblíže adresáři vašeho projektu. To vám umožní další kontrolu na různých úrovních úložiště.

Tady je příklad, podívejte se na následující strukturu úložiště:

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

Project1 vyhodnotí Directory.Packages.props soubor v adresáři Repository\Solution1\ a v případě potřeby musí ručně naimportovat další soubor.

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

Project2 vyhodnotí Directory.Packages.props soubor v adresáři Repository\.

Poznámka: MSBuild nebude automaticky importovat všechny Directory.Packages.props za vás, pouze první, který je nejblíže projektu. Pokud máte více Directory.Packages.props, musíte nadřazenou položku importovat ručně, zatímco kořenový Directory.Packages.props to nevyžaduje.

Začít

Pokud chcete úložiště plně připojit, zvažte provedení těchto kroků:

Vytvořte nový soubor v kořenovém adresáři úložiště s názvem Directory.Packages.props, který deklaruje centrálně definované verze balíčků a nastaví vlastnost MSBuild ManagePackageVersionsCentrally na true.
Deklarujte položky <PackageVersion /> v Directory.Packages.props.
Deklarujte položky <PackageReference /> bez atributů Version ve vašich projektových souborech.

Představu o tom, jak může centrální správa balíčků vypadat, najdete v našem úložišti ukázek .

Tranzitivní připnutí

Tranzitivní verzi balíčku můžete automaticky přepsat i bez explicitní úrovně nejvyššího <PackageReference /> tím, že se přihlásíte k funkci označované jako tranzitivní připnutí. V případě potřeby to implicitně povýší tranzitivní závislost na úroveň hlavní závislosti vaším jménem. Mějte na paměti, že downgrady jsou povoleny při tranzitivním připnutí balíčku. Pokud se pokusíte připnout balíček na nižší verzi, než je ta, kterou vaše závislosti požaduje, obnovení vyvolá NU1109 chybu.

Tuto funkci můžete povolit nastavením vlastnosti MSBuild CentralPackageTransitivePinningEnabled na true v projektu nebo v Directory.Packages.props nebo Directory.Build.props souboru importu:

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

Přechodné připnutí a balení

Když je balíček přechodně připnutý, váš projekt používá vyšší verzi balíčku, než jakou požadují vaše závislosti. Pokud vytvoříte balíček z projektu, aby bylo zajištěno, že váš balíček bude fungovat, NuGet povýší transitivně připnuté závislosti na explicitní závislosti v nuspec.

V následujícím příkladu PackageA 1.0.0 má závislost na 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>

Když k vytvoření balíčku použijete příkaz pack, zobrazí se oba balíčky ve skupině závislostí.

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

Z tohoto důvodu by při vytváření knihovny mělo být pečlivě vyhodnoceno použití přechodného připnutí, protože může vést k závislostem, které jste neočekádali.

Přepisování verzí balíčků

Jednotlivou verzi balíčku můžete přepsat pomocí vlastnosti VersionOverride u položky <PackageReference />. Tím se přepíše všechny <PackageVersion /> definované centrálně.

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

Tuto funkci můžete zakázat nastavením vlastnosti MSBuild CentralPackageVersionOverrideEnabled na false v projektu nebo v Directory.Packages.props nebo Directory.Build.props import souboru:

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

Pokud je tato funkce zakázaná, zadání VersionOverride u libovolné položky <PackageReference /> způsobí chybu v době obnovení, která značí, že je tato funkce zakázaná.

Zakázání správy centrálních balíčků

Pokud chcete zakázat centrální správu balíčků pro libovolný konkrétní projekt, můžete ji zakázat nastavením vlastnosti MSBuild ManagePackageVersionsCentrally na false:

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

Globální odkazy na balíčky

Poznámka

Tato funkce je dostupná jenom v sadě Visual Studio 2022 17.4 nebo novější, .NET SDK 7.0.100.preview7 nebo vyšší a NuGet 6.4 nebo vyšší.

Globální odkaz na balíček se používá k určení, že balíček bude používán každým projektem v úložišti. To zahrnuje balíčky, které provádějí správu verzí, rozšiřují sestavení, nebo jakékoli další balíčky, které všechny projekty potřebují. Globální odkazy na balíčky se přidají do skupiny položek PackageReference s následujícími metadaty:

IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
Tím se zajistí, že se balíček použije pouze jako vývojová závislost a zabrání všem odkazům na sestavení v době kompilace.
PrivateAssets="All"
To brání tomu, aby globální odkazy na balíčky byly přejaty následnými závislostmi.

GlobalPackageReference položky by měly být umístěny ve vašem Directory.Packages.props, aby je používal každý projekt v úložišti:

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

Upozornění při použití více zdrojů balíčků

Pokud používáte centrální správu balíčků, zobrazí se NU1507 upozornění, pokud máte v konfiguraci definovaných více zdrojů balíčků. Pokud chcete toto upozornění vyřešit, namapujte zdroje balíčků pomocí mapování zdroje balíčků , nebo zadejte jediný zdroj balíčku.

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.