dotNet符号文件(pdb)，符号包(snupkg)和SourceLink

2024-04-18 17:59:44

前言

本文的主题是 Visual Studio 调试 NuGet 包,以及符号包的概念，如何去发布一个 NuGet 包，让我们的 NuGet 包支持 SouceLink，这些都是我们开发中比较容易忽视的内容，但是熟悉了以后可以让我们在调试中得心应手，也是开源项目开发的基础篇。

demo 源代码在文末

pdb 符号文件

程序数据库 (.pdb) 文件（也称为符号文件）将项目源代码中的标识符和语句映射到已编译应用中的相应标识符和说明。 这些映射文件将调试器链接到源代码，以进行调试。

在 Visual Studio 调试器（C#、C++、Visual Basic、F#）中指定符号 (.pdb) 和源文件

符号文件的工作方式

.pdb 文件保存调试和项目状态信息，使用这些信息可以对应用的调试配置进行增量链接。 在调试时，Visual Studio 调试器使用 .pdb 文件来确定两项关键信息：

  • 要在 Visual Studio IDE 中显示的源文件名和行号。
  • 在应用中停止的断点位置。

调试器只会加载与在生成应用时创建的 .pdb 文件完全匹配的 .pdb 文件（即原始 .pdb 文件或副本）。

我们随便找一个自己代码的类库 Build 可以看一下
image

简单的讲：我们平时在 Visual Studio 中调试代码 编译后的dll 文件在和 VS 内代码文件，断点等各种调试操作都是跟.pdb 文件内记录的信息做的映射。

符号包 (.snupkg)

创建符号包

符号包提供了一些关键信息，例如已编译的代码与源代码之间的关联、局部变量的名称、堆栈跟踪,代码源文件映射等。 你可以使用符号包 (.snupkg) 来分发这些符号(.pdb)，并改善 NuGet 包的调试体验。

创建符号包

有两种方式可以创建符号包

  • .csproj 文件添加属性
<PropertyGroup>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>
  • 打包时指定参数
dotnet pack MyPackage.csproj -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg

那我们创建一个类库先用第二种命令行打包测试一下看看效果

image

可以看到我们的符号包已经成功创建了。

接下来我们看一下符号包里面有什么东西
这里面用NuGetPackageExplorer本地工具，直接打开本地的包
image

可以看到我们的.pdb 文件已经被打包到符号包中

源链接将源代码管理元数据添加到程序集和 NuGet 包，这么做的好处是进一步的获得最佳调试体验，把源链接元数据跟符号包中的pdb文件绑定

github sourcelink

从.NET 8 开始，.NET SDK 默认包含对以下来源控制提供商的源链接（Source Link）支持：

  • GitHub 或 GitHub Enterprise
  • Azure Repos git 仓库（之前称为 Visual Studio Team Services）
  • GitLab 12.0+（对于旧版本，请查看 GitLab 设置）
  • Bitbucket 4.7+（对于旧版本，请查看 Bitbucket 设置）

如果您的项目使用.NET SDK 8+并托管在上述提供商中，则无需引用任何 Source Link 包或设置任何构建属性，Source Link 已默认启用。

否则，您可以通过设置几个属性并添加适用于提供商的 Source Link 包的 PackageReference 来启用项目中的 Source Link 体验，这样可以实现在指定的来源控制环境中进行无缝调试和源代码导航。
配置如下

<Project>
 <PropertyGroup>
    <!-- Optional: Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
    <PublishRepositoryUrl>true</PublishRepositoryUrl>

    <!-- Optional: Embed source files that are not tracked by the source control manager in the PDB -->
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
  </PropertyGroup>
  <ItemGroup>
    <!-- Add PackageReference specific for your source control provider (see below) -->
  </ItemGroup>
</Project>

如果你在 dotNet 8+ 的环境中引用任何的源代码管理包比如
github.com and GitHub Enterprise

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

会禁用.NET SDK 中包含的 Source Link 功能。

本文的所有案例默认都是用 dotNet8 开发的 那按照说明如果代码在 github 那默认可以不用安装任何 SourceLink 的 package

接下来我们继续测试一下在类库中添加对应的属性

先提交一下代码，再打 pack
image

从这可以看出我们的 pdb 符号文件已经包含了 git 的源代码信息。

推送 Nuget 包

