Create a NuGet package with the dotnet CLI (original) (raw)

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 nuget.exe or 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.

The MSBuild msbuild -t:pack command is functionally equivalent to dotnet pack. For more information about creating a package with MSBuild, see Create a NuGet package using MSBuild.

Note

• 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).
• For projects migrated from packages.config to PackageReference, use msbuild -t:pack. For more information, see Create a package after migration.

Set properties

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 AssemblyName.
• Version is a specific version number in the form Major.Minor.Patch[-Suffix], where -Suffix identifies prerelease versions. If not specified, the default value is 1.0.0.
• Authors are the authors of the package. If not specified, the default value is the AssemblyName.
• Company is company information. If not specified, the default value is the Authors value.
• Product is product information. If not specified, the default value is the AssemblyName.

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 Title, PackageDescription, and PackageTags.

Note

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.

The 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 IncludeAssets, ExcludeAssets and 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 rather than Contoso-Utility-UsefulStuff or 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 .Sample to the identifier, as in Contoso.Utility.UsefulStuff.Sample.
  The sample package has a dependency on the original package. When you create the sample package, add <IncludeAssets> with the contentFiles value. In the content folder, arrange the sample code in a folder called \Samples\, 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.
• If you use a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in Package versioning. NuGet is mostly Semantic Versioning 2.0.0-compliant.

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.

dotnet pack

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 <PropertyGroup> tag:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Note

When you automatically generate the package, packing increases the build time for your project.

Running dotnet pack on a solution packs all the projects in the solution that are packable, that is, have the IsPackable property set to true.

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.

Important

• 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.

Next steps

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:

• Package versioning
• Support multiple target frameworks
• Add a package icon
• Transformations of source and configuration files
• Localization
• Prerelease versions
• Set package type
• MSBuild props and targets
• Create packages with COM interop assemblies
• Create native packages
• Create symbol packages (.snupkg)