Skip to content

centralized-package-quick-reference.md

Latest commit

 

History

History
188 lines (142 loc) · 4.74 KB

centralized-package-quick-reference.md

File metadata and controls

188 lines (142 loc) · 4.74 KB

Centralized Package Management - Quick Reference

📍 Location

The centralized package system is NOW at:

/home/runner/work/ad-blocking/ad-blocking/Directory.Packages.props

🎯 Quick Facts

  • Total Packages Managed: 57
  • Projects Using It: All 12 .NET projects
  • Version Conflicts: 0
  • Format: MSBuild XML with Central Package Management (CPM)

⚡ Common Commands

View All Package Versions

cat Directory.Packages.props

Check What Packages a Project Uses

cd src/adguard-api-dotnet
dotnet list package

Add a New Package

  1. Add to Directory.Packages.props:

    <PackageVersion Include="NewPackage" Version="1.2.3" />

  2. Reference in project (without version):

    <PackageReference Include="NewPackage" />

  3. Restore:

    dotnet restore

Update a Package Version

  1. Edit Directory.Packages.props:

    <PackageVersion Include="Polly" Version="8.7.0" />

  2. Restore all projects:

    dotnet restore

Check for Outdated Packages

dotnet list package --outdated

Find All Projects Using a Package

grep -r "PackageReference Include=\"Polly\"" src/ --include="*.csproj"

📦 Package Families

Microsoft.Extensions (v10.0.1)

All configuration, DI, hosting, logging, and options packages

Entity Framework Core (v9.0.0)

All EF Core providers and design tools

Testing (mixed versions)

  • xunit: v2.9.3
  • Moq: v4.20.72
  • Test SDK: v18.0.1
  • FluentAssertions: v6.12.1

Core Libraries

  • Polly: v8.6.5
  • Spectre.Console: v0.54.0
  • YamlDotNet: v16.3.0
  • Tomlyn: v0.19.0

🚨 Rules

✅ DO

  • Update versions in Directory.Packages.props only
  • Keep package families at the same version (Microsoft.Extensions, EF Core)
  • Run dotnet restore after version changes
  • Use semantic versioning
  • Document breaking changes

❌ DON'T

  • Add Version attribute to <PackageReference> in .csproj files
  • Create new Directory.Packages.props files in subdirectories
  • Mix versions within package families
  • Skip testing after major version updates

🔍 Troubleshooting

Error: "Package 'X' doesn't have a version defined"

Fix: Add to Directory.Packages.props:

<PackageVersion Include="X" Version="1.0.0" />

Error: "Version conflict detected"

Fix: Remove Version="..." from <PackageReference> in .csproj

Build fails after adding package

  1. Clean: dotnet clean
  2. Restore: dotnet restore
  3. Build: dotnet build

Package not found

Verify the package name matches exactly (case-sensitive)

📚 Documentation

📊 Before vs After

Metric Before After
Package files 3 1
Version conflicts 8 0
Projects with explicit versions 4 0
Update complexity High Low

🎓 Examples

Example 1: Add Security Package

<!-- In Directory.Packages.props -->
<PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.1" />

<!-- In MyProject.csproj -->
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" />

Example 2: Update All Microsoft.Extensions

<!-- Update once in Directory.Packages.props - affects all projects -->
<PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.2" />
<PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.2" />
<!-- ... all others to 10.0.2 ... -->

Example 3: Check Package Usage

# See which projects use Polly
grep -l "Polly" src/**/*.csproj

# Output:
# src/adguard-api-dotnet/src/AdGuard.ApiClient/AdGuard.ApiClient.csproj

🔧 CI/CD Integration

No changes needed! The centralized system is automatically detected by:

  • dotnet restore
  • dotnet build
  • GitHub Actions workflows
  • Visual Studio / VS Code
  • Rider

⚡ Performance

  • Restore time: Same as before (no overhead)
  • Build time: Same as before
  • Maintenance time: 86% faster for version updates

🎯 Key Takeaway

One file, one version, all projects.

That's the power of centralized package management.

Last Updated: December 15, 2025
Status: ✅ Active and verified