skip to content

Pack & Publish

Turning a library into a NuGet package: dotnet pack with PackageId, Version and licence metadata, .snupkg symbols and Source Link, then nuget push. Asked since nuget.org versions can only be unlisted.

on this pageshow

explore

questions

6

With the .NET 10 SDK, what does dotnet pack produce for a class library, and what do PackageId, Version, Authors and IsPackable default to?

level: juniorimportance: must knowfreq 52%

answer

  1. a .nupkg in bin/Release
  2. PackageId falls back to AssemblyName
  3. Version comes from VersionPrefix 1.0.0
  4. Authors defaults to the assembly name
  5. test projects are not packable

basics

~20 s

dotnet pack builds the project in Release and writes <PackageId>.<version>.nupkg to bin/Release. PackageId defaults to the assembly name, the version to Version (1.0.0 unless set), Authors to the assembly name, and IsPackable is true except for test projects.

solid answer

~40 s

`dotnet pack` builds the library and runs NuGet's pack target, which writes a `.nupkg` — a zip holding the generated `.nuspec`, the assemblies under `lib/<tfm>/` and the declared metadata. Because `PackRelease` defaults to `true`, the CLI packs **Release** and drops the file in `bin/Release/` (`PackageOutputPath` is `$(BaseOutputPath)$(Configuration)\`). Defaults come from the targets: `PackageId` = `$(AssemblyName)`, `PackageVersion` = `$(Version)`, which is `VersionPrefix` 1.0.0 plus any `VersionSuffix`; `Authors` = `$(AssemblyName)`; the description falls back to `Package Description`. `IsPackable` is `true` unless the project is a test project or a testing-platform app, where it becomes `false`. `PackageReference` items turn into nuspec dependencies, and a `ProjectReference` becomes a dependency on that project's package. .NET 10 adds `dotnet pack --version` to set `PackageVersion` directly.

code

xml · 9 lines
xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <PackageId>Shared.Validation</PackageId>
    <VersionPrefix>2.3.0</VersionPrefix>
    <Authors>Platform team</Authors>
    <Description>Validation rules shared by the lending services.</Description>
  </PropertyGroup>
</Project>

go deeper

for a junior

Recall that dotnet pack writes a .nupkg, that PackageId comes from the assembly name and the version from Version, and where the file lands.

for a middle

Explain each default and its source, how VersionPrefix, VersionSuffix, PackageVersion and the .NET 10 --version option interact, and how references become dependencies.

for a senior

Set package identity and metadata deliberately, keep non-libraries unpackable, and notice where the docs and the SDK targets disagree before trusting either.

for a principal

Decide how a portfolio of internal libraries is versioned and packed in CI, and who owns package identity once consumers depend on it.

## What dotnet pack does `dotnet pack` is how an SDK-style project becomes a NuGet package. It restores and builds the project (unless `--no-build` is given) and then runs NuGet's **pack** target, which generates a `.nuspec` from MSBuild properties and zips it with the build output into a `.nupkg`. The team that owns a shared validation library used by several internal services runs: ```bash dotnet pack Shared.Validation/Shared.Validation.csproj -o ./artifacts ``` and gets `Shared.Validation.1.0.0.nupkg` in `./artifacts`. ## Where the defaults come from Every package field has an MSBuild property behind it, and the SDK and `NuGet.Build.Tasks.Pack.targets` fill the empty ones: | Property | Default when unset | Source of the default | |---|---|---| | `PackageId` | `$(AssemblyName)` | pack targets | | `PackageVersion` | `$(Version)` | pack targets | | `Version` | `$(VersionPrefix)`, plus `-$(VersionSuffix)` if set | SDK assembly-info targets | | `VersionPrefix` | `1.0.0` | SDK assembly-info targets | | `Authors` | `$(AssemblyName)` | SDK assembly-info targets | | `PackageDescription` | `$(Description)`, else `Package Description` | pack targets | | `IsPackable` | `false` for test projects, else `true` | pack targets | | `PackageOutputPath` | `$(BaseOutputPath)$(Configuration)\` | pack targets | Two of these contradict the reference docs, and the source wins. The NuGet docs table says `Authors` defaults to the current user name; the SDK sets it to the assembly name. The docs also say `IsPackable` defaults to `true`; the targets make it `false` when `IsTestProject` or `IsTestingPlatformApplication` is `true`, so packing a whole solution skips test projects. ## Configuration and output - **Release by default.** `PackRelease` defaults to `true`, so the CLI packs the Release configuration unless you pass `-c Debug`. Packages built in Debug by accident used to be a common mistake. - **Output folder.** Without `-o`, the package lands in `bin/Release/`, not under the target-framework subfolder. - **Not on every build.** `GeneratePackageOnBuild` defaults to `false`; set it to `true` only if every build should also produce a package. ## Setting the version There are several equivalent levers, from most to least explicit: 1. `dotnet pack --version 2.3.0` — new in .NET 10; it sets `PackageVersion`. 2. `-p:PackageVersion=2.3.0` on any SDK version. 3. `<Version>` in the project, or `<VersionPrefix>` with `--version-suffix beta.1` for prereleases such as `2.3.0-beta.1`. Setting `PackageVersion` overrides the prefix and suffix. Because the package version is the contract consumers resolve against, CI usually computes it rather than leaving the 1.0.0 default in place. ## What goes inside - `lib/<tfm>/Shared.Validation.dll` and its XML documentation file if one is generated — pack copies `.dll`, `.exe`, `.winmd`, `.json`, `.pri` and `.xml` build outputs. - A `.nuspec` with id, version, authors, description, license and repository metadata. - A dependency group per target framework listing every `PackageReference` that is not fully private, and a dependency on the package of every `ProjectReference`. `SuppressDependenciesWhenPacking` removes all dependencies, which is almost never what a library wants. ## Packing in a pipeline A release job for the validation library usually separates build and pack so the tested binaries are the packed ones: 1. `dotnet build -c Release` once, run the tests against that output. 2. `dotnet pack -c Release --no-build -o artifacts --version 2.3.0` to package exactly those binaries; `--no-build` also implies no restore. 3. Keep the `.nupkg` as the build artifact and push that same file later. The SDK can also check the package as it is produced: with `EnablePackageValidation` set to `true`, a `RunPackageValidation` step runs after `Pack`, and `PackageValidationBaselineVersion` makes it compare the new package's API with a previously released version, so an accidental breaking change fails the pack instead of reaching consumers. ## Common traps - Shipping with `Package Description` and an author equal to the assembly name because nobody set the metadata. - Packing an application or test project by accident; set `IsPackable` to `false` explicitly on anything that is not a library. - Forgetting that the id is permanent on a public feed: renaming `PackageId` later creates a different package rather than a new version of the old one.

  • Why might dotnet pack on a solution produce no package for the test project?
    NuGet's pack targets set `IsPackable` to `false` when `IsTestProject` or `IsTestingPlatformApplication` is `true` and the project has not set `IsPackable` itself. Test SDKs set those flags, so a solution-wide pack skips them; the docs' claim that the default is always `true` is out of date.
  • What becomes of a ProjectReference when the library is packed?
    It becomes a package dependency in the nuspec, on the referenced project's `PackageId` and version, so that project must also be packed and published. The referenced assembly is not copied into your package unless you take extra steps; NuGet treats project references as package references by default.

  • PackageId defaults to the folder name of the solution.
  • dotnet pack uses the Debug configuration unless told otherwise.
  • Authors defaults to the logged-in user's name, as the docs say.
  • Test projects are packed like any other project unless excluded by hand.
  • dotnet pack copies ProjectReference assemblies into the package's lib folder.

Assumes the .NET 10.0.400 SDK with NuGet 7; dotnet pack --version arrived in .NET 10, PackRelease has made Release the CLI default since .NET 8, and the Authors and IsPackable defaults are read from the pinned targets rather than the docs.

open as a page

With the .NET CLI, how do you publish with dotnet nuget push, and what can you do once a nuget.org release is broken?

level: middleimportance: must knowfreq 46%

basics

~20 s

dotnet nuget push <file>.nupkg --source <feed> --api-key <key> uploads the package; a version can be pushed only once. nuget.org does not delete packages: you unlist the broken version, which hides it from search but keeps exact-version restores working, and ship a fixed version.

open as a page

In a .NET library's project file, how do PackageLicenseExpression, PackageReadmeFile and PackageIcon get into the .nupkg, and why do NU5039 and NU5046 appear?

level: middleimportance: should knowfreq 35%

basics

~20 s

PackageLicenseExpression writes an SPDX licence into the nuspec. PackageReadmeFile and PackageIcon only name files inside the package, so each file must also be packed with a None item marked Pack="true"; forgetting that gives NU5039 for the readme and NU5046 for the icon.

open as a page

When a NuGet package is packed from a library targeting netstandard2.0, net8.0 and net10.0, what lands under lib/, and which folder does net9.0 use?

level: middleimportance: should knowfreq 38%

basics

~20 s

Pack writes one lib/<tfm>/ folder per target framework and one dependency group per framework in the nuspec. A net9.0 consumer gets lib/net8.0, the highest compatible framework not above its own, while a .NET Framework consumer falls back to lib/netstandard2.0.

open as a page

In NuGet, what do dotnet nuget sign and dotnet nuget verify do, and when does restore itself check package signatures on Windows, Linux and macOS?

level: seniorimportance: nice to knowfreq 18%

basics

~20 s

dotnet nuget sign adds an author signature to a .nupkg with an X.509 code-signing certificate and a timestamp; dotnet nuget verify checks signatures. Restore verifies signatures by default on Windows and, since the .NET 8 SDK, on Linux; on macOS it is off by default.

open as a page