PackageReference

PackageReference is the standard way to declare NuGet package dependencies in SDK-style projects, such as those that target .NET Core and newer .NET versions. It replaces older approaches like packages.config by embedding dependency information directly in the project file. When a project uses PackageReference, NuGet resolves the declared packages and their transitive dependencies during restore.

In a project file, PackageReference entries are placed inside an ItemGroup. A typical entry looks like:

<PackageReference Include="Newtonsoft.Json" Version="13.0.1" />

Additional metadata can be specified, such as Version ranges, and assets behavior. For example, Version="^13.0.0" expresses a floating version, while PrivateAssets, IncludeAssets, and ExcludeAssets control how the package’s assets impact consuming projects or build steps.

During restore, NuGet computes the exact set of package versions to use and records the result in an assets file under the obj directory. This ensures consistent resolution across builds. Some projects may also employ an optional lock file to lock exact versions, providing reproducible restores in environments with strict requirements.

Advantages of PackageReference include simplified project maintenance, elimination of separate per-project packages.config files, and automatic handling of transitive dependencies. It supports advanced scenarios such as central package management, where version numbers can be centralized in files like Directory.Packages.props to coordinate versions across multiple projects. It is the default and recommended approach for modern .NET projects and remains compatible with a wide range of NuGet feeds and tooling.