Gestione pacchetti centrale (CPM)
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.
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.
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 nellaRepository\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 nellaRepository\
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.
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 sutrue
. - Dichiarare
<PackageVersion />
gli elementi nell'oggettoDirectory.Packages.props
. - Dichiarare
<PackageReference />
gli elementi senzaVersion
attributi nei file di progetto.
Per un'idea dell'aspetto della gestione centrale dei pacchetti, vedere il repository degli esempi.
È 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>
È 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.
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>
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>
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.
Nota
La gestione centrale dei pacchetti è in fase di sviluppo attivo. Siamo lieti di provarlo e fornire commenti e suggerimenti che potresti avere in NuGet/Home.