dotNet符號檔案(pdb)，符號包(snupkg)和SourceLink

董瑞鹏發表於2024-03-25
符號

前言

本文的主題是 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 原始碼

希望本文能對你有幫助！

相關文章