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

前言本文的主題是 Visual Studio 調試 NuGet 包,以及符號包的概念，如何去發佈一個 NuGet 包，讓我們的 NuGet 包支持 SouceLink，這些都是我們開發中比較容易忽視的內容，但是熟悉了以後可以讓我們在調試中得心應手，也是開源項目開發的基礎篇。 demo 源代碼在文末 ...

前言

本文的主題是 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 可以看一下

簡單的講：我們平時在 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

那我們創建一個類庫先用第二種命令行打包測試一下看看效果

可以看到我們的符號包已經成功創建了。

接下來我們看一下符號包裡面有什麼東西
這裡面用NuGetPackageExplorer本地工具，直接打開本地的包

可以看到我們的.pdb 文件已經被打包到符號包中

SourceLink 源鏈接

源鏈接將源代碼管理元數據添加到程式集和 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

從這可以看出我們的 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%

現在 NuGet 包已經推送上去了第一次推送的包 NuGet 平臺需要對其進行索引病毒掃描等大概需要幾分鐘

可以看到我們的符號包以及源代碼地址都已經在 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 中開啟如下配置

VS 工具->選項->調試->符號開啟上面符號伺服器的選中，可以設置一個本地緩存的文件夾，另外下麵選擇僅載入指定模塊（如果開啟上面除了排除的全部載入大項目調試起來有點難受）

VS 設置 SourceLink

VS 工具->選項->調試-常規

第一步要禁用啟用僅我的代碼

第二部啟用源伺服器的支持

到這兒基本上配置已經全部完成了

實戰測試一下
我們的類庫實際上是封裝了一個 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();

可以看到很對 NuGet 類庫源碼的調試就舒服多了，可以加斷點修改代碼，加類庫調試。

最後

簡要摘要：

本文介紹了在 Visual Studio中調試 NuGet 包的相關概念，包括 PDB 符號文件、符號包、Source Link 功能以及發佈支持 Source Link 的 NuGet 包。通過配置符號包和 Source Link，開發者可以更輕鬆地調試外部依賴項的源代碼，提高調試效率。

總結：

PDB 符號文件和符號包在調試中起著關鍵作用，幫助將源代碼映射到編譯後的應用程式，提供更詳細的調試信息。
Source Link 通過在程式集和 NuGet 包中添加源代碼管理元數據，實現了方便調試外部依賴項的功能。
配置符號伺服器路徑和 Source Link 選項可以使 Visual Studio 更好地支持調試 NuGet 包的源代碼。

本文Demo 源代碼

希望本文能對你有幫助！

本文來自博客園，作者：董瑞鵬，轉載請註明原文鏈接：https://www.cnblogs.com/ruipeng/p/18093758