CPM (Gerenciamento Central de Pacotes)

O gerenciamento de dependência é um recurso principal do NuGet. Embora o gerenciamento de dependências para um único projeto seja simples, ele se torna cada vez mais complexo à medida que o número de projetos em uma solução aumenta.

Se você gerenciar dependências comuns para muitos projetos diferentes, poderá aproveitar os recursos do CPM (Gerenciamento Central de Pacotes) do NuGet para fazer tudo isso de um único local central.

O Gerenciamento Central de Pacotes se aplica a todos os <PackageReference>projetos do MSBuild baseados (incluindo CSPROJ herdado).

Habilitando o Gerenciamento Central de Pacotes

Para começar a usar o Gerenciamento Central de Pacotes, crie um Directory.Packages.props arquivo na raiz do repositório e defina a propriedade ManagePackageVersionsCentrally MSBuild como true.

Você pode criá-lo manualmente ou usar a CLI do .NET:

dotnet new packagesprops

Dentro Directory.Packages.props, defina <PackageVersion /> elementos para especificar as IDs do pacote e as versões usadas por seus projetos.

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="PackageA" Version="1.0.0" />
    <PackageVersion Include="PackageB" Version="2.0.0" />
  </ItemGroup>
</Project>

Em cada arquivo de projeto, defina <PackageReference /> elementos sem o Version atributo. A versão será resolvida da entrada correspondente <PackageVersion /> em Directory.Packages.props.

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

Agora você está usando o Gerenciamento Central de Pacotes e gerenciando suas versões em um local central!

Regras centrais de gerenciamento de pacotes

O Directory.Packages.props arquivo tem regras específicas sobre sua localização e contexto em um repositório. Apenas um Directory.Packages.props arquivo é avaliado para um determinado projeto por padrão.

Se você tiver vários Directory.Packages.props arquivos em seu repositório, o arquivo mais próximo do diretório de um determinado projeto será avaliado para ele. Isso permite um controle extra em vários níveis do repositório.

Considere a seguinte estrutura de diretório do repositório:

📂 (root)
 ├─📄 Directory.Packages.props
 |
 ├─📂Solution1
 |  ├─ 📄Directory.Packages.props
 |  |
 |  └─ 📂 Project1
 |      └─📄Project1.csproj
 |
 └─ 📂 Solution2
    └─ 📂 Project2
        └─ 📄 Project2.csproj

Project1.csproj usará o Directory.Packages.props arquivo no Repository\Solution1\ diretório. Se você quiser incluir configurações de um pai Directory.Packages.props, deverá importá-la manualmente.

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

Project2.csproj avaliará o Directory.Packages.props arquivo no diretório raiz.

Introdução

Para integrar totalmente o repositório, siga estas etapas:

1. Crie um novo arquivo na raiz do repositório chamado Directory.Packages.props que declara suas versões de pacote definidas centralmente e defina a propriedade do MSBuild ManagePackageVersionsCentrally como true.
2. Declare <PackageVersion /> itens em seu Directory.Packages.props.
3. Declare itens <PackageReference /> que não possuem atributos Version em seus arquivos de projeto.

Para obter um exemplo da aparência do Gerenciamento Central de Pacotes, consulte nosso repositório de exemplos.

Usando versões diferentes para estruturas de destino diferentes

À medida que os pacotes NuGet evoluem, os proprietários de pacotes podem descartar o suporte para estruturas de destino mais antigas. Isso pode causar problemas para desenvolvedores de bibliotecas que ainda se destinam a estruturas mais antigas, mas que desejam referenciar versões mais recentes de pacotes para estruturas de destino mais recentes.

Por exemplo, se o projeto for direcionado para .NET Standard 2.0, .NET 8.0 e .NET Framework 4.7.2, mas PackageA não oferecer mais suporte ao .NET Standard 2.0 em sua versão mais recente, você poderá especificar versões diferentes para cada estrutura de destino.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;net8.0;net472</TargetFrameworks>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="PackageA" />
  </ItemGroup>
