使用 nuget.exe CLI 创建包

项目
08/10/2023

无论包是什么用途或者它包含什么代码，均使用其中一个 CLI 工具（nuget.exe 或 dotnet.exe）将该功能打包进可以与任意数量的其他开发人员共享且可以由其使用的组件中。若要安装 NuGet CLI 工具，请参阅安装 NuGet 客户端工具。请注意，Visual Studio 不会自动包含 CLI 工具。

对于非 SDK 样式项目（通常为 .NET Framework 项目），按照本文中所述的步骤创建包。有关使用 Visual Studio 和 nuget.exe CLI 的分步说明，请参阅创建和发布 .NET Framework 包。
对于使用 SDK 样式格式的 .NET Core 和 .NET Standard 项目，以及任何其他 SDK 样式项目，请参阅使用 dotnet CLI 创建 NuGet 包。
对于从 packages.config 迁移到 PackageReference 的项目，使用 msbuild -t:pack。

从技术角度来讲，NuGet 包仅仅是一个使用 .nupkg 扩展重命名且其中的内容与特定约定相匹配的 ZIP 文件。本主题介绍创建满足这些约定的包的详细流程。

包以编译的代码（程序集）、符号和/或需要作为包传送的其他文件开头（请参阅概述和工作流）。尽管可以使用项目文件中信息的描述来保持编译程序集和包的同步，但此流程独立于编译或生成进入包的文件。

重要

本主题适用于非 SDK 样式项目，通常是除使用 Visual Studio 2017 和更高版本以及 NuGet 4.0+ 的 .NET Core 和 .NET Standard 项目之外的项目。

确定要打包的程序集

大多数通用包包含一个或多个其他开发人员可在其自己项目中使用的程序集。

通常情况下，最好每个 NuGet 包有一个程序集，前提是每个程序集可独立正常运行。例如，如果有一个 Utilities.dll 依赖于 Parser.dll 且 Parser.dll 可独立正常运行，则为每一个创建一个包。这样做使得开发人员能够独立于 Utilities.dll 使用 Parser.dll。
如果库由多个不能独立正常运行的程序集构成，那么可以将它们合并到一个包中。使用上面的示例，如果 Parser.dll 包含仅由 Utilities.dll 使用的代码，那么可以将 Parser.dll 保留在同一包中。
同样，如果 Utilities.dll 依赖于 Utilities.resources.dll 并且后者不能独立正常运行，则将两者放入同一包中。

事实上，资源是一种特殊情况。当包安装到项目中时，NuGet 自动将程序集引用添加到包的 DLL，不包含命名为 .resources.dll 的内容，因为它们被假定为本地化的附属程序集（请参阅创建本地化包）。为此，请避免对包含基本包代码的文件使用 .resources.dll。

如果库包含 COM 互操作程序集，请遵循使用 COM 互操作程序集创建包中的其他准则。

.nuspec 文件的角色和结构

一旦知道需要打包的文件后，下一步是在 .nuspec XML 文件中创建包清单。

清单：

介绍包的内容和自己是否包含在包中。
驱动包的创建并且指示 NuGet 如何将包安装到项目。例如，清单识别其他包依赖项，这样，NuGet 还可以在安装主包时安装这些依赖项。
如下所示，包含所需属性和可选属性。有关确切的详细信息（包括此处未提及的其他属性），请参阅 .nuspec 引用。

所需属性：

包标识符在承载包的库中必须是唯一的。
窗体 Major.Minor.Patch[-Suffix] 中特定的版本号，其中 -Suffix 标识预发布版本
包标题应出现在主机上（例如 nuget.org）
创建者和所有者信息。
对包的详细说明。

常见可选属性：

发行说明
版权信息
对 Visual Studio 中的包管理器 UI 的简短说明
区域设置 ID
项目 URL
作为表达式或文件的许可证（licenseUrl 将被弃用，请改为使用 license nuspec 元数据元素）
图标文件（iconUrl 将被弃用，请改为使用 icon nuspec 元数据元素）
依赖项和引用的列表
协助库搜索的标记

以下是典型（但虚构）的 .nuspec 文件，其中注释介绍属性：

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- Package version number that is used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- Icon is used in Visual Studio's package manager UI -->
        <icon>icon.png</icon>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

有关声明依赖项并指定版本号的详细信息，请参阅 packages.config 和包版本控制。还可以使用 dependency 元素上的 include 和 exclude 特性直接在包中结合依赖项的资产。请参阅 .nuspec 引用 - 依赖项。

