{"id":31145,"date":"2020-12-09T09:05:44","date_gmt":"2020-12-09T16:05:44","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=31145"},"modified":"2020-12-09T10:04:33","modified_gmt":"2020-12-09T17:04:33","slug":"producing-packages-with-source-link","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/producing-packages-with-source-link\/","title":{"rendered":"Producing Packages with Source Link"},"content":{"rendered":"

In our last post, we showed you how you can debug into the framework and dependencies<\/a> that was produced with Source Link. In this post, we’ll show you how to add Source Link to your projects. This is beneficial both for public and internal projects.<\/p>\n

How Source Link Works<\/h2>\n

At its most basic, Source Link generates a JSON file that maps raw source code locations to the source files in the build. This is most commonly an HTTPS URL to a file on GitHub, GitLab, Azure Repos, or Bitbucket. The JSON file gets embedded in the debug symbols, which the debugger uses to download the file on-demand. For non-public repos, this does not automatically grant anyone access to the source; the debugger would need to authenticate so existing permissions are maintained.<\/p>\n

Using Source Link<\/h2>\n

Source Link is distributed as a set of NuGet packages<\/a>, one per repository host. It is intended to be used as a private reference (it is used during the build, it does not require runtime consumers to have a dependency on it).<\/p>\n

You can enable Source Link experience in your own .NET project by setting a few properties and adding a PackageReference to a Source Link package:<\/p>\n

<Project Sdk=\"Microsoft.NET.Sdk\">\r\n <PropertyGroup>\r\n    <TargetFramework>net5.0<\/TargetFramework>\r\n\r\n    <!-- Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->\r\n    <PublishRepositoryUrl>true<\/PublishRepositoryUrl>\r\n\r\n    <!-- Embed source files that are not tracked by the source control manager in the PDB -->\r\n    <EmbedUntrackedSources>true<\/EmbedUntrackedSources>\r\n\r\n    <!-- Recommended: Embed symbols containing Source Link in the main file (exe\/dll) -->\r\n    <DebugType>embedded<\/DebugType>\r\n  <\/PropertyGroup>\r\n  <ItemGroup>\r\n    <!-- Add PackageReference specific for your source control provider (see below) -->\r\n  <\/ItemGroup>\r\n<\/Project>\r\n<\/code><\/pre>\n
Deterministic Builds<\/h3>\n
Deterministic builds ensure that the same binary is produced regardless of the machine building it, including paths to sources stored in the symbols. While deterministic builds are enabled by default in .NET SDK projects, there is an extra property, ContinuousIntegrationBuild<\/code>, to set on the build server to normalize stored file paths. These should not be enabled during local dev or the debugger won’t be able to find the local source files.<\/p>\n
Therefore, you should use your CI system’s variable to set them conditionally. For Azure Pipelines, it looks like this<\/p>\n
<PropertyGroup Condition=\"'$(TF_BUILD)' == 'true'\">\r\n  <ContinuousIntegrationBuild>true<\/ContinuousIntegrationBuild>\r\n<\/PropertyGroup>\r\n<\/code><\/pre>\n
For GitHub Actions, the variable is GITHUB_ACTIONS<\/code>, so the result would be:<\/p>\n
<PropertyGroup Condition=\"'$(GITHUB_ACTIONS)' == 'true'\">\r\n  <ContinuousIntegrationBuild>true<\/ContinuousIntegrationBuild>\r\n<\/PropertyGroup>\r\n<\/code><\/pre>\n
Don’t Repeat Yourself<\/h3>\n
If you have a solution that has multiple projects in it, you can extract the common properties into a Directory.Build.props<\/a> file at the solution directory. That way all projects have them added automatically.<\/p>\n
If you distribute the library via a package published to NuGet.org<\/a>, you should use embedded PDB’s so the debug information is always available with your library. Alternatively, you can build a symbol package<\/a> and publish it to NuGet.org<\/a> as well. This will make the symbols available on NuGet.org symbol server<\/a>, where the debugger can download it when needed.<\/p>\n
Source Control Providers<\/h2>\n
Source Link packages are currently available for the following source control providers.<\/p>\n
Source Link package is a development dependency, which means it is only used during build. It is therefore recommended to set PrivateAssets<\/code> to all<\/code> on the package reference. This prevents consuming projects of your NuGet package from attempting to install Source Link.<\/p><\/blockquote>\n
github.com and GitHub Enterprise<\/h3>\n
For projects hosted by GitHub<\/a> or GitHub Enterprise<\/a> reference Microsoft.SourceLink.GitHub<\/a> like so:<\/p>\n
<ItemGroup>\r\n  <PackageReference Include=\"Microsoft.SourceLink.GitHub\" Version=\"1.0.0\" PrivateAssets=\"All\"\/>\r\n<\/ItemGroup>\r\n<\/code><\/pre>\n
Azure Repos (former Visual Studio Team Services)<\/h3>\n
For projects hosted by Azure Repos<\/a> in git repositories reference Microsoft.SourceLink.AzureRepos.Git<\/a>:<\/p>\n
<ItemGroup>\r\n  <PackageReference Include=\"Microsoft.SourceLink.AzureRepos.Git\" Version=\"1.0.0\" PrivateAssets=\"All\"\/>\r\n<\/ItemGroup>\r\n<\/code><\/pre>\n
Azure DevOps Server (former Team Foundation Server)<\/h3>\n
For projects hosted by on-prem Azure DevOps Server<\/a> in git repositories reference\nMicrosoft.SourceLink.AzureDevOpsServer.Git<\/a> and add host configuration like so:<\/p>\n
<ItemGroup>\r\n  <PackageReference Include=\"Microsoft.SourceLink.AzureDevOpsServer.Git\" Version=\"1.0.0\" PrivateAssets=\"All\"\/>\r\n<\/ItemGroup>\r\n<\/code><\/pre>\n
If your server is configured with non-empty IIS Virtual Directory<\/a>, specify this directory in SourceLinkAzureDevOpsServerGitHost<\/code> item like so:<\/p>\n
<ItemGroup>\r\n  <SourceLinkAzureDevOpsServerGitHost Include=\"server-name\" VirtualDirectory=\"tfs\"\/>\r\n<\/ItemGroup>\r\n<\/code><\/pre>\n
The Include<\/code> attribute specifies the domain and optionally the port of the server (e.g. server-name<\/code> or server-name:8080<\/code>).<\/p>\n
GitLab<\/h3>\n
For projects hosted by GitLab<\/a> reference Microsoft.SourceLink.GitLab<\/a> package:<\/p>\n
<ItemGroup>\r\n  <PackageReference Include=\"Microsoft.SourceLink.GitLab\" Version=\"1.0.0\" PrivateAssets=\"All\"\/>\r\n<\/ItemGroup>\r\n<\/code><\/pre>\n
Bitbucket<\/h3>\n
For projects in git repositories hosted on Bitbucket.org<\/a> or hosted on an on-prem Bitbucket server reference Microsoft.SourceLink.Bitbucket.Git<\/a> package:<\/p>\n
<ItemGroup>\r\n  <PackageReference Include=\"Microsoft.SourceLink.Bitbucket.Git\" Version=\"1.0.0\" PrivateAssets=\"All\"\/>\r\n<\/ItemGroup>\r\n<\/code><\/pre>\n
If your project is hosted by Bitbucket Server or Bitbucket Data Center older than version 4.7 you must specify SourceLinkBitbucketGitHost<\/code> item group in addition to the package reference:<\/p>\n
<ItemGroup>\r\n  <SourceLinkBitbucketGitHost Include=\"bitbucket.yourdomain.com\" Version=\"4.5\"\/>\r\n<\/ItemGroup>\r\n<\/code><\/pre>\n
The item group SourceLinkBitbucketGitHost<\/code> specifies the domain of the Bitbucket host and the version of Bitbucket.\nThe version is important since URL format for accessing files changes with version 4.7. By default Source Link assumes new format (version 4.7+).<\/p>\n
gitweb (pre-release)<\/h3>\n
For projects hosted on-prem via gitweb<\/a> reference Microsoft.SourceLink.GitWeb<\/a> package:<\/p>\n
<ItemGroup>\r\n  <PackageReference Include=\"Microsoft.SourceLink.GitWeb\" Version=\"1.1.0-beta-20204-02\" PrivateAssets=\"All\"\/>\r\n<\/ItemGroup>\r\n<\/code><\/pre>\n
Summary<\/h2>\n
Source Link is easy to add to your projects and we highly recommend that all projects configure it by default.<\/p>\n","protected":false},"excerpt":{"rendered":"
Learn how to add Source Link to your packages, to make your users more productive while debugging.<\/p>\n","protected":false},"author":42867,"featured_media":31148,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685,196,7196],"tags":[4,9,322,7202],"class_list":["post-31145","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet","category-dotnet-core","category-debugging","tag-net","tag-net-core","tag-debugging","tag-source-link"],"acf":[],"blog_post_summary":"
Learn how to add Source Link to your packages, to make your users more productive while debugging.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/31145","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/42867"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=31145"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/31145\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/31148"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=31145"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=31145"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=31145"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}