Search
  • en
  • es
  • en
    Search
    Open menu Open menu

    How to configure Source Link in .NET projects and how to use into the Visual Studio

    As a maintainer of open-source projects at Xabaril, I think it is important to help developers debug the source code of the libraries they use. It makes troubleshooting easier and helps them understand how those libraries work. That is why we decided to enable Source Link in our projects.

    Before we begin, I would like to thank Unai Zorrilla for showing me how Source Link works and helping me configure it in Balea.

    Example environment
    This guide uses .NET Core 3.1 and Visual Studio 2019.

    Source Link lets developers debug the source code of NuGet packages. Tools such as Visual Studio can use it to step into that code as if it were another local project, making it easier to troubleshoot problems when working with open-source libraries.

    Centralize dependency versions

    The dependencies.props file lets you define NuGet package versions in one place. This avoids version inconsistencies across a solution, while each project declares the dependencies it needs.

    dependencies.props
    <PropertyGroup Label="Package Dependencies">
    <AspNetCoreVersion>3.1.3</AspNetCoreVersion>
    <EntityFrameworkVersion>3.1.3</EntityFrameworkVersion>
    </PropertyGroup>

    In your csproj file, declare the dependencies you want to use:

    Project .csproj
    <ItemGroup>
        <PackageReference Include="Microsoft.Extensions.Http.Polly" Version="$(AspNetCoreVersion)" />
      </ItemGroup>

    If the ASP.NET Core team releases a new version, you do not need to update every project individually. Update the version in dependencies.props, and the projects that reference it will use that version.

    Share solution metadata

    Directory.Build.props is another useful file: it lets you share common metadata across the solution.

    Directory.Build.props
    <Project>
      <Import Project="build/dependencies.props" />
      <PropertyGroup Label="Package information">
        <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
        <PackageProjectUrl>http://github.com/xabaril/Balea</PackageProjectUrl>
        <RepositoryUrl>https://github.com/xabaril/Balea</RepositoryUrl>
        <Authors>Xabaril Contributors</Authors>
        <Company>Xabaril</Company>
      </PropertyGroup>
    </Project>

    The first line imports dependencies.props. The remaining properties define metadata shared by all projects, including the license and project URL.

    Enable Source Link

    To enable Source Link in your project, add these properties to Directory.Build.props:

    Directory.Build.props
    <!-- Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    
    <!-- Embed source files that are not tracked by the source control manager in the PDB -->
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    
    <!-- Build symbol package (.snupkg) to distribute the PDB containing Source Link -->
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>

    For projects hosted on GitHub, reference the Source Link package:

    Directory.Build.props
    <ItemGroup>
      <SourceRoot Include="$(MSBuildThisFileDirectory)/"/>
      <PackageReference Include="Microsoft.SourceLink.GitHub" Version="$(MicrosoftSourceLinkGithub)">
        <PrivateAssets>all</PrivateAssets>
        <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
      </PackageReference>
    </ItemGroup>

    Enable deterministic builds

    Next, enable deterministic builds. In this repository, Claire Novotny explains how they work and why they matter.

    Deterministic builds make it possible to verify which source produced a binary and trace it back to that source.

    Add the following to Directory.Build.props if you use GitHub Actions:

    Directory.Build.props
    <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
        <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
    </PropertyGroup>

    Apply the workaround for SDKs earlier than 3.1.300

    There is a known issue with the EmbedUntrackedSources attribute in SDKs earlier than 3.1.300. The original article used SDK 3.1.201.

    For that environment, add a Directory.Build.targets file at solution level with the following content:

    Directory.Build.targets
    <Project>
    <PropertyGroup>
        <TargetFrameworkMonikerAssemblyAttributesPath>$([System.IO.Path]::Combine('$(IntermediateOutputPath)','$(TargetFrameworkMoniker).AssemblyAttributes$(DefaultLanguageSourceExtension)'))</TargetFrameworkMonikerAssemblyAttributesPath>
      </PropertyGroup>
      <ItemGroup>
        <!-- https://github.com/dotnet/sourcelink/issues/572 -->
        <EmbeddedFiles Include="$(GeneratedAssemblyInfoFile)"/>
      </ItemGroup>
    </Project>

    Check the NuGet package

    Test the package locally

    To test your packages locally before publishing them to a NuGet feed, temporarily remove the MSBuild condition for GitHub Actions:

    Directory.Build.props — local test
    <PropertyGroup>
        <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
    </PropertyGroup>

    Run the following command to pack your project:

    Terminal
    dotnet pack <yoor_project>.csproj -c Release -o .\artifacts --include-symbols
    The NuGet package generated by dotnet pack.
    The NuGet package generated by dotnet pack.

    Open NuGet Package Explorer and select Open a local package.

    Open a local package in NuGet Package Explorer.
    Open a local package in NuGet Package Explorer.

    Find the NuGet package you just generated.

    Select the locally generated NuGet package.
    Select the locally generated NuGet package.

    You should see that Source Link and the deterministic build are valid.

    Verify Source Link and the deterministic build.
    Verify Source Link and the deterministic build.

    Validate the published package

    Before pushing your changes, restore the GitHub Actions condition you removed for local testing. You will need a GitHub Action to publish your packages to the NuGet feed.

    Once the package is published, open NuGet Package Explorer again and select Open a package from online feed.

    Open a package from a NuGet feed.
    Open a package from a NuGet feed.

    Search for your NuGet package.

    Search for the package published on NuGet.
    Search for the package published on NuGet.

    If you followed the steps correctly, the package should be valid and reflect the latest commit in your repository.

    Check the published package and its associated source code.
    Check the published package and its associated source code.

    Configure Visual Studio 2019 for Source Link

    Enable the NuGet symbol server

    The NuGet symbol server is disabled by default. Visual Studio 2019 needs to download those symbols to work with Source Link. To enable it, go to Tools → Options → Debugging → Symbols.

    Enable the NuGet symbol server in Visual Studio 2019.
    Enable the NuGet symbol server in Visual Studio 2019.

    Disable Just My Code

    Go to Tools → Options → Debugging → General and clear Enable Just My Code.

    Configure Enable Just My Code in the debugging options.
    Configure Enable Just My Code in the debugging options.

    Review the Source Link options

    Source Link is enabled by default in Visual Studio 2019, but Source Server support is not.

    Source Link and Source Server options in Visual Studio 2019.
    Source Link and Source Server options in Visual Studio 2019.

    The Fallback to Git Credential Manager option lets tools that use Git Credential Manager work with Source Link in private repositories.

    Debug library source code

    For this example, I created a simple Web API application and added the Balea packages.

    The example Web API application using the Balea packages.
    The example Web API application using the Balea packages.

    Run the web application and press F11 to step into the library code.

    Step into the library code while debugging.
    Step into the library code while debugging.

    The first time you do this, a dialog will explain that Source Link is about to download source code from the Internet, if it has not already been downloaded.

    Confirm the source code download through Source Link.
    Confirm the source code download through Source Link.

    Once Source Link has downloaded the source code, you can debug it in Visual Studio.

    Debug the library source code downloaded by Source Link.
    Debug the library source code downloaded by Source Link.

    This guide shows how to configure Source Link in .NET projects and use it in Visual Studio. For a complete example, see the Balea repository.

    Original reference article: Using Source Link in .NET projects and how to configure Visual Studio to use it.