How do you create and publish a NuGet package with dotnet pack, including versioning, package metadata, symbols and signing?

1. The lifecycle of a package

 your library project
   |  dotnet pack -c Release -p:Version=1.4.0
   v
 build each target framework (net8.0, net10.0)
   |
   v
 generate .nuspec from MSBuild properties and PackageReferences
   |
   v
 Contoso.Abn.1.4.0.nupkg  +  Contoso.Abn.1.4.0.snupkg
   |  (optional) dotnet nuget sign
   |  dotnet nuget push
   v
 feed (nuget.org / Azure Artifacts / GitHub Packages)
   |
   v
 consumer: <PackageReference Include="Contoso.Abn" Version="1.4.0" />
   |  restore: read .nuspec dependencies, pick the nearest lib/<tfm>
   v
 consumer build compiles against lib/net10.0/Contoso.Abn.dll
   |
   v
 consumer debugger: downloads the .pdb from the .snupkg, then source via Source Link

2. What is inside a .nupkg

A .nupkg is a zip file. Open one with any zip tool to check what you are shipping.

 Contoso.Abn.1.4.0.nupkg
 +-- Contoso.Abn.nuspec           manifest: id, version, licence, dependencies per TFM
 +-- lib/
 |   +-- net8.0/Contoso.Abn.dll   used by consumers on net8.0 and net9.0
 |   +-- net10.0/Contoso.Abn.dll  used by consumers on net10.0 and later
 +-- README.md                    shown on the feed's package page
 +-- icon.png                     (optional) PackageIcon
 +-- build/ or buildTransitive/   (optional) .props/.targets imported into consumer builds
 +-- analyzers/dotnet/cs/         (optional) Roslyn analysers and source generators
 +-- [Content_Types].xml, _rels/, package/   zip bookkeeping

 Contoso.Abn.1.4.0.snupkg         separate symbol package
 +-- lib/net8.0/Contoso.Abn.pdb
 +-- lib/net10.0/Contoso.Abn.pdb

When a consumer restores, NuGet picks the nearest compatible lib/<tfm> folder for the consumer's target framework. That is why multi-targeting net8.0;net10.0 lets you use newer APIs on .NET 10 while still supporting .NET 8 consumers.

3. Metadata properties

4. Semantic Versioning in practice

 1 . 4 . 0 - beta.3
 |   |   |   |
 |   |   |   +-- prerelease label: sorts BEFORE 1.4.0
 |   |   +------ PATCH: bug fixes only
 |   +---------- MINOR: new features, backwards compatible
 +-------------- MAJOR: breaking changes

Prerelease ordering follows SemVer 2 rules: beta.10 sorts after beta.2 because dot-separated numbers compare numerically, but beta10 sorts before beta2 because it compares as text. Use dotted labels.

Versions on nuget.org are immutable: you can't replace 1.4.0 with different content. You can only unlist it, deprecate it, or ship 1.4.1.

5. Versioning from source control

The three version properties:

6. Symbols, Source Link and deterministic builds

dotnet nuget push pushes the matching .snupkg automatically when it is next to the .nupkg.

7. Package validation

 EnablePackageValidation = true
   |
   +-- compatible frameworks check: does every TFM expose the same API?
   |   (a method only in lib/net10.0 breaks net8.0 consumers who upgrade TFM)
   |
   +-- with PackageValidationBaselineVersion = 1.3.0:
       download 1.3.0, compare its public API with this build
       removed or changed public members --> error, pack fails

When a break is intentional (a new major version), update the baseline, or record suppressions in CompatibilitySuppressions.xml (generated with -p:ApiCompatGenerateSuppressionFile=true) so the decision is reviewed in a pull request.

8. Dependencies you pass on

Every PackageReference in your library becomes a dependency of every consumer:

9. Pushing

dotnet nuget push "artifacts/*.nupkg" --source <feed> --api-key "$KEY" --skip-duplicate

--skip-duplicate lets a re-run pipeline succeed when the version already exists.

10. Signing

dotnet nuget sign artifacts/Contoso.Abn.1.4.0.nupkg \
  --certificate-path signing.pfx --certificate-password "$CERT_PASSWORD" \
  --timestamper http://timestamp.digicert.com
dotnet nuget verify --all artifacts/Contoso.Abn.1.4.0.nupkg

Consumers enforce signatures with trustedSigners and signatureValidationMode=require in nuget.config. Always timestamp, so the signature stays valid after the certificate expires.

11. Security

• Keep API keys and signing certificates in the pipeline's secret store or a key vault, scoped and expiring.
• Open the .nupkg before the first release of a new package and check for secrets, test data or config files that slipped in.
• Reserve your ID prefix on nuget.org, and use package source mapping internally, to reduce dependency confusion risk.

12. .NET 11 awareness

Packing is stable. Watch the .NET 11 SDK notes for changes to package validation and NuGet defaults before relying on them.

13. Try it yourself

1. Create a class library and add the properties from the code example.
2. Run dotnet pack -c Release -o artifacts -p:Version=1.0.0 and open the .nupkg as a zip. Read the generated .nuspec.
3. Add a PackageReference to an analyser without PrivateAssets="all", pack, and see it appear as a dependency in the .nuspec.
4. Add EnablePackageValidation and PackageValidationBaselineVersion=1.0.0 (push 1.0.0 to a local folder feed first), remove a public method, pack 1.1.0 and read the error.
5. Push to a local folder feed: dotnet nuget push artifacts/*.nupkg --source ./local-feed, then consume it from another project with a nuget.config pointing at that folder.
6. Pack 1.5.0-beta.2 and 1.5.0-beta.10 and check which one the feed lists as newer.

src/Contoso.Abn/Contoso.Abn.csproj:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>

    <PackageId>Contoso.Abn</PackageId>
    <Description>Validation and formatting for Australian Business Numbers (ABNs).</Description>
    <Authors>Contoso Platform Team</Authors>
    <PackageTags>abn;australia;validation</PackageTags>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>

    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>

    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.3.0</PackageValidationBaselineVersion>
  </PropertyGroup>

  <ItemGroup>
    <None Include="README.md" Pack="true" PackagePath="\" />
  </ItemGroup>
</Project>

src/Contoso.Abn/Abn.cs:

namespace Contoso.Abn;

public static class Abn
{
    private static readonly int[] Weights = [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19];

    /// <summary>Checks an ABN using the ATO's modulus 89 algorithm.</summary>
    public static bool IsValid(string? abn)
    {
        if (abn is null) return false;
        var digits = abn.Where(char.IsDigit).Select(c => c - '0').ToArray();
        if (digits.Length != 11) return false;

        digits[0] -= 1;
        var sum = digits.Select((d, i) => d * Weights[i]).Sum();
        return sum % 89 == 0;
    }
}

CI commands:

dotnet pack src/Contoso.Abn -c Release -o artifacts -p:Version=1.4.0 -p:ContinuousIntegrationBuild=true
dotnet nuget push "artifacts/*.nupkg" --source "https://api.nuget.org/v3/index.json" --api-key "$NUGET_API_KEY"