NuGet
NuGet 是 .NET 生态系统的包管理器,是开发人员发现和获取 .NET 开源库的主要方式。 NuGet.org是微软提供的用于托管 NuGet 包的免费服务,它是公共 NuGet 包的主要主机,但你也可以发布到自定义 NuGet 服务,例如 MyGet 和 Azure Artifacts。
创建 NuGet 包
NuGet 包(*.nupkg
)是包含 .NET 程序集和关联元数据的 zip 文件。
创建 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 元数据。 |
重要
没有许可证的项目默认 独家版权,使其他人在法律上不可能使用。
✔️ 请考虑选择一个 NuGet 包名称,该名称的前缀符合 NuGet 前缀预留条件 和。
✔️ 请使用指向包图标的 HTTPS href。
像 NuGet.org 这样的站点启用 HTTPS 后,如果显示非 HTTPS 图像,将会创建混合内容警告。
✔️ 请使用 64x64 且具有透明背景的包图标图像,以便获得最佳查看结果。
✔️ 请考虑设置 源链接,将源代码管理元数据添加到程序集和 NuGet 包。
源链接会自动将
RepositoryUrl
和RepositoryType
元数据添加到 NuGet 包。 源链接还会添加有关生成包的确切源代码的信息。 例如,从 Git 存储库创建的包将添加提交哈希作为元数据。
预发行包
带有版本后缀的 NuGet 包被视为 预发行版。 默认情况下,NuGet 包管理器 UI 显示稳定版本,除非用户选择加入预发行版包,使预发行版包非常适合有限的用户测试。
<PackageVersion>1.0.1-beta1</PackageVersion>
注意
稳定包不能依赖于预发行版包。 必须创建自己的预发行包或依赖于较旧的稳定版本。
✔️ 在测试、预览或试验时,请发布预发行版包。
✔️ 准备好后,请发布稳定包,以便其他稳定包可以引用它。
符号包
符号文件(*.pdb
)由 .NET 编译器与程序集一起生成。 符号文件将执行位置映射到原始源代码,以便使用调试器时可以逐步调试源代码。 NuGet 支持 生成一个单独的符号包(*.snupkg
), 该符号包包含符号文件,而主包则包含 .NET 程序集。 符号包的想法是它们托管在符号服务器上,并且仅由 Visual Studio 等工具按需下载。
NuGet.org 承载自己的 符号服务器存储库。 开发人员可以使用发布到 NuGet.org 符号服务器的符号,方法是将 https://symbols.nuget.org/download/symbols
添加到 Visual Studio 中的符号源。
重要
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 的符号服务器添加到默认符号服务器列表中。