因为清单包含在从清单创建的包中，所以可以通过检查现有包查找任意数目的其他示例。计算机上的 global-packages 文件夹是一个不错的源，其位置由以下命令返回：

nuget locals -list global-packages

转到任意 package\version 文件夹，将 .nupkg 文件复制到 .zip 文件，然后打开该 .zip 文件并检查其中的 .nuspec。

注意

从 Visual Studio 项目创建 .nuspec 时，清单包含生成包时被项目信息替换的令牌。请参阅从 Visual Studio 项目创建 .nuspec。

创建 .nuspec 文件

创建完整的清单通常以通过以下其中一种方法生成的基础 .nuspec 文件开始：

基于约定的工作目录
程序集 DLL
Visual Studio 项目
包含默认值的新文件

然后手动编辑文件，使它可以在最终包中描述所需的确切内容。

重要

生成 .nuspec 文件包含的占位符必须在使用 nuget pack 命令创建包前修改。如果 .nuspec 包含任意占位符，则命令失败。

来自基于约定的工作目录

因为 NuGet 包仅仅是使用 .nupkg 扩展名重命名的 ZIP 文件，所以在本地文件系统上创建所需文件夹结构，然后从该结构直接创建 .nuspec 文件通常最简单。然后，nuget pack 命令自动将所有文件添加到该文件夹结构（不包含以 . 开头的文件夹，从而在同一结构中保留专用文件）。

此方法的优势是无需在清单中指定需要包含在包中的文件（如本主题后面所述）。可以轻松使得生成进程生成进入包中的确切文件夹结构，并且可以轻松包含不是项目一部分的其他文件：

应注入目标项目的内容和源代码。
PowerShell 脚本
转换到现有配置和项目中的源代码文件。

文件夹约定如下所示：

Folder	说明	包安装时的操作
（根）	readme.txt 的位置	包安装时，Visual Studio 在包根目录中显示 readme.txt 文件。
lib/{tfm}	特定目标框架名字对象 (TFM) 的程序集 (`.dll`)、文档 (`.xml`) 和符号 (`.pdb`) 文件	程序集添加为引用，以用于编译和运行时；`.xml` 和 `.pdb` 复制到项目文件夹中。有关创建框架特定目标子文件夹的详细信息，请参阅支持多个目标框架。
ref/{tfm}	给定目标框架名字对象 (TFM) 的程序集 (`.dll`) 和符号 (`.pdb`) 文件	程序集添加为引用，仅用于编译时；因此，不会向项目 Bin 文件夹复制任何内容。
runtimes	特定于体系结构的程序集 (`.dll`)、符号 (`.pdb`) 和本机源 (`.pri`) 文件	程序集添加为引用，仅用于运行时；其他文件复制到项目文件夹中。在 `AnyCPU` 文件夹下应始终具有特定于相应的 (TFM) `/ref/{tfm}` 的程序集，以提供相应的编译时程序集。请参阅支持多个目标框架。
内容	任意文件	内容复制到项目根目录。将“内容”文件夹视为最终使用包的目标应用程序的根目录。若要使包在应用程序的 /images 文件夹中添加图片，请将其置于包的 content/images 文件夹中。
build	(3.x+) MSBuild `.targets` 和 `.props` 文件	自动插入到项目。
buildMultiTargeting	(4.0+) 跨框架目标的 MSBuild `.targets` 和 `.props` 文件	自动插入到项目。
buildTransitive	(5.0+) 以可传递的方式流入任意使用项目的 MSBuild `.targets` 和 `.props` 文件。请参阅功能页。	自动插入到项目。
工具	可从包管理器控制台访问 Powershell 脚本和程序	`tools` 文件夹添加到仅适用于包管理器控制台的 `PATH` 环境变量（尤其是不作为 MSBuild 集在生成项目时添加到 `PATH`）。

因为文件夹结构可能包含任意数量的目标框架的任意数量的程序集，所以此方法在创建支持多个框架的包时是必要的。

在任何情况下，一旦准备好所需文件夹结构，则在该文件夹中运行以下命令以创建 .nuspec 文件：

nuget spec

同样，生成的 .nuspec 不包含文件夹结构中的文件的显式引用。包创建时，NuGet 自动包含所有文件。但是，还需在清单的其他部分中编辑占位符值。

来自程序集 DLL

在从程序集创建包的简单情况下，可以使用以下命令从程序集中的元数据生成 .nuspec 文件：

nuget spec <assembly-name>.dll