发布 Nuget 包
我们这里使用dotnet cli推送
用命令行推送.nupkg包同名的.snupkg符号包默认也会被推送到 nuget.org

 dotnet nuget push dotNetParadise-SourceLink.1.0.1.nupkg -s https://api.nuget.org/v3/index.json --api-key %nugetApiKey%

image

现在 NuGet 包已经推送上去了第一次推送的包 NuGet 平台需要对其进行索引病毒扫描等 大概需要几分钟

image

可以看到我们的符号包以及源代码地址都已经在 NuGet 平台显示了。

VS 调试部分

前面做的部分实际上都是为了我们在给用户用的时候方便调试，那我们来调试一下看看这个过程。
创建新项目->NuGet 安装刚才上传的包

dotnet add package dotNetParadise-SourceLink --version 1.0.1

调试器查找符号文件的位置

  • 项目文件夹。

  • 在 DLL 或可执行 (.exe) 文件中指定的位置。

    • 默认情况下，如果你在计算机上已生成 DLL 或 .exe 文件，则链接器会将关联的 .pdb 文件的完整路径和文件名放入 DLL 或 .exe 文件中 。 调试器会检查该位置是否存在符号文件。

  • 与 DLL 或 .exe 文件相同的文件夹。

  • 在调试器选项中为符号文件指定的任何位置。

    • 任何本地符号缓存文件夹。

    • 指定的网络、Internet 或本地符号服务器和位置，例如 Microsoft 符号服务器（如果选择）。 Visual Studio 可从实现 symsrv 协议的符号服务器下载调试符号文件。 Visual Studio Team Foundation Server 和 Windows 调试工具是可使用符号服务器的两个工具。

  • 可能会用到的符号服务器包括：

    • 公共 Microsoft 符号服务器：要调试在调用系统 DLL 或第三方库时出 现的故障，通常需要系统 .pdb 文件。 系统 .pdb 文件包含 Windows DL、.exe 文件和设备驱动程序的符号 。 你可以从公共 Microsoft 符号服务器获取 Windows 操作系统、MDAC、IIS、ISA 和 .NET 的符号。

    • 内部网络或本地计算机上的符号服务器：你的团队或公司可为你自己的产品创建符号服务器，并作为外部源符号的缓存。 你自己的计算机上可能具有符号服务器。

    • 第三方符号服务器：Windows 应用程序和库的第三方提供程序可提供对 Internet 上的符号服务器的访问。

了解了这部分信息之后，我们的符号包是在 Nuget.org 中所以，需要在 Vs 中开启如下配置
image

VS 工具->选项->调试->符号 开启上面符号服务器的选中，可以设置一个本地缓存的文件夹，另外下面选择仅加载指定模块（如果开启上面除了排除的全部加载大项目调试起来有点难受）

VS 工具->选项->调试-常规
image

第一步要禁用启用仅我的代码

第二部 启用源服务器的支持

到这儿基本上配置已经全部完成了

实战测试一下
我们的类库实际上是封装了一个 MinimalApis 的自动注册功能，感兴趣的朋友可以去读一下我之前的文章

public class TodoApi : IEndPoint
{
    public void MapEndPoints(IEndpointRouteBuilder app)
    {
        var group = app.MapGroupWithTags("Todo");
        group.MapGet("sayhello", (string name) => $"hello {name}");
    }
}

创建一个 api 在 program 调用类库方法注册一下

app.RegisterEndPoints();

image

可以看到很对 NuGet 类库 源码的调试就舒服多了，可以加断点修改代码，加类库调试。

最后

简要摘要：

本文介绍了在 Visual Studio中调试 NuGet 包的相关概念，包括 PDB 符号文件、符号包、Source Link 功能以及发布支持 Source Link 的 NuGet 包。通过配置符号包和 Source Link，开发者可以更轻松地调试外部依赖项的源代码，提高调试效率。

总结：

  • PDB 符号文件和符号包在调试中起着关键作用，帮助将源代码映射到编译后的应用程序，提供更详细的调试信息。
  • Source Link 通过在程序集和 NuGet 包中添加源代码管理元数据，实现了方便调试外部依赖项的功能。
  • 配置符号服务器路径和 Source Link 选项可以使 Visual Studio 更好地支持调试 NuGet 包的源代码。

本文Demo 源代码

希望本文能对你有帮助！

上一篇：数学建模常用代码


下一篇：产品经理方法论——MRD文档模板】-三、文档框架