dotnet pack

本文适用于： ✔️ .NET Core 3.1 SDK 及更高版本

“属性”

dotnet pack - 将代码打包到 NuGet 包。

摘要

dotnet pack [<PROJECT>|<SOLUTION>] [-c|--configuration <CONFIGURATION>]
    [--force] [--include-source] [--include-symbols] [--interactive]
    [--no-build] [--no-dependencies] [--no-restore] [--nologo]
    [-o|--output <OUTPUT_DIRECTORY>] [--runtime <RUNTIME_IDENTIFIER>]
    [-s|--serviceable] [--tl:[auto|on|off]] [-v|--verbosity <LEVEL>]
    [--version-suffix <VERSION_SUFFIX>]

dotnet pack -h|--help

描述

dotnet pack 命令生成项目并创建 NuGet 包。 该命令的结果是一个 NuGet 包，也就是一个 .nupkg 文件。

如果要生成包含调试符号的包，可以使用以下两个选项：

• --include-symbols：该选项用于创建符号包。
• --include-source：该选项用于创建带有 src 文件夹的符号包，该文件夹包含源文件。

将被打包项目的 NuGet 依赖项添加到 .nuspec 文件，以便在安装包时可以进行正确解析。 如果打包的项目具有对其他项目的引用，则不会将其他项目包含在包中。 目前，如果具有项目到项目的依赖项，则每个项目均必须包含一个包。

默认情况下，dotnet pack 先构建项目。 如果希望避免此行为，则传递 --no-build 选项。 此选项在持续集成 (CI) 生成方案中通常非常有用，你可以知道代码是之前生成的。

注意

在某些情况下，无法执行隐式生成。 设置 GeneratePackageOnBuild 以避免生成目标和包目标之间的循环依赖关系时可能会发生这种情况。 如果存在锁定文件或其他问题，生成也可能失败。

可向 dotnet pack 命令提供 MSBuild 属性，用于打包进程。 有关详细信息，请参阅 NuGet 包目标属性和 MSBuild 命令行引用。 示例部分介绍了如何在不同的情况下使用 MSBuild -p 开关。

备注

Web 项目不可打包。

隐式还原

无需运行 dotnet restore，因为它由所有需要还原的命令隐式运行，如 dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish 和 dotnet pack。 若要禁用隐式还原，请使用 --no-restore 选项。

在执行显式还原有意义的某些情况下，例如 dotnet restore中，或在需要显式控制还原发生时间的生成系统中，dotnet restore 命令仍然有用。

有关如何使用 NuGet 源的信息，请参阅 dotnet restore 文档。

以长格式传入时，此命令支持 dotnet restore 选项（例如，--source）。 不支持缩写选项，例如 -s。

工作负载清单下载

运行此命令时，它将为工作负载启动播发清单的异步后台下载。 如果此命令完成后，下载仍在运行，则将停止下载。 有关详细信息，请参阅播发清单。

自变量

PROJECT | SOLUTION

要打包的项目或解决方案。 它可能是 csproj 文件、vbproj 文件、fsproj 文件、解决方案文件或目录的路径。 如果未指定，此命令会搜索当前目录，以获取项目文件或解决方案文件。

选项

• -c|--configuration <CONFIGURATION>

  定义生成配置。 如果要使用 .NET 8 SDK 或更高版本进行开发，则默认情况下，该命令对 TargetFramework 设置为net8.0或更高版本的项目使用Release配置。 默认生成配置适用于 Debug 早期版本的 SDK 和早期目标框架。 可以在项目设置中替代默认值，也可以使用此选项替代默认值。 有关详细信息，请参阅 “dotnet publish”使用发布配置 ， “dotnet pack”使用发布配置。

• --force

  强制解析所有依赖项，即使上次还原已成功，也不例外。 指定此标记等同于删除 project.assets.json 文件。

• -?|-h|--help

  打印出有关如何使用命令的说明。

• --include-source

  除输出目录中的常规 NuGet 包外，还包括调试符号 NuGet 包。 源文件包括在符号包内的 src 文件夹中。

• --include-symbols

  除输出目录中的常规 NuGet 包外，还包括调试符号 NuGet 包。

• --interactive

  允许命令停止并等待用户输入或操作。 例如，完成身份验证。 自 .NET Core 3.0 SDK 起可用。

• --no-build

  打包前不生成项目。 还将隐式设置 --no-restore 标记。

• --no-dependencies

  忽略项目间引用，仅还原根项目。

