NuGet
NuGet 是 .NET 生态系统的包管理器,并且是开发人员用来发现并获取 .NET 开放源代码库的主要方法。 NuGet.org(由托管 NuGet 包的 Microsoft 提供的免费服务)是公共 NuGet 包的主要主机,但可以发布到自定义 NuGet 服务,如 MyGet 和 Azure Artifacts。
创建 NuGet 包
NuGet 包 (*.nupkg
) 是一个 zip 文件,其中包含 .NET 程序集和关联的元数据。
创建 NuGet 包有两种主要方式。 较新的推荐方式是从 SDK 样式项目(其内容以 <Project Sdk="Microsoft.NET.Sdk">
开头的项目文件)创建包。 程序集和目标会自动添加到包,剩余元数据会添加到 MSBuild 文件,如包名称和版本号。 使用 dotnet pack
命令编译会输出 *.nupkg
文件,而不是程序集。
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<AssemblyName>Contoso.Api</AssemblyName>
<PackageVersion>1.1.0</PackageVersion>
<Authors>John Doe</Authors>
</PropertyGroup>
</Project>
创建 NuGet 包的较旧方式是使用 *.nuspec
文件和 nuget.exe
命令行工具。 nuspec 文件为你提供更好的控制,但必须仔细指定要包含在最终 NuGet 包中的程序集和目标。 很容易犯错或很容易忘记在发生更改时更新 nuspec。 nuspec 的优点是可以将其用于创建尚不支持 SDK 样式项目文件的框架的 NuGet 包。
✔️ 请考虑使用 SDK 样式项目文件创建 NuGet 包。
包依赖项
依赖项一文详细介绍了 NuGet 包依赖项。
重要的 NuGet 包元数据
NuGet 包支持多个元数据属性。 下表包含 NuGet.org 上的每个包应提供的核心元数据:
MSBuild 属性名称 | Nuspec 名称 | 描述 |
---|---|---|
PackageId |
id |
包标识符。 如果标识符的前缀满足条件,则可以保留该前缀。 |
PackageVersion |
version |
NuGet 包版本。 有关详细信息,请参阅 NuGet 包版本。 |
Title |
title |
明了易用的包标题。 默认为 PackageId 。 |
Description |
description |
UI 中显示的包的详细说明。 |
Authors |
authors |
包创建者的逗号分隔列表,与 nuget.org 上的配置文件名称一致。 |
PackageTags |
tags |
描述包的标记和关键字的空格或分号分隔列表。 搜索包时使用标记。 |
PackageIcon |
icon |
包中要用作包图标的图像的路径。 详细了解 icon 元数据。 |
PackageProjectUrl |
projectUrl |
项目主页或源存储库的 URL。 |
PackageLicenseExpression |
license |
项目许可证的 SPDX 标识符。 只有获得 OSI 和 FSF 批准的许可证才能使用标识符。 其他许可证应使用 PackageLicenseFile 。 详细了解 license 元数据。 |
重要
无许可证的项目默认为 exclusive copyright(独占版权所有),从而无法供其他人使用。
✔️ 请考虑选择带有满足 NuGet 前缀预留条件的前缀的 NuGet 包名称。
✔️ 请使用指向包图标的 HTTPS href。
启用 HTTPS 运行并显示非 HTTPS 图像的 NuGet.org 等网站将创建混合内容警告。
✔️ 请使用属于 64x64 并具有透明背景的包图标图像以获得最佳查看结果。
✔️ 请考虑设置源链接以将源代码管理元数据添加到程序集和 NuGet 包中。
源链接会自动将
RepositoryUrl
和RepositoryType
元数据添加到 NuGet 包中。 源链接还会添加用于构建包的确切源代码的相关信息。 例如,从 Git 存储库创建的包将添加提交哈希作为元数据。
预发行包
具有版本后缀的 NuGet 包被视为预发行版。 默认情况下,NuGet 包管理器 UI 显示稳定版本,除非用户选择预发行包,使预发行包适用于受限的用户测试。
<PackageVersion>1.0.1-beta1</PackageVersion>
注意
稳定版包不能依赖于预发行包。 必须创建自己的预发行包或依赖于较旧的稳定版本。
✔️ 请在测试、预览或试用预发行包后进行发布。
✔️ 请在稳定版包就绪后进行发布,以便其他稳定版包可以引用它。
符号包
符号文件 (*.pdb
) 由 .NET 编译器与程序集一起生成。 符号文件将执行位置映射到原始源代码,以便可以逐行执行源代码(因为它使用调试程序运行)。 NuGet 支持生成单独的符号包 (*.snupkg
)(包含符号文件)以及主包(包含 .NET 程序集)。 符号包的理念是它们托管在符号服务器上并仅由 Visual Studio 等工具按需下载。
NuGet.org 托管了自己的符号服务器存储库。 开发人员可以通过向其在 Visual Studio 中的符号源添加 https://symbols.nuget.org/download/symbols
,来使用发布到 NuGet.org 符号服务器的符号。
重要
NuGet.org 符号服务器仅支持由 SDK 样式项目创建的新的可移植符号文件 (*.pdb
)。
若要在调试 .NET 库时使用 NuGet.org 符号服务器,开发人员必须安装有 Visual Studio 2017 版本 15.9 或更高版本。
创建符号包的另一种方法是在主 NuGet 包中嵌入符号文件。 主 NuGet 包将变大,但嵌入的符号文件意味着开发人员不需要配置 NuGet.org 符号服务器。 如果使用 SDK 样式项目生成 NuGet 包,则可以通过设置 AllowedOutputExtensionsInPackageBuildOutputFolder
属性来嵌入符号文件:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<!-- Include symbol files (*.pdb) in the built .nupkg -->
<AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
</PropertyGroup>
</Project>
嵌入式符号文件的缺点是,对于使用 SDK 样式项目编译的 .NET 库,它们会将包的大小增加约 30%。 如果要考虑包大小,应改成在符号包中发布符号。
✔️ 请考虑将符号作为符号包 (*.snupkg
) 发布到 NuGet.org
符号包 (
*.snupkg
) 为开发人员提供了良好的按需调试体验,而不会使主程序包大小膨胀,也不会影响那些不打算调试 NuGet 包的用户的还原性能。需要注意的是,用户可能需要在其 IDE 中查找和配置 NuGet 符号服务器(作为一次性设置)来获取符号文件。 Visual Studio 2019 版本 16.1 将 NuGet.org 的符号服务器添加到了默认符号服务器列表中。