创建符号包 (.snupkg)Creating symbol packages (.snupkg)

10/30/2018

本文内容

良好的调试体验依赖于调试符号的存在，因为它们提供了一些关键信息，例如已编译的代码与源代码之间的关联、局部变量的名称、堆栈跟踪等。A good debugging experience relies on the presence of debug symbols as they provide critical information like the association between the compiled and the source code, names of local variables, stack traces, and more. 你可以使用符号包 (.snupkg) 来分发这些符号，并改善 NuGet 包的调试体验。You can use symbol packages (.snupkg) to distribute these symbols and improve the debugging experience of your NuGet packages.

必备条件Prerequisites

创建符号包Creating a symbol package

如果使用 dotnet CLI 或 MSBuild，则除 .nupkg 文件外，还需要设置 IncludeSymbols 和 SymbolPackageFormat 属性以创建 .snupkg 文件。If you're using dotnet CLI or MSBuild, you need to set the IncludeSymbols and SymbolPackageFormat properties to create a .snupkg file in addition to the .nupkg file.

要么将以下属性添加到 .csproj 文件：Either add the following properties to your .csproj file:

true

snupkg

要么在命令行上指定这些属性：Or specify these properties on the command-line:

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

或or

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

如果使用 NuGet.exe，除 .nupkg 文件外，可以使用以下命令创建一个 .snupkg 文件：If you're using NuGet.exe, you can use the following commands to create a .snupkg file in addition to the .nupkg file:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

SymbolPackageFormat 属性可以有下列两个值之一：symbols.nupkg(默认值)或 snupkg。The SymbolPackageFormat property can have one of two values: symbols.nupkg (the default) or snupkg. 如果未指定此属性，将会创建旧的符号包。If this property is not specified, a legacy symbol package will be created.

备注

仍支持旧格式 .symbols.nupkg，但仅出于兼容性原因(请参阅旧版符号包)。The legacy format .symbols.nupkg is still supported but only for compatibility reasons (see Legacy Symbol Packages). NuGet.org 的符号服务器只接受新的符号包格式，即 .snupkg。NuGet.org's symbol server only accepts the new symbol package format - .snupkg.

发布符号包Publishing a symbol package

为方便起见，首先使用 NuGet 保存 API 密钥(请参阅发布包)。For convenience, first save your API key with NuGet (see publish a package).

nuget SetApiKey Your-API-Key

将主包发布到 nuget.org 后，按如下方式推送符号包。After publishing your primary package to nuget.org, push the symbol package as follows.

nuget push MyPackage.snupkg

还可以使用以下命令同时推送主包和符号包。You can also push both primary and symbol packages at the same time using the below command. 当前文件夹中必须同时有 .nupkg 和 .snupkg 文件。Both .nupkg and .snupkg files need to be present in the current folder.

nuget push MyPackage.nupkg

NuGet 会将两个包发布到 nuget.org。MyPackage.nupkg 先发布，随后 MyPackage.snupkg 发布。NuGet will publish both packages to nuget.org. MyPackage.nupkg will be published first, followed by MyPackage.snupkg.

备注

如果没有发布符号包，请检查是否已将 NuGet.org 源配置为 https://api.nuget.org/v3/index.json。If the symbol package isn't published, check that you've configured the NuGet.org source as https://api.nuget.org/v3/index.json. Symbol package publishing is only supported by the NuGet V3 API.

NuGet.org 符号服务器NuGet.org symbol server

NuGet.org 支持自己的符号服务器存储库，只接受新的符号包格式 - .snupkg。NuGet.org supports its own symbols server repository and only accepts the new symbol package format - .snupkg. 包使用者可将 https://symbols.nuget.org/download/symbols 添加到 Visual Studio 中的符号源，使用发布到 nuget.org 符号服务器的符号，这允许在 Visual Studio 调试程序中单步执行包代码。Package consumers can use the symbols published to nuget.org symbol server by adding https://symbols.nuget.org/download/symbols to their symbol sources in Visual Studio, which allows stepping into package code in the Visual Studio debugger.

NuGet.org 符号包约束NuGet.org symbol package constraints

NuGet.org 对符号包具有以下约束：NuGet.org has the following constraints for symbol packages:

