讓你發布的nuget包支持源代碼調試

本文轉載自查看原文 2021-07-07 17:43 339 asp.net core/ .Net Core/ dotnet/ 技術集成

前情概要

在不久的從前(也還是要以年為單位哈), 我們如果需要調試第三方代碼, 或者框架代碼很麻煩. 需要配置symbols, 匹配原始代碼路徑等.
為此, MS推出了 Source Link 功能, 詳細的介紹請查看官方repo 的 readme.

Copy+google翻譯過來的介紹:

Source Link 是一個與語言和源代碼控制無關的系統，用於為二進制文件提供一流的源代碼調試體驗。該項目的目標是讓任何構建NuGet 庫的人都能夠毫不費力地為其用戶提供源代碼調試。Microsoft 庫（例如 .NET Core 和 Roslyn）已啟用 Source Link。Microsoft 支持源鏈接。

Source Link 是一組包和規范，用於描述可以嵌入到符號、二進制文件和包中的源代碼控制元數據。

Visual Studio 15.3+ 支持在調試時從符號讀取源鏈接信息。它為用戶下載並顯示適當的特定於提交的源，例如來自raw.githubusercontent，啟用斷點和對任意 NuGet 依賴項的所有其他源調試體驗。Visual Studio 15.7+ 支持從需要身份驗證的私有 GitHub 和 Azure DevOps（以前的 VSTS）存儲庫下載源文件。

在最初的來源鏈接的實現是通過提供@ctaggart。謝謝！.NET 團隊和 Cameron 共同努力使此實現在 .NET Foundation 中可用。

如果您是從原始 Source Link 文檔到達這里的 - 您不需要使用SourceLink.Create.CommandLine. 您只需要安裝下面列出的軟件包。

到目前為止, 主流的nuget package 都已經支持了. 例如MS官方的包, protobuf-net, Newtonsoft.Json 等.

首先, 先介紹如何源代碼調試支持Sourcelink的包.

我們僅需要修改vs的配置.

首先, 禁用 Just My Code 功能
然后, 啟用 Source Server Support 和 Source Link Support

我們就可以 `F11` 進入源代碼了

就是這么簡單, 就是這么順滑.

然后, 本文的重點來了, 讓我們自己的nuget包也支持這么棒的功能!!!

為我們的項目添加SourceLink支持

<Project>
	<PropertyGroup>
		<DebugType>embedded</DebugType>
		<DebugSymbols>true</DebugSymbols>
		<PublishRepositoryUrl>true</PublishRepositoryUrl>
	</PropertyGroup>

	<!--<PropertyGroup Condition="'$(GITLAB_CI)' == 'true'">-->
	<PropertyGroup Condition="'$(Configuration)' == 'Release'">
		<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
		<Deterministic>true</Deterministic>
		<EmbedUntrackedSources>true</EmbedUntrackedSources>
	</PropertyGroup>
	<ItemGroup>
		<PackageReference Include="Microsoft.SourceLink.GitLab" Version="1.0.0" PrivateAssets="All"/>
	</ItemGroup>
</Project>

這些代碼可以添加的項目的.csproj文件中, 也可以為整個solution的所有project添加.
為整個solution添加, 我們可以在.sln文件的同級目錄下增加文件 Directory.Build.props, 然后把上面代碼copy進行就可以了.

接下來簡單解釋一下這些改動都是啥意思, 其實在Source Link解釋的非常清楚了. 強烈建議看官方文檔.

DebugType 為啥用 embedded呢? 首先它的意思是把pdb的信息直接打包到dll文件中.
- 它的好處
  - 一個.dll文件就夠了, 不在要生成 .dll和.pdb 2個文件.
  - 在目前階段, 不同的框架(nfx, netcore 2.x, 3.x, 5.x),不同的vs(msbuild)版本下, 對pdb文件的處理各不相同. 比如vs 16.10 和netcore 2.x 它在build或者release的時候就不copy nuget packages 里面的pdb文件. 當然這個問題官方也在解決,但是比較緩慢, 反正我知道這個問題就已經好幾年了, 到目前位置github上的issue還在討論來討論去...
- 壞處
  - 比較明顯的增加的文件的體積.
DebugSymbols 我想應該不用解釋
PublishRepositoryUrl 將源代碼的git信息編譯到dll和打包到nuget package 上.
ContinuousIntegrationBuild 和 Deterministic 表示確定性編譯. 具體解釋請查看Here
EmbedUntrackedSources 跟蹤build生成的代碼文件. 比如我有模板代碼在build時生成, 或者由PublishRepositoryUrl生成的比如assemble attribute文件等.
沒有設置的時候

設置好了的時候
添加Microsoft.SourceLink.[your git repo]包, 比如我DEMO這個項目用的是gitlab, 那我添加的就是Microsoft.SourceLink.GitLab. 目前SouceLink支持 github, gitlab, azure, bitbucket, gitweb, gitea.
- PrivateAssets設置為All的意思是:這個包只有在編譯調試的時候使用, 打包到nuget的時候它不會添加進去.

驗證我們的dll或者pdb已經支持SourceLink了

首先我們先安裝sourcelink工具.

dotnet tool install -g sourcelink

接着測試一下我們的dll是否已經支持了

sourcelink print-json .\protobuf-net.Core.dll
sourcelink print-urls .\protobuf-net.Core.dll

當然也可以用

sourcelink test .\protobuf-net.Core.dll

到這里就基本完成了, 把包發布到nuget package上就可以, 可以是nuget.org, 也可以是myget, 更可以你公司內部的私有nuget package 服務器.

如果你和我一樣, 用的是gitlab的私有git repo, 那可以繼續看下去.

為gitlab的私有源代碼項目提供支持.

如果是gitlab的私有git repo. 在sourcelink test的時候會收到類似下面的錯誤

https://gitlab.com/myproject/mysourcecode.cs
error: url failed ServiceUnavailable: Service Temporarily Unavailable
sourcelink test failed

這是因為gitlab目前為止不支持基本身份驗證, 另外對於如果你是github的私有repo不用擔心. 只需要把Enable Source Link Support的下面的Fall back to GCM 選項勾起就可以了(參考我們僅需要修改vs的配置小節的截圖).
具體的issue可以參考:
Add support for Git Credential Manager on Windows
Support private GitLab repositories
如果要解決這個問題可以參考 https://github.com/rgl/gitlab-source-link-proxy 的解決方案.

如果只是臨時的調試一下源代碼可以有更簡單粗暴的方法, 在vs中用Web Browesr 登錄一下gitlab就完事了.

哈!, 就是這么簡單粗暴.