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

2024-09-06 776

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

本文涉及的产品

可观测监控 Prometheus 版，每月50GB免费额度

Serverless 应用引擎免费试用套餐包，4320000 CU，有效期3个月

云原生网关 MSE Higress，422元/月

简介： `dotnet pack` 是 .NET Core 的 NuGet 包打包工具，用于将代码打包成 NuGet 包。通过命令 `dotnet pack` 可生成 `.nupkg` 文件。使用 `--include-symbols` 和 `--include-source` 选项可分别创建包含调试符号和源文件的包。默认情况下，`dotnet pack` 会先构建项目，可通过 `--no-build` 跳过构建。此外，还可以使用 `--output` 指定输出目录、`-c` 设置配置等。示例展示了创建类库项目并打包的过程。更多详情及命令选项，请参考官方文档。

@TOC

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 命令：

这将会生成一个包含描述和其他元数据的 NuGet 包，并将其放置在指定的输出目录（例如 ./test/nupkgs）中。

cd C:\Users\Jeffrey.Chai\Desktop\test\ClassLibrary1\

dotnet pack ClassLibrary1.csproj \
--no-build \
-o ./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 包版本信息；

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

dotnet pack

查看生成的 nuget 包

生成的 nuget 包文件（例如 MyLibrary.1.0.0.nupkg）将包含你在 .csproj 文件中定义的所有元数据。你可以使用 nuget spec 命令查看或编辑包的 .nuspec 文件：

nuget spec ./test/nupkgs/MyLibrary.1.0.0.nupkg

这将生成一个 .nuspec 文件，其中包含了所有元数据（metadata）信息，你可以进一步编辑或查看这些信息。

生成带注释的 nuget 包

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

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

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

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

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework> <!-- 打包特定目标框架的项目 -->
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <GenerateDocumentationFile>true</GenerateDocumentationFile> <!-- 启用生成 XML 文档文件 -->
    <NoWarn>$(NoWarn);1591</NoWarn> <!-- 忽略缺少 XML 注释的警告 -->
  </PropertyGroup>

  <PropertyGroup>
    <PackageId>MyLibrary</PackageId> <!-- 包的 ID -->
    <VersionSuffix>$(VersionSuffix)</VersionSuffix> <!--使用给定的后缀打包当前项目，并更新生成的程序包版本-->
    <PackageVersion>1.0.0</PackageVersion> <!-- 包的版本号 -->
    <Authors>YourName</Authors> <!-- 作者 -->
    <Company>YourCompany</Company> <!-- 公司名称 -->
    <Copyright>© 2023 YourCompany</Copyright> <!-- 版权信息 -->
    <Description>This is a description of the package.</Description> <!-- 包的描述 -->
    <PackageTags>Tag1;Tag2</PackageTags> <!-- 包的标签 -->
    <PackageLicense>https://example.com/license</PackageLicense> <!-- 许可证 URL -->
    <!--<PackageLicenseUrl>https://example.com/license</PackageLicenseUrl>--> <!-- 许可证 URL -->
    <PackageProjectUrl>https://example.com/project</PackageProjectUrl> <!-- 项目 URL -->
    <RepositoryUrl>https://github.com/yourusername/mylibrary</RepositoryUrl> <!-- 仓库 URL -->
    <RepositoryType>git</RepositoryType> <!-- 仓库类型 -->
  </PropertyGroup>

  <ItemGroup>
    <Folder Include="test\nupkgs\" />
  </ItemGroup>

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