</Project>

Nesse caso, defina versões diferentes para cada estrutura de destino em suas Directory.Packages.propscondições do MSBuild:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="PackageA" Version="1.0.0" Condition="'$(TargetFramework)' == 'netstandard2.0'" />
    <PackageVersion Include="PackageA" Version="2.0.0" Condition="'$(TargetFramework)' == 'net8.0' Or '$(TargetFramework)' == 'net472'" />
  </ItemGroup>
</Project>

Fixação transitiva

Você pode substituir automaticamente uma versão de pacote transitivo sem um item de nível <PackageReference /> superior explícito optando por um recurso conhecido como fixação transitiva. Isso promove uma dependência transitiva para uma dependência de nível superior implicitamente em seu nome, quando necessário.

Observe que os downgrades não são permitidos ao realizar a fixação transitiva de um pacote. Se você tentar fixar um pacote em uma versão inferior à solicitada por suas dependências, a restauração gerará um erro de NU1109.

Você pode habilitar esse recurso definindo a propriedade MSBuild CentralPackageTransitivePinningEnabled para true em um projeto ou em um arquivo de importação Directory.Packages.props ou Directory.Build.props:

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

Fixação transitiva e pacote

Quando um pacote é fixado transitivamente, seu projeto usa uma versão mais alta do que a solicitada por suas dependências. Se você criar um pacote com base em seu projeto, para garantir que seu pacote funcione, o NuGet promoverá as dependências fixadas transitivamente para dependências explícitas no nuspec.

No exemplo a seguir, PackageA 1.0.0 tem uma dependência de 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>

Quando você usa o comando do pacote para criar um pacote, ambos os pacotes serão exibidos no grupo de dependências.

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

Por isso, o uso da fixação transitiva deve ser cuidadosamente avaliado ao criar uma biblioteca, pois isso pode levar a dependências que você não esperava.

Substituindo versões do pacote

Você pode substituir a versão individual de um pacote usando a propriedade VersionOverride em um item <PackageReference />. Isso terá precedência sobre qualquer valor definido <PackageVersion />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>

Você pode desabilitar esse recurso definindo a propriedade MSBuild CentralPackageVersionOverrideEnabled para false em um projeto ou em um arquivo de importação Directory.Packages.props ou Directory.Build.props:

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

Quando esse recurso estiver desabilitado, especificar um VersionOverride em qualquer item de <PackageReference /> resultará em um erro no momento da restauração indicando que o recurso está desabilitado.

Desabilitando o Gerenciamento Central de Pacotes

Para desabilitar o Gerenciamento Central de Pacotes para um projeto específico, defina a propriedade ManagePackageVersionsCentrally MSBuild como false:

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

Referências de Pacotes Globais

Uma referência de pacote global é usada para especificar que um pacote será usado por cada projeto em um repositório. Isso inclui pacotes que fazem controle de versão, estendem seu build ou quaisquer outros pacotes necessários para todos os projetos. As referências de pacote global são adicionadas ao grupo de itens PackageReference com os seguintes metadados:

• IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"
  Isso garante que o pacote seja usado apenas como uma dependência de desenvolvimento e impeça que ele seja incluído como uma referência de assembly em tempo de compilação.
• PrivateAssets="All"
  Isto impede que as referências globais de pacote sejam captadas por dependências posteriores.

GlobalPackageReference itens devem ser colocados no seu Directory.Packages.props para serem usados por todos os projetos em um repositório.

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

Aviso NU1507 ao usar várias fontes de pacote

Ao usar o Gerenciamento Central de Pacotes, o NuGet registrará um NU1507 aviso se mais de uma fonte de pacote for definida em sua configuração. Para resolver esse aviso, mapeie as fontes do pacote com de mapeamento de origem do pacote ou especifique uma única fonte de pacote.

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.