探索.NET Core的SourceLink-逐步进入您不拥有的NuGet软件包的源代码

According to https://github.com/dotnet/sourcelink, SourceLink "enables a great source debugging experience for your users, by adding source control metadata to your built assets."

根据https://github.com/dotnet/sourcelink的说法，SourceLink通过将源代码控制元数据添加到已构建的资产中，为用户提供了出色的源代码调试体验。

Sounds fantastic. I download a NuGet to use something like Json.NET or whatever all the time, I'd love to be able to "Step Into" the source even if I don't have laying around. Per the GitHub, it's both language and source control agnostic. I read that to mean "not just C# and not just GitHub."

听起来很棒。 我下载了一个NuGet来一直使用Json.NET之类的东西，或者一直使用它，我希望能够“逐步进入”源代码，即使我没有闲逛也是如此。 根据GitHub，它与语言和源代码控制均无关。 我读到的意思是“不仅是C＃，还不仅仅是GitHub”。

Visual Studio 15.3+ supports reading SourceLink information from symbols while debugging. It downloads and displays the appropriate commit-specific source for users, such as from raw.githubusercontent, enabling breakpoints and all other sources debugging experience on arbitrary NuGet dependencies. Visual Studio 15.7+ supports downloading source files from private GitHub and Azure DevOps (former VSTS) repositories that require authentication.

Visual Studio 15.3+支持在调试时从符号读取SourceLink信息。 它为用户下载并显示适当的特定于提交的源，例如从raw.githubusercontent ，启用断点以及所有其他对任意NuGet依赖项进行调试的源。 Visual Studio 15.7+支持从需要身份验证的私有GitHub和Azure DevOps(以前的VSTS)存储库下载源文件。

Looks like Cameron Taggart did the original implementation and then the .NET team worked with Cameron and the .NET Foundation to make the current version. Also cool.

看起来Cameron Taggart完成了最初的实现，然后.NET团队与Cameron和.NET Foundation一起制作了当前版本。 也很酷。

Let me see if this really works and how easy (or not) it is.

让我看看这是否真的有效，以及它是否容易实现。

I'm going to make a little library using the 5 year old Pseudointernationalizer from here. Fortunately the main function is pretty pure and drops into a .NET Standard library neatly.

我将从这里使用5岁的Pseudointernationalizer制作一个小图书馆。 幸运的是，主要功能非常纯净，可以轻松地放入.NET Standard库。

I'll put this on GitHub, so I will include "PublishRepositoryUrl" and "EmbedUntrackedSources" as well as including the PDBs. So far my CSPROJ looks like this:

我将其放在GitHub上，因此我将包括“ PublishRepositoryUrl”和“ EmbedUntrackedSources”以及PDB。 到目前为止，我的CSPROJ如下所示：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

Pretty straightforward so far. As I am using GitHub I added this reference, but if I was using GitLab or BitBucket, etc, I would use that specific provider per the docs.

到目前为止非常简单。 当我使用GitHub时，我添加了此引用，但是如果使用的是GitLab或BitBucket等，则应根据文档使用该特定提供程序。

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0-beta-63127-02" PrivateAssets="All"/>
</ItemGroup>

Now I'll pack up my project as a NuGet package.

现在，我将项目打包为NuGet包。

D:\github\SourceLinkTest\PsuedoizerCore [master ≡]> dotnet pack -c release
Microsoft (R) Build Engine version 15.8.166+gd4e8d81a88 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restoring packages for D:\github\SourceLinkTest\PsuedoizerCore\PsuedoizerCore.csproj...
  Generating MSBuild file D:\github\SourceLinkTest\PsuedoizerCore\obj\PsuedoizerCore.csproj.nuget.g.props.
  Restore completed in 96.7 ms for D:\github\SourceLinkTest\PsuedoizerCore\PsuedoizerCore.csproj.
  PsuedoizerCore -> D:\github\SourceLinkTest\PsuedoizerCore\bin\release\netstandard2.0\PsuedoizerCore.dll
  Successfully created package 'D:\github\SourceLinkTest\PsuedoizerCore\bin\release\PsuedoizerCore.1.0.0.nupkg'.

Let's look inside the .nupkg as they are just ZIP files. Ah, check out the generated *.nuspec file that's inside!

让我们看一下.nupkg，因为它们只是ZIP文件。 啊，检查里面生成的* .nuspec文件！

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <id>PsuedoizerCore</id>
    <version>1.0.0</version>
    <authors>PsuedoizerCore</authors>
    <owners>PsuedoizerCore</owners>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package Description</description>
    <repository type="git" url="https://github.com/shanselman/PsuedoizerCore.git" commit="35024ca864cf306251a102fbca154b483b58a771" />
    <dependencies>
      <group targetFramework=".NETStandard2.0" />
    </dependencies>
  </metadata>
</package>

See under repository it points back to the location AND commit hash for this binary! That means I can give it to you or a coworker and they'd be able to get to the source. But what's the consumption experience like? I'll go over and start a new Console app that CONSUMES my NuGet library package. To make totally sure that I don't accidentally pick up the source from my machine I'm going to delete the entire folder. This source code no longer exists on this machine.

请参阅存储库下面的内容，它指向该二进制文件的位置并提交哈希！ 这意味着我可以将其提供给您或同事，他们可以找到源头。 但是消费体验如何？ 我将结束并启动一个新的Console应用程序，该应用程序将占用我的NuGet库软件包。 为了完全确保我不会意外从计算机中获取源代码，我将删除整个文件夹。 此源代码在此计算机上不再存在。

