如何使用 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