Create a NuGet package with the dotnet CLI
NuGet packages contain code that developers can reuse in their projects. No matter what your code does or contains, you use a command-line tool, either
dotnet.exe, to create the NuGet package.
This article describes how to create a package by using the dotnet CLI. Starting in Visual Studio 2017, the dotnet CLI is included with all .NET and .NET Core workloads. If you need to install the dotnet CLI or other NuGet client tools, see Install NuGet client tools.
This topic applies only to .NET and other projects that use the SDK-style format. For these projects, NuGet uses information from the project file to create a package. For quickstart tutorials, see Create packages with the dotnet CLI or Create packages with Visual Studio.
To create and publish packages for non-SDK-style projects, typically .NET Framework projects, see Create a package using the nuget.exe CLI or Create and publish a package using Visual Studio (.NET Framework).
You can create an example class library project by using the
dotnet new classlib command, and package the project by using
dotnet pack. The
dotnet pack command uses the following properties. If you don't specify values in the project file, the command uses default values.
PackageId, the package identifier, must be unique across nuget.org and any other targets that host the package. If you don't specify a value, the command uses the
Versionis a specific version number in the form
-Suffixidentifies prerelease versions. If not specified, the default value is
Authorsare the authors of the package. If not specified, the default value is the
Companyis company information. If not specified, the default value is the
Productis product information. If not specified, the default value is the
In Visual Studio, you can set these values in the project properties. Right-click the project in Solution Explorer, select Properties, and then select the Package section. You can also add the properties directly to the .csproj or other project file.
The following example shows a project file with package properties added.
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>netstandard2.0</TargetFramework> <PackageId>UniqueID</PackageId> <Version>1.0.0</Version> <Authors>Author Name</Authors> <Company>Company Name</Company> <Product>Product Name</Product> </PropertyGroup> </Project>
You can add other optional properties, such as
For packages you build for public consumption, pay special attention to the
PackageTags property. Tags help others find your package and understand what it does.
dotnet pack command automatically converts
PackageReferences in your project files to dependencies in the created package. You can control which assets to include through the
PrivateAssets tags. For more information, see Controlling dependency assets.
For more information about dependencies, optional properties, and versioning, see:
- Package references in project files
- Package versioning
- NuGet metadata properties
- MSBuild pack targets
Choose a unique package identifier and set the version number
The package identifier and the version number uniquely identify the exact code that's contained in the package.
Follow these best practices to create the package identifier:
The identifier must be unique across nuget.org and all other locations that host the package. To avoid conflicts, a good pattern is to use your company name as the first part of the identifier.
Follow a .NET namespace-like naming convention, using dot notation. For example, use
Contoso_Utility_UsefulStuff. It's also helpful for consumers if you match the package identifier to the namespace the code uses.
If you produce a package of sample code that demonstrates how to use another package, append
.Sampleto the identifier, as in
The sample package has a dependency on the original package. When you create the sample package, add
contentFilesvalue. In the content folder, arrange the sample code in a folder called \Samples\<identifier>, such as \Samples\Contoso.Utility.UsefulStuff.Sample.
Follow these best practices to set the package version:
In general, set the package version to match the project or assembly version, although this isn't strictly required. Matching the version is simple when you limit a package to a single assembly. NuGet itself deals with package versions when resolving dependencies, not assembly versions.
For more information about dependency resolution, see Dependency resolution with PackageReference. For information that might help you understand versioning, see this series of blog posts:
Add an optional description field
The package's optional description appears on the README tab of the package's nuget.org page. The description pulls from the
<Description> in the project file or the
$description in the .nuspec file.
The following example shows a
Description in the .csproj file for a .NET package:
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <PackageId>Azure.Storage.Blobs</PackageId> <Version>12.4.0</Version> <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags> <Description> This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data. For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/ Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/ REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api </Description> </PropertyGroup> </Project>
Run the pack command
To build the NuGet package or .nupkg file, run the dotnet pack command from the project folder, which also builds the project automatically.
The output shows the path to the .nupkg file:
MSBuild version 17.3.0+92e077650 for .NET Determining projects to restore... Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms). Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.
Automatically generate package on build
To automatically run
dotnet pack whenever you run
dotnet build, add the following line to your project file in the
When you automatically generate the package, packing increases the build time for your project.
dotnet pack on a solution packs all the projects in the solution that are packable, that is, have the
IsPackable property set to
Test package installation
Before you publish a package, you should test installing the package into a project. Testing ensures that the necessary files end up in their correct places in the project.
Test the installation manually in Visual Studio or on the command line by using the normal package installation process.
You can't change packages once created. If you correct a problem, change the package contents and repack.
After you recreate the package, retesting still uses the old version of the package until you clear your global packages folder. Clearing the folder is especially important for packages that don't use a unique prerelease label on every build.
Once you create the package, you can publish the .nupkg file to the host of your choice.
See the following articles for ways to extend the capabilities of your package or support other scenarios:
Submit and view feedback for