NuGet

suggest change

NuGet is the official, open-source package manager for the Microsoft development platform. It enables developers to consume third-party libraries, share reusable code across organizations, and publish packages to the public NuGet Gallery.


1. Managing Packages via the .NET CLI

Modern .NET projects use the dotnet CLI to add, update, and remove packages:

Adding a Package

# Add the latest stable version of a package
dotnet add package Newtonsoft.Json

# Add a specific version
dotnet add package Serilog --version 3.1.1

# Add a package with prerelease versions allowed
dotnet add package Microsoft.Extensions.Logging --prerelease

Listing and Inspecting Dependencies

# List directly referenced packages
dotnet list package

# Also include transitive dependencies
dotnet list package --include-transitive

# Check for outdated packages
dotnet list package --outdated

# Scan dependencies for known security vulnerabilities
dotnet list package --vulnerable

Removing a Package

dotnet remove package Newtonsoft.Json

2. Project File Configuration (.csproj)

In SDK-style projects, dependencies are stored directly in your .csproj file using the <PackageReference> element:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <!-- Direct package reference with explicit version -->
    <PackageReference Include="Spectre.Console" Version="0.49.1" />

    <!-- Private asset: build-time analyzer not bundled with output -->
    <PackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.556">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>

3. Central Package Management (CPM)

In multi-project solutions, maintaining consistent package versions across dozens of projects can lead to version drift. .NET provides Central Package Management (CPM) to define package versions in a single root file.

Create a Directory.Packages.props file in your repository root:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="MediatR" Version="12.2.0" />
    <PackageVersion Include="FluentValidation" Version="11.9.0" />
    <PackageVersion Include="xunit" Version="2.7.0" />
  </ItemGroup>
</Project>

Individual .csproj files then omit the Version attribute:

<ItemGroup>
  <PackageReference Include="MediatR" />
  <PackageReference Include="FluentValidation" />
</ItemGroup>

4. Configuring Package Sources (nuget.config)

To pull packages from private feeds (such as Azure Artifacts, GitHub Packages, or BaGet), add a nuget.config file to the root of your repository:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear /> <!-- Clears system defaults for predictable builds -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="InternalFeed" value="https://pkgs.dev.azure.com/my-org/_packaging/internal/nuget/v3/index.json" />
  </packageSources>

  <!-- Enforce package source mapping for security -->
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="InternalFeed">
      <package pattern="MyOrg.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

5. Creating and Publishing Packages

You can turn any class library into a redistributable NuGet package by embedding metadata directly into its .csproj:

<PropertyGroup>
  <PackageId>MyOrg.Utilities.Logging</PackageId>
  <Version>1.0.0</Version>
  <Authors>Acme Dev Team</Authors>
  <Company>Acme Corp</Company>
  <Description>High-performance structured logging helpers for .NET applications.</Description>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>
  <PackageProjectUrl>https://github.com/myorg/logging-utils</PackageProjectUrl>
  <RepositoryUrl>https://github.com/myorg/logging-utils.git</RepositoryUrl>
  <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
</PropertyGroup>

Packaging and Pushing

# Build the .nupkg in Release mode (add -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg for a .snupkg symbol package)
dotnet pack -c Release -o ./artifacts

# Push the package to NuGet.org
dotnet nuget push ./artifacts/MyOrg.Utilities.Logging.1.0.0.nupkg \
  --api-key YOUR_NUGET_API_KEY \
  --source https://api.nuget.org/v3/index.json

6. Best Practices

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents