Solutions, References and Packages

This section documents MSBuild 18.9, the .NET SDK 10.0.402 (with its dotnet CLI) and NuGet 7.9, as published in the MSBuild, .NET and NuGet documentation on learn.microsoft.com, which is the reference these pages are written and verified against. Material about .NET 11 / NuGet 8.0 is still in preview and is always flagged as such — never presented as baseline.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The C# Reference bibliography lists the reference material consulted while preparing these pages.

Most project changes are a line of XML, and the CLI’s project-modification commands write that line for you: they add projects to solutions, project references to projects, and package references with a resolved version. This page runs them with .NET SDK 10.0.402 on a small "Books" repository created on dotnet new and Templates. The NuGet side — how the version is chosen, CPM, sources — is documented in depth on dotnet package and nuget Commands.

Noun first, verb first

NET 10 documents noun-first commands (dotnet package add) as the main form and keeps the older verb-first

forms (dotnet add package) as aliases:

Noun first Verb first (older form)

Noun first	Verb first (older form)
`dotnet package add`	`dotnet add package`
`dotnet package list`	`dotnet list package`
`dotnet package remove`	`dotnet remove package`
`dotnet reference add`	`dotnet add reference`
`dotnet reference list`	`dotnet list reference`
`dotnet reference remove`	`dotnet remove reference`
`dotnet package search`, `update`, `download`	(none)

dotnet package add

dotnet add package

dotnet package list

dotnet list package

dotnet package remove

dotnet remove package

dotnet reference add

dotnet add reference

dotnet reference list

dotnet list reference

dotnet reference remove

dotnet remove reference

dotnet package search, update, download

(none)

Both forms worked on SDK 10.0.402 (dotnet add Books.Core package Humanizer.Core --version 2.14.1 added the reference exactly like dotnet package add). The documentation dates the noun-first forms to .NET 10, while the dotnet package pages' headers say "applies to .NET 6 SDK and later" — and in practice SDK 9.0.319 already listed package (search, add, list, remove) and reference (add, list, remove) in its help. dotnet package update and dotnet package download are not in 9.0.319. Use the verb-first forms in scripts that must run on SDK 8.

Source: What’s new in the .NET 10 SDK: More consistent command order.

Solutions

dotnet sln Books.slnx add Books.Core/Books.Core.csproj Books.Probe/Books.Probe.csproj
dotnet sln Books.slnx list

Project `Books.Core/Books.Core.csproj` added to the solution.
Project `Books.Probe/Books.Probe.csproj` added to the solution.
Project(s)
----------
Books.Core/Books.Core.csproj
Books.Probe/Books.Probe.csproj

dotnet solution is the same command under its full name. Solution folders, .sln versus .slnx and migration are covered on Solutions and .slnx.

Source: dotnet sln.

Project references

dotnet reference add Books.Core/Books.Core.csproj --project Books.Probe/Books.Probe.csproj
dotnet reference list --project Books.Probe

Reference `..\Books.Core\Books.Core.csproj` added to the project.
Project reference(s)
--------------------
../Books.Core/Books.Core.csproj

The command writes a ProjectReference with a path relative to the referencing project.

There is no command for a reference to an assembly that is in no project or package. Edit the project file:

<ItemGroup>
  <Reference Include="Ledger.Legacy">
    <HintPath>..\lib\Ledger.Legacy.dll</HintPath>
  </Reference>
</ItemGroup>

Such references bypass NuGet’s version resolution; conflicts between them are resolved by ResolveAssemblyReference (Troubleshooting MSBuild).

Source: dotnet reference add: Add a reference to an assembly that isn’t in a project, dotnet reference list, dotnet reference remove.

Package references

dotnet package add resolves a version (the latest stable, unless --version or --prerelease is given), writes the PackageReference and restores:

dotnet package add Humanizer.Core --version 2.14.1 --project Books.Core
dotnet package list --project Books.Core --outdated

log  : Restored ~/newrepo/Books.Core/Books.Core.csproj (in 1.27 sec).
Project 'Books.Core' has the following package references
   [net10.0]:
   Top-level Package      Requested   Resolved   Latest
   > Humanizer.Core       2.14.1      2.14.1     3.0.10

dotnet package update (.NET 10) updates to the latest version — across a major version boundary:

dotnet package update Humanizer.Core --project Books.Core
grep Humanizer Books.Core/Books.Core.csproj

    Updating Humanizer.Core 2.14.1 to 3.0.10.

Updated 1 packages in 1 scanned packages.
    <PackageReference Include="Humanizer.Core" Version="3.0.10" />

A major version usually contains breaking changes; build and test before committing, or move to a chosen version with dotnet package add Humanizer.Core --version <version>. --vulnerable updates only packages with known vulnerabilities to the lowest fixed version.

dotnet package remove Humanizer.Core --project Books.Core removes the reference (info : Removing PackageReference for package 'Humanizer.Core' from project …). In a repository that uses Central Package Management the commands write the version into Directory.Packages.props instead of the project (Central Package Management).

Source: dotnet package add.

Search and download

dotnet package search Humanizer.Core --exact-match
dotnet package download Humanizer.Core@2.14.1 -o pkgs

Source: nuget.org (https://api.nuget.org/v3/index.json)
| Package ID     | Version | Owners | Total Downloads |
| -------------- | ------- | ------ | --------------- |
| Humanizer.Core | 2.0.0   |        | N/A             |
…
Installed Humanizer.Core 2.14.1 from https://api.nuget.org/v3/index.json to pkgs/humanizer.core/2.14.1 with content hash lQKvtaTDOXnoVJ20ibTuSIOf2i0uO0MPbDhd1jm238I+U/2ZnRENj0cktKZhtchBMtCUSRQ5v4xBCUbKNmyVMw==.
Package 'Humanizer.Core' (2.14.1) successfully downloaded to 'pkgs'.

--exact-match lists every version of the exact ID. dotnet package download (SDK 10.0.2xx and later) fetches a package — with its signature file and content hash — into a folder in the global-packages layout, without a project; it suits offline mirrors and inspecting a package before depending on it.

Source: Manage dependencies in .NET applications.

Common mistakes

dotnet package update without reviewing the diff — it crosses major versions.
Noun-first commands in scripts that run on SDK 8 — use the verb-first form.
Reference with HintPath for something that exists as a package — use the package.
Hand-editing a version in a CPM repository’s project file — NU1008; the version belongs in Directory.Packages.props.