符号包中仅允许使用以下文件扩展名：.pdb、.nuspec、.xml、.psmdcp、.rels、.p7sOnly the following file extensions are allowed in symbol packages: .pdb, .nuspec, .xml, .psmdcp, .rels, .p7s

NuGet.org 符号服务器目前仅支持托管的可移植 PDB。Only managed Portable PDBs are supported on NuGet.org's symbol server.

需要使用 Visual Studio 15.9 或更高版本中的编译器构建 PDB 及其关联的 nupkg DLL(请参阅 PDB 加密哈希)The PDBs and their associated .nupkg DLLs need to be built with the compiler in Visual Studio version 15.9 or above (see PDB crypto hash)

如果未满足这些约束，则发布到 NuGet.org 的符号包将无法通过验证。Symbol packages published to NuGet.org will fail validation if these constraints aren't met.

符号包验证和编制索引Symbol package validation and indexing

发布到 NuGet.org 的符号包会接受多项验证，包括恶意软件扫描。Symbol packages published to NuGet.org undergo several validations, including malware scanning. 如果包未通过验证检查，则其包详细信息页将显示错误消息。If a package fails a validation check, its package details page will display an error message. 此外，包的所有者还将收到一封电子邮件，其中包含有关如何解决已识别问题的说明。In addition, the package's owners will receive an email with instructions on how to fix the identified issues.

当符号包通过所有验证后，NuGet.org 的符号服务器将为其中的符号编制索引，并且这些符号将可供使用。When the symbol package has passed all validations, the symbols will be indexed by NuGet.org's symbol servers and will be available for consumption.

包验证和编制索引所需的时间通常不超过 15 分钟。Package validation and indexing usually takes under 15 minutes. 如果发布包所用时间超出预期，请访问 status.nuget.org 检查 NuGet.org 是否遇到任何中断。If the package publishing takes longer than expected, visit status.nuget.org to check if NuGet.org is experiencing any interruptions. 如果所有系统均正常运行，但一个小时之内还未成功发布包，请登录 nuget.org 并使用包详细信息页面上的“联系支持人员”链接与我们联系。If all systems are operational and the package hasn't been successfully published within an hour, please login to nuget.org and contact us using the Contact Support link on the package details page.

符号包结构Symbol package structure

符号包 (.snupkg) 具有以下特征：The symbol package (.snupkg) has the following characteristics:

.snupkg 与相应的 NuGet 包 (.nupkg) 具有相同的 ID 和版本。The .snupkg has the same id and version as its corresponding NuGet package (.nupkg).

.snupkg 具有与任何 DLL 或 EXE 文件的相应 .nupkg 相同的文件夹结构，区别在于其相应的 PDB 将包含在同一文件夹层次结构中，而不是 DLL/EXE 中。The .snupkg has the same folder structure as its corresponding .nupkg for any DLL or EXE files with the distinction that instead of DLLs/EXEs, their corresponding PDBs will be included in the same folder hierarchy. 扩展名不是 PDB 的文件和文件夹将被排除在 snupkg 之外。Files and folders with extensions other than PDB will be left out of the snupkg.

符号包的 .nuspec 文件具有 SymbolsPackage 包类型：The symbol package's .nuspec file has the SymbolsPackage package type:

如果创建者决定使用自定义 nuspec 来构建其 nupkg 和 snupkg，则 snupkg 应该具有 2 中详细描述的同一文件夹层次结构和文件)。If an author decides to use a custom nuspec to build their nupkg and snupkg, the snupkg should have the same folder hierarchy and files detailed in 2).

将从 snupkg 的 nuspec 中排除以下字段：authors、owners、requireLicenseAcceptance、license type、licenseUrl 和 icon。The following fields will be excluded from the snupkg's nuspec: authors, owners, requireLicenseAcceptance, license type, licenseUrl, and icon.

不要使用 元素。Do not use the element. .snupkg 与对应的 .nupk 位于同一个许可证中。A .snupkg is covered under the same license as the corresponding .nupkg.

另请参阅See also

考虑使用源链接来启用 .NET 程序集的源代码调试。Consider using Source Link to enable source code debugging of .NET assemblies. 有关详细信息，请参阅源链接指南。For more information, please refer to the Source Link guidance.

有关符号包的更多信息，请参阅 NuGet 包调试与符号改进设计规范。For more information on symbol packages, please refer to the NuGet Package Debugging & Symbols Improvements design spec.