使用 dotnet CLI 创建 NuGet 包

项目
11/30/2023

NuGet 包包含开发人员可在项目中重复使用的代码。无论代码功能或内容如何，你都使用命令行工具 nuget.exe 或 dotnet.exe 创建 NuGet 包。

本文介绍如何使用 dotnet CLI 创建包。从 Visual Studio 2017 开始，dotnet CLI 包含在所有 .NET 或 .NET Core 工作负荷中。如果需要安装 dotnet CLI 或其他 NuGet 客户端工具，请参阅安装 NuGet 客户端工具。

本主题仅适用于使用 SDK 样式格式的 .NET 和其他项目。对于这些项目，NuGet 使用项目文件中的信息来创建包。有关快速入门教程，请参阅使用 dotnet CLI 创建包或使用 Visual Studio 创建包。

MSBuild msbuild -t:pack 命令在功能上等效于 dotnet pack。有关使用 MSBuild 创建 NuGet 包的详细信息，请参阅使用 MSBuild 创建 NuGet 包。

注意

若要为非 SDK 样式项目（通常是 .NET 框架项目）创建和发布包，请参阅使用 nuget.exe CLI 创建包或使用 Visual Studio 创建和发布包（.NET 框架）。
对于从 packages.config 迁移到 PackageReference 的项目，使用 msbuild -t:pack。有关详细信息，请参阅迁移后创建包。

设置属性

可以使用 dotnet new classlib 命令创建示例类库项目，并使用 dotnet pack 打包项目。 dotnet pack 命令使用以下属性。如果未在项目文件中指定值，该命令将使用默认值。

包标识符 PackageId 必须在 nuget.org 和承载包的任何其他目标中是唯一的。如果未指定值，该命令将使用 AssemblyName。
Version 是表单 Major.Minor.Patch[-Suffix] 中的特定版本号，用于 -Suffix 标识预发行版版本。如果未指定，默认值为 1.0.0。
Authors 是包的作者。如果未指定，默认值为 AssemblyName。
Company 是公司信息。如果未指定，默认值为 Authors 值。
Product 是产品信息。如果未指定，默认值为 AssemblyName。

在 Visual Studio 中，可以在项目属性中设置这些值。在“解决方案资源管理器”中右击该项目，选择“属性”，然后选择“包”部分。还可以将属性直接添加到 .csproj 或其他项目文件中。

以下示例显示了添加包属性的项目文件。

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

可以添加其他可选属性，例如 Title、PackageDescription 和 PackageTags。

注意

对于为公共消耗而生成的包，请特别注意该 PackageTags 属性。标记可帮助其他人找到你的包并了解它的作用。

命令 dotnet pack 会自动将项目文件中的 PackageReference 转换为所创建的包中的依赖项。可以控制要通过 IncludeAssets、ExcludeAssets 和 PrivateAssets 标记包括哪些资产。有关详细信息，请参阅控制依赖项资产。

有关依赖项、可选属性和版本控制的详细信息，请参阅：

选择唯一的包标识符并设置版本号

包标识符和版本号唯一标识包中包含的确切代码。

按照以下最佳做法创建包标识符：

该标识符必须在 nuget.org 和承载包的所有其他位置中是唯一的。为了避免冲突，最好使用公司名作为标识符的第一部分。
使用点表示法遵循类似于 .NET 命名空间的命名规则。例如，使用 Contoso.Utility.UsefulStuff 而不是 Contoso-Utility-UsefulStuff 或 Contoso_Utility_UsefulStuff。如果将包标识符与代码使用的命名空间匹配，这对使用者也很有帮助。
如果生成展示如何使用另一个包的示例代码包，请附加 .Sample 作为标识符的后缀，就像 Contoso.Utility.UsefulStuff.Sample 中一样。

示例包依赖于原始包。创建示例包时，请添加值为 contentFiles 的 <IncludeAssets>。在内容文件夹中，排列名为 \Samples\<标识符>的文件夹中的示例代码，例如 \Samples\Contoso.Utility.UsefulStuff.Sample。

遵循以下最佳做法设置包版本：

一般情况下，将包版本设置为与项目或程序集版本相匹配，但这不是必须的。如果将包限制为单个程序集，那么匹配版本很简单。解析依赖项时，NuGet 自己处理包版本而不是程序集版本。
如果使用非标准版本方案，请确保考虑使用 NuGet 版本控制规则，如包版本控制中所述。 NuGet 主要与语义化版本控制 2.0.0兼容。

注意

有关依赖项解析的详细信息，请参阅使用 PackageReference 进行依赖项解析。有关可帮助你了解版本控制的信息，请参阅以下系列博客文章：

添加可选说明字段

包的可选说明显示在包 nuget.org 页的“自述文件”选项卡上。说明从项目文件的 <Description> 中或 .nuspec 文件的 $description 中拉取。

以下示例显示 .NET 包的 .csproj 文件中的 Description。

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

运行 pack 命令

若要生成 NuGet 包或 .nupkg 文件，请从项目文件夹运行 dotnet pack 命令，该命令也会自动生成项目。

dotnet pack

输出将显示 .nupkg 文件的路径：

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

在生成期间自动生成包

若要在运行 dotnet build 时都自动运行 dotnet pack，请将以下行添加到 <PropertyGroup> 标记中的项目文件内：

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

注意

自动生成包时，打包会增加项目的生成时间。

在解决方案上运行 dotnet pack 时，会打包解决方案中可打包的所有项目，即 IsPackable 属性设置为 true。

测试包安装

在发布包之前，应测试将包安装到项目中。测试确保文件一定在项目中正确的位置结束。

可以在 Visual Studio 中手动测试安装，或使用常规包安装流程在命令行上测试。

重要

创建包后，无法更改包。如果更正了问题，请更改包内容并重新打包。
重新创建包后，重新测试仍使用旧版本的包，直到清除全局包文件夹。清除文件夹对于每个生成中不使用唯一预发行版标签的包尤其重要。

后续步骤

创建包后，可以将 .nupkg 文件发布到所选主机。

发布包

有关扩展包的功能或支持其他方案的方法，请参阅以下文章：