让你发布的nuget包支持源代码调试

2024-01-12 13:34:04

前情概要

在不久的从前(也还是要以年为单位哈), 我们如果需要调试第三方代码, 或者框架代码很麻烦. 需要配置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就完事了.

哈!, 就是这么简单粗暴.

最后, 一些有用的Links