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

Článek
10/18/2023

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žívaný 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.

Od NuGetu 6.2 můžete centrálně spravovat závislosti v projektech přidáním Directory.Packages.props souboru 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 <PackageReference>projekty MSBuild (včetně starší verze CSPROJ), 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 Directory.Packages.props soubor v kořenovém adresáři úložiště a nastavit vlastnost ManagePackageVersionsCentrally MSBuild na true.

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 /> atribut, ale vynecháte ho Version , protože verze bude dosažena z odpovídající <PackageVersion /> položky.

<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 má ř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 Directory.Packages.props soubor.

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 vyhodnocuje Directory.Packages.propsRepository\Solution1\ soubor v adresáři a v případě potřeby musí ručně importovat 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 Repository\ adresáři.

Poznámka: NÁSTROJ MSBuild nebude automaticky importovat každý Directory.Packages.props za vás, pouze první, který je nejblíže k projektu. Pokud máte více Directory.Packages.props, musíte nadřazený objekt importovat ručně, zatímco kořenový adresář Directory.Packages.props by ne.

Začínáme

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 ManagePackageVersionsCentrally MSBuild na true.
Deklarujte <PackageVersion /> položky v souboru Directory.Packages.props.
Deklarujte <PackageReference /> položky bez Version atributů v souborech projektu.

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í

Můžete automaticky přepsat tranzitivní verzi balíčku i bez explicitní nejvyšší úrovně <PackageReference /> tím, že se přihlásíte k funkci, která se označuje jako tranzitivní připnutí. To v případě potřeby podporuje tranzitivní závislost na závislost nejvyšší úrovně implicitně vaším jménem.

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

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

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

Jednotlivé verze balíčku můžete přepsat pomocí VersionOverride vlastnosti <PackageReference /> položky. 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 CentralPackageVersionOverrideEnabled MSBuild v false projektu nebo v souboru importu Directory.Packages.propsDirectory.Build.props :

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

Pokud je tato funkce zakázaná, zadání položky VersionOverride<PackageReference /> způsobí chybu při 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 ManagePackageVersionsCentrally MSBuild 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 jiné balíčky, které jsou potřeba všemi projekty. 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 vyzvednuty podřízenými závislostmi.

GlobalPackageReference položky by měly být umístěny do vašeho 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í NU1507 se 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 jeden 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.