NuGet

NuGet 是 .NET 生态系统的包管理器,是开发人员发现和获取 .NET 开源库的主要方式。 NuGet.org是微软提供的用于托管 NuGet 包的免费服务,它是公共 NuGet 包的主要主机,但你也可以发布到自定义 NuGet 服务,例如 MyGetAzure Artifacts

NuGet

创建 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 包。

源链接会自动将 RepositoryUrlRepositoryType 元数据添加到 NuGet 包。 源链接还会添加有关生成包的确切源代码的信息。 例如,从 Git 存储库创建的包将添加提交哈希作为元数据。

预发行包

带有版本后缀的 NuGet 包被视为 预发行版。 默认情况下,NuGet 包管理器 UI 显示稳定版本,除非用户选择加入预发行版包,使预发行版包非常适合有限的用户测试。

<PackageVersion>1.0.1-beta1</PackageVersion>

注意

稳定包不能依赖于预发行版包。 必须创建自己的预发行包或依赖于较旧的稳定版本。

NuGet 预发行版包依赖项

✔️ 在测试、预览或试验时,请发布预发行版包。

✔️ 准备好后,请发布稳定包,以便其他稳定包可以引用它。

符号包

符号文件(*.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 的符号服务器添加到默认符号服务器列表中。