Gestione pacchetti centrale (CPM)

Articolo
10/23/2023

La gestione delle dipendenze è una funzionalità di base di NuGet. La gestione delle dipendenze per un singolo progetto può essere semplice. La gestione delle dipendenze per le soluzioni multiprogetto può rivelarsi difficile quando iniziano a ridimensionare le dimensioni e la complessità. In situazioni in cui si gestiscono le dipendenze comuni per molti progetti diversi, è possibile sfruttare le funzionalità di gestione centrale dei pacchetti (CPM) di NuGet per eseguire tutto questo, dalla facilità di una singola posizione.

Storicamente, le dipendenze dei pacchetti NuGet sono state gestite in una delle due posizioni seguenti:

packages.config - File XML utilizzato nei tipi di progetto meno recenti per mantenere l'elenco dei pacchetti a cui fa riferimento il progetto.
<PackageReference /> - Un elemento XML usato nei progetti MSBuild definisce le dipendenze del pacchetto NuGet.

A partire da NuGet 6.2, è possibile gestire centralmente le dipendenze nei progetti con l'aggiunta di un Directory.Packages.props file e una proprietà MSBuild.

La funzionalità è disponibile in tutti gli strumenti integrati NuGet, a partire dalle versioni seguenti.

Gli strumenti meno recenti ignoreranno le configurazioni e le funzionalità di gestione dei pacchetti centrali. Per usare questa funzionalità nel modo più completo, assicurarsi che tutti gli ambienti di compilazione usino le versioni più recenti degli strumenti compatibili.

La gestione centrale dei pacchetti si applica a tutti i <PackageReference>progetti MSBuild basati su ,incluso CSPROJ legacy, purché vengano usati strumenti compatibili.

Abilitazione della gestione pacchetti centrale

Per iniziare a usare la gestione centrale dei pacchetti, è necessario creare un Directory.Packages.props file nella radice del repository e impostare la proprietà ManagePackageVersionsCentrally MSBuild su true.

All'interno si definiscono quindi ognuna delle rispettive versioni del pacchetto necessarie per i progetti usando <PackageVersion /> elementi che definiscono l'ID e la versione del pacchetto.

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

Per ogni progetto, è quindi necessario definire un <PackageReference /> attributo ma omettere poiché Version la versione verrà ottenuta da un elemento corrispondente <PackageVersion /> .

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

A questo punto si usa la gestione centrale dei pacchetti e si gestiscono le versioni in una posizione centrale.

Regole di gestione pacchetti centrali

Il Directory.Packages.props file ha una serie di regole relative alla posizione in cui si trova nella directory di un repository e nel relativo contesto. Per semplicità, viene valutato un Directory.Packages.props solo file per un determinato progetto.

Ciò significa che se nel repository sono presenti più Directory.Packages.props file, il file più vicino alla directory del progetto verrà valutato. In questo modo è possibile controllare in modo aggiuntivo a vari livelli del repository.

Di seguito è riportato un esempio, considerare la struttura di repository seguente:

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

Project1 valuterà il Directory.Packages.props file nella Repository\Solution1\ directory e dovrà importare manualmente quello successivo, se necessario.

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

Project2 valuterà il Directory.Packages.props file nella Repository\ directory.

Nota: MSBuild non importerà automaticamente ognuno Directory.Packages.props di essi, ma solo il primo più vicino al progetto. Se si dispone di più Directory.Packages.props, è necessario importare manualmente l'elemento padre mentre la radice Directory.Packages.props non lo farebbe.

Operazioni preliminari

Per eseguire l'onboarding completo del repository, seguire questa procedura:

Creare un nuovo file nella radice del repository denominato Directory.Packages.props che dichiara le versioni del pacchetto definite centralmente e impostare la proprietà ManagePackageVersionsCentrally MSBuild su true.
Dichiarare <PackageVersion /> gli elementi nell'oggetto Directory.Packages.props.
Dichiarare <PackageReference /> gli elementi senza Version attributi nei file di progetto.

Per un'idea dell'aspetto della gestione centrale dei pacchetti, vedere il repository degli esempi.

Pinning transitivo

È possibile eseguire automaticamente l'override di una versione transitiva del pacchetto anche senza un livello superiore <PackageReference /> esplicito optando per una funzionalità nota come pinning transitivo. In questo modo si promuove una dipendenza transitiva a una dipendenza di primo livello in modo implicito per conto dell'utente, quando necessario.

È possibile abilitare questa funzionalità impostando la proprietà CentralPackageTransitivePinningEnabled MSBuild su true in un progetto o in un Directory.Packages.props file di Directory.Build.props importazione:

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

Override delle versioni dei pacchetti

È possibile eseguire l'override di una singola versione del pacchetto usando la VersionOverride proprietà di un <PackageReference /> elemento. In questo modo viene eseguito l'override di qualsiasi <PackageVersion /> elemento definito centralmente.

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

È possibile disabilitare questa funzionalità impostando la proprietà CentralPackageVersionOverrideEnabled MSBuild su false in un progetto o in un Directory.Packages.props file di Directory.Build.props importazione:

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

Quando questa funzionalità è disabilitata, la specifica di un VersionOverride elemento <PackageReference /> genera un errore in fase di ripristino che indica che la funzionalità è disabilitata.

Disabilitazione della gestione pacchetti centrale

Se si vuole disabilitare la gestione centrale dei pacchetti per un determinato progetto, è possibile disabilitarla impostando la proprietà ManagePackageVersionsCentrally MSBuild su false:

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

Riferimenti ai pacchetti globali

Nota

Questa funzionalità è disponibile solo in Visual Studio 2022 17.4 o versione successiva, .NET SDK 7.0.100.preview7 o versione successiva e NuGet 6.4 o versione successiva.

Un riferimento al pacchetto globale viene usato per specificare che un pacchetto verrà usato da ogni progetto in un repository. Sono inclusi i pacchetti che eseguono il controllo delle versioni, estendono la compilazione o qualsiasi altro pacchetto necessario per tutti i progetti. I riferimenti globali ai pacchetti vengono aggiunti al gruppo di elementi PackageReference con i metadati seguenti:

IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
In questo modo, il pacchetto viene usato solo come dipendenza di sviluppo e impedisce riferimenti ad assembly in fase di compilazione.
PrivateAssets="All"
In questo modo si impedisce che i riferimenti globali ai pacchetti vengano prelevati dalle dipendenze downstream.

GlobalPackageReference gli elementi devono essere inseriti nell'oggetto Directory.Packages.props da usare da ogni progetto in un repository:

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

Avviso quando si usano più origini di pacchetti

Quando si usa la gestione centrale dei pacchetti, viene visualizzato un NU1507 avviso se nella configurazione sono definite più di un'origine pacchetto. Per risolvere questo avviso, eseguire il mapping delle origini dei pacchetti con il mapping dell'origine del pacchetto o specificare un'origine del pacchetto singola.

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.