如何使用 dotnet pack 打包 .NET 跨平台程序集？

dotnet pack 介绍

dotnet pack 是一个 .NET Core NuGet 包打包程序。

官方描述

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

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

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

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

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

dotnet pack 命令说明

前提条件，安装 .NET Core 3.1 SDK 及更高版本，此处环境安装的是 .NET 8 SDK，在终端执行如下命令：

• 查看 .net 信息：

PS F:\gitee> dotnet --info
.NET SDK:
 Version:           8.0.101
 Commit:            6eceda187b
 Workload version:  8.0.100-manifests.291ed43a

运行时环境:
 OS Name:     Windows
 OS Version:  10.0.22621
 OS Platform: Windows
 RID:         win-x64
 Base Path:   C:\Program Files\dotnet\sdk\8.0.101\

已安装 .NET 工作负载:
 Workload version: 8.0.100-manifests.291ed43a
没有要显示的已安装工作负载。

Host:
  Version:      8.0.1
  Architecture: x64
  Commit:       bf5e279d92

.NET SDKs installed:
  8.0.101 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
  x86   [C:\Program Files (x86)\dotnet]
    registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

• 查看 dotnet pack 命令帮助信息：

PS F:\gitee> dotnet pack -h
Description:
  .NET Core NuGet 包打包程序

用法:
  dotnet pack [<PROJECT | SOLUTION>...] [options]

参数:
  <PROJECT | SOLUTION>  要操作的项目或解决方案文件。如果没有指定文件，则命令将在当前目录里搜索一个文件。

选项:
  -o, --output <OUTPUT_DIR>            要放置生成包的输出目录。
  --artifacts-path <ARTIFACTS_DIR>     工件路径。项目中的所有输出(包括生成、发布和打包输出)都将放到指定路径下的子文件夹 中。
  --no-build                           打包之前不要生成项目。Implies --no-restore.
  --include-symbols                    除了输出目录中的常规包之外，还包括带符号的包。
  --include-source                     包括 PDB 和源文件。源文件放入 nuget 结果包的“src”文件夹中。
  -s, --serviceable                    在包中设置可用标志。有关详细信息，请参阅 https://aka.ms/nupkgservicing。
  --nologo                             不显示启动版权标志或版权消息。
  --interactive                        允许命令停止和等待用户输入或操作(例如，用以完成身份验证)。
  --no-restore                         生成前请勿还原项目。
  -v, --verbosity <LEVEL>              设置 MSBuild 详细程度。允许值为 q[uiet]、m[inimal]、n[ormal]、d[etailed] 和 diag[nostic]。
  --version-suffix <VERSION_SUFFIX>    设置生成项目时使用的 $(VersionSuffix) 属性的值。
  -c, --configuration <CONFIGURATION>  用于生成包的配置。默认值为 "Release"。
  --disable-build-servers              强制命令忽略任何永久性生成服务器。
  --ucr, --use-current-runtime         将当前运行时用作目标运行时。
  -?, -h, --help                       显示命令行帮助。

关于【dotnet pack】更多信息请查看，https://learn.microsoft.com/zh-cn/dotnet/core/tools/dotnet-pack

使用示例

打包 .net 类库项目

• 创建一个 .net 类库(classlib) 文件，执行命令：

dotnet new classlib -n ClassLibrary1

• 在创建的类库项目中，添加如下代码：

namespace ClassLibrary1;

public class Class1
{
    public void SayHi() 
    {
        Console.WriteLine("helle, dotnet!");
    }
}

• 执行 dotnet pack 命令：

dotnet pack \
C:\Users\Jeffrey.Chai\Desktop\test\ClassLibrary1\ClassLibrary1.csproj \
--no-build -o C:\Users\Jeffrey.Chai\Desktop\test\nupkgs \
-c Release \
-p:TargetFrameworks=net8.0 \
-p:PackageVersion=0.0.1

参数说明：

• --no-build 打包时跳过生成步骤信息；
• -o|--output 将生成的 nuget 包放置到指定的文件夹中；
• -c|--configuration 定义生成配置。大多数项目的默认配置为 Debug，但你可以覆盖项目中的生成配置设置；
• -p:TargetFrameworks 指定生成的 nuget 包依赖 目标框架；
• -p:PackageVersion 指定生成的 nuget 包版本信息；

执行成功后，输出如下信息：

生成带注释的 nuget 包

通过上面默认的方式构建的 nuget 包是没有注释说明的，在使用的时候看不到包介绍说明不是很方便。

其实想让生成的 nuget 包带注释非常简单，只需要在项目文件加上一个 GenerateDocumentationFile 元数据配置即可。

类库 .csproj 文件完整信息如下：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <Version>0.0.1</Version>
  </PropertyGroup>

</Project>

添加上面信息后，再次执行 dotnet pack 命令即可。

构建特定平台的 nuget 包

有些时候，项目环境因素，我们可能需要构建特定平台的 nuget 包，我们可以添加 --runtime 参数即可。

• 打包项目，并使用特定运行时 (Windows 10) 进行还原操作：

dotnet pack --runtime win10-x64

参数说明：

• --runtime 可以指定特定的 .NET RID 目录

关于 .NET RID 目录

RID 是 运行时标识符 的缩写。RID 值用于标识应用程序运行所在的目标平台。.NET 包使用它们来表示 NuGet 包中特定于平台的资产。 以下值是 RID 的示例：linux-x64、win-x64 或 osx-x64。 对于具有本机依赖项的包，RID 将指定在其中可以还原包的平台。

可以在项目文件的 <RuntimeIdentifier> 元素中设置一个 RID。 可以将多个 RID 定义为项目文件的 <RuntimeIdentifiers> 元素中的列表（以分号分隔）。 也可使用以下 .NET CLI 命令 通过 --runtime 选项使用它们：

• dotnet build
• dotnet clean
• dotnet pack
• dotnet publish
• dotnet restore
• dotnet run
• dotnet store

表示具体操作系统的 RID 通常遵循以下模式：[os].[version]-[architecture]-[additional qualifiers]，其中：

• [os] 是操作系统/平台系统名字对象。 例如 ubuntu。

• [version] 是操作系统版本，使用的格式是以点 (.) 分隔的版本号。 例如 15.10。

版本不应为营销版本，因为营销版本通常代表该操作系统的多个离散版本，且具有不同的平台 API 外围应用。

• [architecture] 是处理器体系结构。 例如：x86、x64、arm 或 arm64。

• [additional qualifiers] 进一步区分了不同的平台。 例如：aot。

以下示例演示了 runtime.json 文件中定义的另一个略大的 RID 图表：

linux-arm64     linux-arm32
         |     \   /     |
         |     linux     |
         |       |       |
    unix-arm64   |    unix-x64
             \   |   /
               unix
                 |
                any

关于更多 .NET RID 目录，请查看：https://learn.microsoft.com/zh-cn/dotnet/core/rid-catalog