让你发布的nuget包支持源代码调试
前情概要
在不久的从前(也还是要以年为单位哈), 我们如果需要调试第三方代码, 或者框架代码很麻烦. 需要配置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和.pdb2个文件. - 在目前阶段, 不同的框架(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 的解决方案.
更新于 2022年8月29日, VS2022没有WebBrower了,并且gitlab不再支持IE浏览器. 请参考Gitlab私有存储库支持SourceLink 调试之使用proxy方式
如果只是临时的调试一下源代码可以有更简单粗暴的方法, 在vs中用Web Browesr 登录一下gitlab就完事了.
哈!, 就是这么简单粗暴.