使用此窗体将清单中的一些占位符替换为程序集的特定值。例如，<id> 属性设为程序集名称，<version> 设为程序集版本。但是，清单中的其他属性在程序集中没有匹配值，因此仍包含占位符。

来自 Visual Studio 项目

从 .csproj 或 .vbproj 文件创建 .nuspec 较为方便，因为其他已安装到这些项目的包会自动引用为依赖项。只需使用与项目文件相同的文件夹中的命令：

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

生成的 <project-name>.nuspec 文件包含在打包时替换为项目值的令牌，包含对所有其他已安装的包的引用。

若将程序包依赖项包含在 .nuspec 中，请使用nuget pack，并从生成的 .nupkg 文件获取 .nuspec 文件。例如，使用以下命令。

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget pack myproject.csproj

令牌在项目属性的两侧由 $ 符号分隔。例如，通过此方法生成的清单中的 <id> 值通常如下所示：

<id>$id$</id>

此令牌在打包时替换为项目文件的 AssemblyName 值。有关项目值到 .nuspec 令牌的确切映射，请参阅替换令牌引用。

借助令牌，更新项目时可以不再需要更新关键值，例如 .nuspec 中的版本号。（如果需要，随时可以使用文本值替换令牌）。

注意在 Visual Studio 项目中工作时，有多个可用的其他打包选项，如稍后的运行 NuGet 包生成 .nupkg 文件所述。

解决方案级别包

仅适用于 NuGet 2.x。在 NuGet 3.0+ 中不可用。

NuGet 2.x 支持为包管理器控制台（tools 文件夹的内容）安装工具或其他命令的解决方案级别包的概念，但是不会将引用、内容或生成自定义添加到解决方案中的任何项目中。该包在其直接 lib、content 或 build 文件夹中未包含文件，并且它的依赖项各自的 lib、content 或 build 文件夹中也没有文件。

NuGet 在 .nuget 文件夹的 packages.config 文件（而不是项目的 packages.config 文件）中，跟踪安装的解决方案级别包。

包含默认值的新文件

以下命令使用占位符创建默认清单，这可确保一开始就使用正确的文件结构：

nuget spec [<package-name>]

如果忽略 <package-name>，生成的文件是 Package.nuspec。如果提供 Contoso.Utility.UsefulStuff 等名称，则文件是 Contoso.Utility.UsefulStuff.nuspec。

生成的 .nuspec 包含值的占位符（例如 projectUrl）。请确保在使用文件创建最终 .nupkg 文件前编辑该文件。

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

包标识符（<id> 元素）和版本号（<version> 元素）是清单中最重要的两个值，因为它们唯一标识包中包含的确切代码。

针对包标识符的最佳做法：

唯一性：标识符在 nuget.org 或承载包的任意库中必须是唯一的。确定标识符之前，请搜索适用库以检查该名称是否已使用。为了避免冲突，最好使用公司名作为标识符的第一部分（例如 Contoso.）。
类似命名空间的名称：遵循类似于 .NET 中命名空间的模式，使用点表示法而不是连字符。例如，使用 Contoso.Utility.UsefulStuff 而不是 Contoso-Utility-UsefulStuff 或 Contoso_Utility_UsefulStuff。当包标识符与代码中使用的命名空间相匹配时，这个方法也很有用。
示例包：如果生成演示如何使用另一个包的示例代码的包，则附加 .Sample 作为标识符的后缀，与 Contoso.Utility.UsefulStuff.Sample 中相似。（当然，示例包会在其他包上有依赖项。）创建示例包时，请使用前面介绍的基于约定的工作目录方法。在 content 文件夹中，在名为 \Samples\<identifier> 的文件夹中排列示例代码，与 \Samples\Contoso.Utility.UsefulStuff.Sample 中相似。

针对包版本的最佳做法：

一般情况下，将包的版本设置为与库相匹配，但这不是必须的。如之前在确定要打包的程序集中所述，将包限制到单个程序集是一个简单的问题。总的来说，请记住解析依赖项时，NuGet 自己处理包版本而不是程序集版本。
使用非标准版本方案时，请确保考虑使用 NuGet 版本控制规则，如包版本控制中所述。

以下一系列简短博客文章也有助于理解版本控制：

第 1 部分：解决 DLL Hell

第 2 部分：核心算法

第 3 部分：通过绑定重定向统一

添加自述文件和其他文件

若要直接指定要包含在包中的文件，请使用 .nuspec 中的 <files> 节点，其遵循 <metadata> 标记：

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

