NuGet Guide: use packages and build your own.

Work through the steps in order and try each command yourself.

This guide is designed as a hands-on walkthrough. Start at step 1, run the commands in your own project, and verify the result before moving to the next step. You can jump to any step later using the tutorial navigation.

Continue through all 11 steps using the tutorial list on this page.

NuGet is the package manager used by .NET.

A NuGet package normally contains compiled .NET assemblies together with metadata such as its package ID, version, dependencies, license, repository information, and supported target frameworks. Projects consume packages through a PackageReference in the project file.

In modern SDK-style projects, the dotnet CLI is usually all you need for installing, restoring, packing, and publishing NuGet packages.

Add a NuGet dependency to a .NET project.

Open a terminal in the directory that contains your project file and add the package you want to use.

A typical project-file result looks like this:

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>

Restore dependencies, then use the normal .NET build pipeline.

dotnet restore
dotnet build
dotnet test

dotnet restore resolves package dependencies and downloads missing packages. Most build commands restore automatically, but an explicit restore stage is useful in CI because it makes dependency failures easier to diagnose.

Start from an SDK-style class library.

mkdir GrowBit.Sample
cd GrowBit.Sample
dotnet new classlib

Add your reusable code, then build and test the library before you pack it.

dotnet build
dotnet test

Define package information in the project file.

SDK-style projects can keep NuGet package metadata directly in the.csproj file.

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <PackageId>GrowBit.Sample</PackageId>
  <Version>1.0.0</Version>
  <Authors>GrowBit Labs</Authors>
  <Company>GrowBit Labs</Company>
  <Description>A short description of what the package does.</Description>
  <PackageTags>growbit;dotnet;sample</PackageTags>
  <RepositoryUrl>https://github.com/your-org/your-repo</RepositoryUrl>
  <PackageReadmeFile>README.md</PackageReadmeFile>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

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

Choose a package ID that is unique on the package source where you plan to publish it. Public packages should also include clear README, repository, license, and tag metadata.

Create the .nupkg with dotnet pack.

dotnet pack -c Release -o ./artifacts

The output directory will contain a package similar to GrowBit.Sample.1.0.0.nupkg. For SDK-style PackageReference projects, prefer dotnet pack or MSBuild pack targets rather than nuget pack.

Install the package into a clean consumer project.

Testing the actual .nupkg catches problems that a normal library build can miss, such as incomplete package contents, incorrect metadata, dependency issues, and target-framework mismatches.

Create a consumer and install from the local artifacts folder

dotnet new console -n NuGetConsumer
cd NuGetConsumer
dotnet package add GrowBit.Sample --source ../GrowBit.Sample/artifacts
dotnet build
dotnet run

You can also register a local directory as a named source when you use it repeatedly:

dotnet nuget add source ../GrowBit.Sample/artifacts --name LocalPackages

Push the package to a NuGet server.

dotnet nuget push ./artifacts/GrowBit.Sample.1.0.0.nupkg   --source https://api.nuget.org/v3/index.json   --api-key YOUR_API_KEY

Do not commit API keys to source control. Keep publishing credentials in your CI provider's secret store or another approved secret manager.

Give every published package an intentional version.

1.0.0   first stable release
1.1.0   backwards-compatible feature
1.1.1   backwards-compatible fix
2.0.0   breaking API change
2.0.0-preview.1   prerelease

You can override the package version at pack time:

dotnet pack -c Release -p:PackageVersion=1.2.0

Start with package sources, cache, and compatibility.

dotnet nuget list source

dotnet nuget locals all --clear

For dependency or framework errors, compare the package's target frameworks and dependencies with the consumer project's target framework instead of forcing an incompatible restore.

Use a repeatable package-development loop.

dotnet restore
dotnet build -c Release
dotnet test -c Release
dotnet pack -c Release -o ./artifacts
# install the .nupkg into a clean consumer project
# verify the public API and runtime behavior
# publish only after local/CI validation

For repository-wide .NET workflows, see the StemCode .NET developer guide.

Repeat the package workflow with your own library.

Use the same install, build, pack, local-test, and publish sequence with a package you actually maintain. Keeping the workflow repeatable makes package problems much easier to diagnose.