创建符号包 (.snupkg)

项目
08/10/2023

良好的调试体验依赖于调试符号的存在，因为它们提供了一些关键信息，例如已编译的代码与源代码之间的关联、局部变量的名称、堆栈跟踪等。你可以使用符号包 (.snupkg) 来分发这些符号，并改善 NuGet 包的调试体验。

请注意，符号包并不是使调试符号可用于库使用者的唯一策略。还可以通过以下项目属性在 dll 或 exe 中 embed 它们：<DebugType>embedded</DebugType>

先决条件

nuget.exe v4.9.0 或更高版本或 dotnet CLI v2.2.0 或更高版本，它们实现了所需的 NuGet 协议。

创建符号包

如果使用 dotnet CLI 或 MSBuild，则除 .nupkg 文件外，还需要设置 IncludeSymbols 和 SymbolPackageFormat 属性以创建 .snupkg 文件。

要么将以下属性添加到 .csproj 文件：

<PropertyGroup>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>

要么在命令行上指定这些属性：

dotnet pack MyPackage.csproj -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg

或

msbuild MyPackage.csproj /t:pack /p:IncludeSymbols=true /p:SymbolPackageFormat=snupkg

如果使用 NuGet.exe，除 .nupkg 文件外，可以使用以下命令创建一个 .snupkg 文件：

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

SymbolPackageFormat 属性可以有下列两个值之一：symbols.nupkg（默认值）或 snupkg。如果未指定此属性，将会创建旧的符号包。

注意

旧格式 .symbols.nupkg 仍受支持，但只是出于兼容性的原因，例如本机包（请参阅旧版符号包）。 NuGet.org 的符号服务器只接受新的符号包格式，即 .snupkg。

发布符号包

注意

Azure Devops Artifacts 当前不支持通过 .snupkg 文件进行调试。

为方便起见，首先使用 NuGet 保存 API 密钥（请参阅发布包）。
```
nuget SetApiKey Your-API-Key
```
将主包发布到 nuget.org 后，按如下方式推送符号包。
```
nuget push MyPackage.snupkg
```
还可以使用以下命令同时推送主包和符号包。当前文件夹中必须同时有 .nupkg 和 .snupkg 文件。
```
nuget push MyPackage.nupkg
```

NuGet 会将两个包发布到 nuget.org。MyPackage.nupkg 先发布，随后 MyPackage.snupkg 发布。

注意

如果没有发布符号包，请检查是否已将 NuGet.org 源配置为 https://api.nuget.org/v3/index.json。只有 NuGet V3 API 才支持符号包发布。

NuGet.org 符号服务器

NuGet.org 支持自己的符号服务器存储库，只接受新的符号包格式 - .snupkg。包使用者可将 https://symbols.nuget.org/download/symbols 添加到 Visual Studio 中的符号源，使用发布到 nuget.org 符号服务器的符号，这允许在 Visual Studio 调试程序中单步执行包代码。有关该过程的详细信息，请参阅在 Visual Studio 调试程序中指定符号 (.pdb) 和源文件。

NuGet.org 符号包约束

NuGet.org 对符号包具有以下约束：

符号包中仅允许使用以下文件扩展名：.pdb、.nuspec、.xml、.psmdcp、.rels、.p7s
NuGet.org 符号服务器目前仅支持托管的可移植 PDB。
需要使用 Visual Studio 15.9 或更高版本中的编译器构建 PDB 及其关联的 nupkg DLL（请参阅 PDB 加密哈希）

如果未满足这些约束，则发布到 NuGet.org 的符号包将无法通过验证。

注意

本机项目（如 C++ 项目）生成 Windows PDB，而不是可移植的 PDB。 NuGet.org 的符号服务器不支持这些 PDB。请改用旧版符号包。

符号包验证和编制索引

发布到 NuGet.org 的符号包会接受多项验证，包括恶意软件扫描。如果包未通过验证检查，则其包详细信息页将显示错误消息。此外，包的所有者还将收到一封电子邮件，其中包含有关如何解决已识别问题的说明。

当符号包通过所有验证后，NuGet.org 的符号服务器将为其中的符号编制索引，并且这些符号将可供使用。

包验证和编制索引所需的时间通常不超过 15 分钟。如果发布包所用时间超出预期，请访问 status.nuget.org 检查 NuGet.org 是否遇到任何中断。如果所有系统均正常运行，但一个小时之内还未成功发布包，请登录 nuget.org 并使用包详细信息页面上的“联系支持人员”链接与我们联系。

符号包结构

符号包 (.snupkg) 具有以下特征：

.snupkg 与相应的 NuGet 包 (.nupkg) 具有相同的 ID 和版本。
.snupkg 具有与任何 DLL 或 EXE 文件的相应 .nupkg 相同的文件夹结构，区别在于其相应的 PDB 将包含在同一文件夹层次结构中，而不是 DLL/EXE 中。扩展名不是 PDB 的文件和文件夹将被排除在 snupkg 之外。

符号包的 .nuspec 文件具有 SymbolsPackage 包类型：

<packageTypes>
   <packageType name="SymbolsPackage"/>
</packageTypes>

如果创建者决定使用自定义 nuspec 来构建其 nupkg 和 snupkg，则 snupkg 应该具有 2 中详细描述的同一文件夹层次结构和文件）。
将从 snupkg 的 nuspec 中排除以下字段：authors、owners、requireLicenseAcceptance、license type、licenseUrl 和 icon。
不要使用 <license> 元素。 .snupkg 与对应的 .nupk 位于同一个许可证中。

另请参阅

考虑使用源链接来启用 .NET 程序集的源代码调试。有关详细信息，请参阅源链接指南。

有关符号包的更多信息，请参阅 NuGet 包调试与符号改进设计规范。