I'm using a "local" NuGet Feed. In fact, it's just a folder. Check it out:

我正在使用“本地” NuGet Feed。 实际上，这只是一个文件夹。 看看这个：

D:\github\SourceLinkTest\AConsumerConsole> dotnet add package PsuedoizerCore -s "c:\users\scott\desktop\LocalNuGetFeed"
  Writing C:\Users\scott\AppData\Local\Temp\tmpBECA.tmp
info : Adding PackageReference for package 'PsuedoizerCore' into project 'D:\github\SourceLinkTest\AConsumerConsole\AConsumerConsole.csproj'.
log  : Restoring packages for D:\github\SourceLinkTest\AConsumerConsole\AConsumerConsole.csproj...
info :   GET https://api.nuget.org/v3-flatcontainer/psuedoizercore/index.json
info :   NotFound https://api.nuget.org/v3-flatcontainer/psuedoizercore/index.json 465ms
log  : Installing PsuedoizerCore 1.0.0.
info : Package 'PsuedoizerCore' is compatible with all the specified frameworks in project 'D:\github\SourceLinkTest\AConsumerConsole\AConsumerConsole.csproj'.
info : PackageReference for package 'PsuedoizerCore' version '1.0.0' added to file 'D:\github\SourceLinkTest\AConsumerConsole\AConsumerConsole.csproj'.

See how I used -s to point to an alternate source? I could also configure my NuGet feeds, be they local directories or internal servers with "dotnet new nugetconfig" and including my NuGet Servers in the order I want them searched.

看看我如何使用-s指向备用源吗？ 我还可以使用“ dotnet new nugetconfig”配置我的NuGet提要，无论它们是本地目录还是内部服务器，并按我希望它们搜索的顺序包括我的NuGet服务器。

Here is my little app:

这是我的小应用程序：

using System;
using Utils;

namespace AConsumerConsole
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine(Pseudoizer.ConvertToFakeInternationalized("Hello World!"));
        }
    } 
}

And the output is [Ħęľľő Ŵőřľđ! !!! !!!].

输出为[ĦęľľőŴőřľđ！ !!! !!!]。

But can I step into it? I don't have the source remember...I'm using SourceLink.

但是我可以介入吗？ 我没有来源记得...我正在使用SourceLink。

In Visual Studio 2017 I confirm that SourceLink is enabled. This is the Portable PDB version of SourceLink, not the "SourceLink 1.0" that was "Enable Source Server Support." That only worked on Windows..

在Visual Studio 2017中，我确认已启用SourceLink。 这是SourceLink的可移植PDB版本，而不是“启用源服务器支持”的“ SourceLink 1.0”。 那只适用于Windows。

You'll also want to turn off "Just My Code" since, well, this isn't your code.

您还需要关闭“ Just My Code”，因为这不是您的代码。

Now I'll start a Debug Session in my consumer app and hit F11 to Step Into the Library whose source I do not have!

现在，我将在用户应用程序中启动一个调试会话，然后按F11键进入没有源代码的库！

Fantastic. It's going to get the source for me! Without git cloning the repository it will seamlessly let me continue my debugging session.

太棒了它会为我找到来源！ 如果没有git克隆存储库，它将无缝地让我继续调试会话。

The temporary file ended up in C:\Users\scott\AppData\Local\SourceServer\4bbf4c0dc8560e42e656aa2150024c8e60b7f9b91b3823b7244d47931640a9b9 if you're interested. I'm able to just keep debugging as if I had the source...because I do! It came from the linked source.

如果您感兴趣，该临时文件将以C：\ Users \ scott \ AppData \ Local \ SourceServer \ 4bbf4c0dc8560e42e656aa2150024c8e60b7f9b91b3823b7244d47931640a9b9结尾。 我可以像调试源代码一样继续调试...因为我这样做了！ 它来自链接源。

Very cool. I'm going to keep digging into SourceLink and learning about it. It seems that if YOU have a library or published NuGet either inside your company OR out in the open source world that you absolutely should be using SourceLink.

很酷。 我将继续研究SourceLink并对其进行学习。 看来，如果您在公司内部或在开源环境中拥有图书馆或发布了NuGet，则绝对应该使用SourceLink。

You can even install the sourcelink global tool and test your .pdb files for greater insight.

您甚至可以安装sourcelink全局工具并测试.pdb文件以获得更深入的了解。

D:\github\SourceLinkTest\PsuedoizerCore>dotnet tool install --global sourcelink
D:\github\SourceLinkTest\PsuedoizerCore\bin\release\netstandard2.0>sourcelink print-urls PsuedoizerCore.pdb
43c83e7173f316e96db2d8345a3f963527269651 sha1 csharp D:\github\SourceLinkTest\PsuedoizerCore\Psuedoizer.cs
https://raw.githubusercontent.com/shanselman/PsuedoizerCore/02c09baa8bfdee3b6cdf4be89bd98c8157b0bc08/Psuedoizer.cs
bfafbaee93e85cd2e5e864bff949f60044313638 sha1 csharp C:\Users\scott\AppData\Local\Temp\.NETStandard,Version=v2.0.AssemblyAttributes.cs
embedded

Think about how much easier consumers of your library will have it when debugging their apps! Your package is no longer a black box. Go set this up on your projects today.

想一想，在调试他们的应用程序时，您的库的使用者将更容易获得它！ 您的包裹不再是黑匣子。 立即在您的项目上进行设置。

翻译自: https://www.hanselman.com/blog/exploring-net-cores-sourcelink-stepping-into-the-source-code-of-nuget-packages-you-dont-own