创建符号包 (.snupkg)

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

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

必备条件

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

创建符号包

如果使用 dotnet CLI 或 MSBuild,则除 .nupkg 文件外,还需要设置 IncludeSymbolsSymbolPackageFormat 属性以创建 .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 文件进行调试。

  1. 为方便起见,首先使用 NuGet 保存 API 密钥(请参阅发布包)。

    nuget SetApiKey Your-API-Key
    
  2. 将主包发布到 nuget.org 后,按如下方式推送符号包。

    nuget push MyPackage.snupkg
    
  3. 还可以使用以下命令同时推送主包和符号包。 当前文件夹中必须同时有 .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) 具有以下特征:

  1. .snupkg 与相应的 NuGet 包 (.nupkg) 具有相同的 ID 和版本。

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

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

    <packageTypes>
       <packageType name="SymbolsPackage"/>
    </packageTypes>
    
  4. 如果创建者决定使用自定义 nuspec 来构建其 nupkg 和 snupkg,则 snupkg 应该具有 2 中详细描述的同一文件夹层次结构和文件)。

  5. 将从 snupkg 的 nuspec 中排除以下字段:authorsownersrequireLicenseAcceptancelicense typelicenseUrlicon

  6. 不要使用 <license> 元素。 .snupkg 与对应的 .nupk 位于同一个许可证中。

另请参阅

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

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