提示

使用基于约定的工作目录方法时，可以将 readme.txt 置于包根目录中并将其他内容置于 content 文件夹中。清单中不需要 <file> 元素。

如果包根目录中包含名为 readme.txt 的文件，Visual Studio 在直接安装包之后立即将该文件的内容显示为纯文本。（对于安装为依赖项的包，不会显示自述文件）。例如，下面是 HtmlAgilityPack 包的自述文件的显示方式：

The display of a readme file for a NuGet package upon installation

注意

如果 .nuspec 文件中包含空 <files> 节点，则 NuGet 不会在包中包含除 lib 文件夹中的内容以外的任何其他内容。

将 MSBuild 属性和目标包含到包中

在某些情况下，可能需要在使用包的项目中添加自定义生成目标或属性，例如生成期间运行自定义工具或进程。有关详细信息，请参阅 NuGet 包中的 MSBuild 属性和目标

在项目的生成文件夹中创建 <package_id>.targets 或 <package_id>.props（例如 Contoso.Utility.UsefulStuff.targets）。

然后在 .nuspec 文件中，确保参阅 <files> 节点中的这些文件：

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

将包添加到项目中时，NuGet 将自动包含这些属性和目标。

运行 nuget 包以生成 .nupkg 文件

使用程序集或基于约定的工作目录时，通过使用 .nuspec 文件运行 nuget pack 创建包，使用特定的文件名替换 <project-name>：

nuget pack <project-name>.nuspec

使用 Visual Studio 项目时，使用项目文件运行 nuget pack，该项目文件自动加载项目的 .nuspec 文件并使用项目文件中的值替换其中的任意令牌：

nuget pack <project-name>.csproj

注意

令牌替换需要直接使用项目文件，因为项目是令牌值的源。如果将 nuget pack 用于 .nuspec 文件，不会发生令牌替换。

在所有情况下，nuget pack 不包含句点开头的文件夹，例如 .git 或 .hg。

NuGet 指示需要更正的 .nuspec 文件中是否有错误，例如忘记更改清单中的占位符值。

一旦 nuget pack 成功，就有一个可以发布到合适库的 .nupkg 文件，如发布包中所述。

提示

一个检查创建后的包的有用方法是在包资源管理器工具中打开它。这会为你提供包内容及其清单的图形视图。还可以将生成的 .nupkg 文件重命名为 .zip 文件并直接浏览其内容。

其他选项

可通过 nuget pack 使用多种命令行开关，以排除文件、替代清单中的版本号和更改输出文件夹等。有关完整列表，请参考包命令引用。

以下是 Visual Studio 项目中的一些常见选项：

引用项目：如果项目引用其他项目，通过使用 -IncludeReferencedProjects 选项，可以将引用项目添加为包的一部分或依赖项：
```
nuget pack MyProject.csproj -IncludeReferencedProjects
```
此包含过程是递归的，所以如果 MyProject.csproj 引用项目 B 和 C，且这些项目引用 D、E 和 F，那么 B、C、D、E 和 F 中的文件包含在包中。

如果引用的项目包含其自身的 .nuspec 文件，那么 NuGet 将该引用的项目添加为依赖项。需要单独打包和发布该项目。
生成配置：默认情况下，NuGet 使用项目文件中设置的默认生成配置，通常是“调试”。若要从不同的生成配置（例如“发布”）中打包文件，使用包含以下配置的 -properties 选项：
```
nuget pack MyProject.csproj -properties Configuration=Release
```
符号：若要包含允许使用者在调试器中单步执行包代码的符号，请使用 -Symbols 选项：
```
nuget pack MyProject.csproj -symbols
```

测试包安装

发布包前，通常需要测试将包安装到项目的过程。测试确保所有文件一定在项目中正确的位置结束。

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

对于自动测试，基本流程如下所示：

将 .nupkg 文件复制到本地文件夹。
使用 nuget sources add -name <name> -source <path> 命令将文件夹添加到包源（请参阅 nuget 源）。请注意，只需在任意给定计算机上设置一次此本地源。
使用 nuget install <packageID> -source <name>（其中 <name> 与提供给 nuget sources 的源名称相匹配）从该源安装包。指定源可确保包从该源中单独安装。
检查文件系统以检查文件是否正确安装。

后续步骤

创建包（.nupkg 文件）后，可以将其发布到选择的库，如发布包中所述。

你可能还希望扩展包的功能，或者支持其他方案，如以下主题所述：

最后，有需要注意的其他包类型：