• --no-restore

  运行此命令时不执行隐式还原。

• --nologo

  不显示启动版权标志或版权消息。

• -o|--output <OUTPUT_DIRECTORY>

  将生成的包放置在指定目录。

  • .NET 7.0.200 SDK

    在 7.0.200 SDK 中，如果在解决方案上运行此命令时指定 --output 选项，CLI 将发出错误。 这是一个回归，已在 .NET SDK 7.0.201 及更高版本中得到修复。

• --runtime <RUNTIME_IDENTIFIER>

  指定要为其还原包的目标运行时。 有关运行时标识符 (RID) 的列表，请参阅 RID 目录。

• -s|--serviceable

  设置包中可用的标志。 有关详细信息，请参阅 .NET 博客：.NET Framework 4.5.1 支持 .NET NuGet 库的 Microsoft 安全更新。

• --tl:[auto|on|off]

  指定是否应将终端记录器用于生成输出。 默认值为 auto，它首先验证环境，然后再启用终端日志记录。 在启用新的记录器之前，环境检查会验证终端能否使用新式输出功能，并且不使用重定向的标准输出。 on 跳过环境检查并启用终端日志记录。 off 跳过环境检查并使用默认控制台记录器。

  终端记录器显示还原阶段，然后显示生成阶段。 在每个阶段，当前生成项目显示在终端的底部。 每个正在生成的项目都会输出当前正在生成的 MSBuild 目标，以及在该目标上花费的时间。 可以搜索此信息以了解有关生成的详细信息。 项目生成完成后，将会编写一个“已完成生成”部分以捕获以下内容：

  • 生成项目的名称。
  • 目标框架（如果是多目标）。
  • 该生成的状态。
  • 该生成的主要输出（它设置了超链接）。
  • 为该项目生成的任何诊断。

  此选项从 .NET 8 开始可用。

• -v|--verbosity <LEVEL>

  设置命令的详细级别。 允许使用的值为 q[uiet]、m[inimal]、n[ormal]、d[etailed] 和 diag[nostic]。 有关详细信息，请参阅 LoggerVerbosity。

• --version-suffix <VERSION_SUFFIX>

  定义 VersionSuffix MSBuild 属性的值。 此属性对包版本的影响取决于 Version 和 VersionPrefix 属性的值，如下表所示：

  具有值的属性	包版本
  无	1.0.0
  Version	$(Version)
  仅 VersionPrefix	$(VersionPrefix)
  仅 VersionSuffix	1.0.0-$(VersionSuffix)
  VersionPrefix 和 VersionSuffix	$(VersionPrefix)-$(VersionSuffix)

  如果要使用 --version-suffix，请在项目文件中指定 VersionPrefix 而不是 Version。 例如，如果 VersionPrefix 是 0.1.2 并且你将 --version-suffix rc.1 传递给 dotnet pack，则包版本将是 0.1.2-rc.1。

  如果 Version 具有值并且你将 --version-suffix 传递到 dotnet pack，则忽略为 --version-suffix 指定的值。

示例

• 打包当前目录中的项目：

  dotnet pack
  

• 打包 app1 项目：

  dotnet pack ~/projects/app1/project.csproj
  

• 打包当前目录中的项目并将生成的包放置到 nupkgs 文件夹：

  dotnet pack --output nupkgs
  

• 将当前目录中的项目打包到 nupkgs 文件夹并跳过生成步骤：

  dotnet pack --no-build --output nupkgs
  

• 将项目的版本后缀配置为 .csproj 文件中的 <VersionSuffix>$(VersionSuffix)</VersionSuffix>，使用给定的后缀打包当前项目，并更新生成的程序包版本：

  dotnet pack --version-suffix "ci-1234"
  

• 使用 PackageVersion MSBuild 属性将包版本设置为 2.1.0：

  dotnet pack -p:PackageVersion=2.1.0
  

• 打包特定目标框架的项目：

  dotnet pack -p:TargetFrameworks=net45
  

• 打包项目并使用特定运行时（Windows）执行还原操作：

  dotnet pack --runtime win-x64
  

• 使用 .nuspec 文件打包项目：

  dotnet pack ~/projects/app1/project.csproj -p:NuspecFile=~/projects/app1/project.nuspec -p:NuspecBasePath=~/projects/app1/nuget
  

  要了解如何使用 NuspecFile、NuspecBasePath 和 NuspecProperties，请参阅以下资源：

  • 使用 .nuspec 打包
  • 用于创建自定义包的高级扩展点
  • 全局属性