{"id":13431965,"url":"https://github.com/dotnet/sourcelink","last_synced_at":"2025-05-11T05:46:22.654Z","repository":{"id":38628557,"uuid":"130140573","full_name":"dotnet/sourcelink","owner":"dotnet","description":"Source Link enables a great source debugging experience for your users, by adding source control metadata to your built assets","archived":false,"fork":false,"pushed_at":"2025-05-11T02:32:37.000Z","size":3081,"stargazers_count":1307,"open_issues_count":132,"forks_count":131,"subscribers_count":232,"default_branch":"main","last_synced_at":"2025-05-11T05:46:16.885Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotnet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-04-19T01:11:45.000Z","updated_at":"2025-05-11T02:18:31.000Z","dependencies_parsed_at":"2022-07-09T18:01:02.884Z","dependency_job_id":"e88d9327-723b-4503-b6e2-3c87be2bd4ee","html_url":"https://github.com/dotnet/sourcelink","commit_stats":{"total_commits":992,"total_committers":53,"mean_commits":18.71698113207547,"dds":0.4092741935483871,"last_synced_commit":"9700a2bfe76f993dbeb34439d4fe320c31182b2a"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet%2Fsourcelink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet%2Fsourcelink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet%2Fsourcelink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet%2Fsourcelink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotnet","download_url":"https://codeload.github.com/dotnet/sourcelink/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253523719,"owners_count":21921818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T02:01:07.402Z","updated_at":"2025-05-11T05:46:22.636Z","avatar_url":"https://github.com/dotnet.png","language":"C#","funding_links":[],"categories":["Frameworks, Libraries and Tools","C\\#","others","C# #","C#","框架, 库和工具"],"sub_categories":["Tools","工具"],"readme":"# Source Link\n\nSource Link is a language- and source-control agnostic system for providing first-class source debugging experiences for binaries. The goal of the project is to enable anyone building [NuGet libraries to provide source debugging](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/debugging-with-symbols-and-sources.md) for their users with almost no effort. Microsoft libraries, such as .NET Core and Roslyn have enabled Source Link. Source Link is supported by Microsoft.\n\nSource Link [specification](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md#source-link-file-specification) describes source control metadata that can be embedded in symbols, binaries and packages to link them to their original sources.\n\nVisual Studio 15.3+ supports reading Source Link information from symbols while debugging. It downloads and displays the appropriate commit-specific source for users, such as from [raw.githubusercontent](https://raw.githubusercontent.com/dotnet/roslyn/681cbc414542ffb9fb13ded613d26a88ea73a44b/src/VisualStudio/Core/Def/Implementation/ProjectSystem/AbstractProject.cs), 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.\n\nThe [original Source Link implementation](https://github.com/ctaggart/SourceLink) was provided by [@ctaggart](https://github.com/ctaggart). Thanks! The .NET Team and Cameron worked together to make this implementation available in the .NET Foundation.\n\n\u003e [!TIP]\n\u003e If you arrived here from the original Source Link documentation - you do not need to use `SourceLink.Create.CommandLine`.\n\nProviding a good debugging experience for your project involves three main steps:\n\n1. Including source control information in PDBs\n2. Including source control information in the NuGet package manifest\n3. Distributing PDBs\n\nSee below for examples and best practices regarding each step.\n\n## Using Source Link in .NET projects\n\nStarting with .NET 8, Source Link for the following source control providers is included in the .NET SDK and enabled by default:\n\n- [GitHub](http://github.com) or [GitHub Enterprise](https://enterprise.github.com/home) \n- [Azure Repos](https://azure.microsoft.com/en-us/services/devops/repos) git repositories (formerly known as Visual Studio Team Services)\n- [GitLab](https://gitlab.com) 12.0+ (for older versions see [GitLab settings](#gitlab))\n- [Bitbucket](https://bitbucket.org/) 4.7+ (for older versions see [Bitbucket settings](#bitbucket))\n\nIf your project uses .NET SDK 8+ and is hosted by the above providers it does not need to reference any Source Link packages or set any build properties to include source control information in the PDB.\n\nIf your project does not yet use .NET SDK 8+, or is not hosted by one of the these providers, you must add a PackageReference to a Source Link package specific to the provider:\n\n```xml\n\u003cProject\u003e\n  \u003cItemGroup\u003e\n    \u003c!-- Add PackageReference specific for your source control provider (see below) --\u003e\n  \u003c/ItemGroup\u003e\n\n  \u003cPropertyGroup\u003e\n    \u003c!-- Optional (set by default in .NET SDK 8+): Embed source files that are not tracked by the source control manager in the PDB --\u003e\n    \u003cEmbedUntrackedSources\u003etrue\u003c/EmbedUntrackedSources\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\n\u003e [!TIP]\n\u003e Source Link is a development dependency, which means it is only used during build. It is therefore recommended to set `PrivateAssets` to `all` on the package reference. This prevents consuming projects from attempting to install Source Link.\n\n\u003e [!NOTE]\n\u003e Referencing any Source Link package in a .NET SDK 8+ project overrides the Source Link version that is included in the SDK.\n\n\nIf your project produces a NuGet package, set `PublishRepositoryUrl` to include source control information in the package manifest:\n\n```xml\n\u003cProject\u003e\n \u003cPropertyGroup\u003e\n    \u003c!-- Optional: Publish the repository URL in the built .nupkg (in the NuSpec \u003crepository\u003e element) --\u003e\n    \u003cPublishRepositoryUrl\u003etrue\u003c/PublishRepositoryUrl\u003e\n  \u003c/PropertyGroup\u003e\n\u003c/Project\u003e\n```\n\nSource Link packages are currently available for these source control providers:\n\n### github.com and GitHub Enterprise\n\nFor projects hosted by [GitHub](http://github.com) or [GitHub Enterprise](https://enterprise.github.com/home) reference \n[Microsoft.SourceLink.GitHub](https://www.nuget.org/packages/Microsoft.SourceLink.GitHub) like so:\n\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"Microsoft.SourceLink.GitHub\" Version=\"8.0.0\" PrivateAssets=\"All\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\n### Azure Repos (former Visual Studio Team Services)\n\nFor projects hosted by [Azure Repos](https://azure.microsoft.com/en-us/services/devops/repos) in git repositories reference [Microsoft.SourceLink.AzureRepos.Git](https://www.nuget.org/packages/Microsoft.SourceLink.AzureRepos.Git): \n\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"Microsoft.SourceLink.AzureRepos.Git\" Version=\"8.0.0\" PrivateAssets=\"All\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\n### Azure DevOps Server (former Team Foundation Server)\n\nFor projects hosted by on-prem [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in git repositories reference\n[Microsoft.SourceLink.AzureDevOpsServer.Git](https://www.nuget.org/packages/Microsoft.SourceLink.AzureDevOpsServer.Git) and add host configuration like so:\n\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"Microsoft.SourceLink.AzureDevOpsServer.Git\" Version=\"8.0.0\" PrivateAssets=\"All\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\nYou also need to provide the hostname of your DevOps server:\n \n```xml\n\u003cItemGroup\u003e\n  \u003cSourceLinkAzureDevOpsServerGitHost Include=\"server-name\"/\u003e\n\u003c/ItemGroup\u003e\n```\n \nThe `Include` attribute specifies the domain and optionally the port of the server (e.g. `server-name` or `server-name:8080`).\n\nIf your server is configured with a non-empty IIS [virtual directory](docs/TfsVirtualDirectory/README.md), specify this directory like so:\n\n```xml\n\u003cItemGroup\u003e\n  \u003cSourceLinkAzureDevOpsServerGitHost Include=\"server-name\" VirtualDirectory=\"tfs\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\n### GitLab\n\nFor projects hosted by [GitLab](https://gitlab.com) reference [Microsoft.SourceLink.GitLab](https://www.nuget.org/packages/Microsoft.SourceLink.GitLab) package: \n\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"Microsoft.SourceLink.GitLab\" Version=\"8.0.0\" PrivateAssets=\"All\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\nStarting with version 8.0.0, Microsoft.SourceLink.GitLab assumes GitLab version 12.0+ by default.\nIf your project is hosted by GitLab older than version 12.0 you must specify `SourceLinkGitLabHost` item group in addition to the package reference:\n\n```xml\n\u003cItemGroup\u003e\n  \u003cSourceLinkGitLabHost Include=\"gitlab.yourdomain.com\" Version=\"11.0\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\nThe item group `SourceLinkGitLabHost` specifies the domain of the GitLab host and the version of GitLab.\nThe version is important since URL format for accessing files changes with version 12.0. By default Source Link assumes new format (version 12.0+).\n\nYou might also consider using environment variable [`CI_SERVER_VERSION`](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) (`Version=\"$(CI_SERVER_VERSION)\"`) if available in your build environment.\n \n### Bitbucket\n\nFor projects in git repositories hosted on [Bitbucket.org](https://bitbucket.org) or hosted on an on-prem Bitbucket server reference [Microsoft.SourceLink.Bitbucket.Git](https://www.nuget.org/packages/Microsoft.SourceLink.Bitbucket.Git) package:\n\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"Microsoft.SourceLink.Bitbucket.Git\" Version=\"8.0.0\" PrivateAssets=\"All\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\nIf your project is hosted by Bitbucket Server or Bitbucket Data Center older than version 4.7 you must specify `SourceLinkBitbucketGitHost` item group in addition to the package reference:\n\n```xml\n\u003cItemGroup\u003e\n  \u003cSourceLinkBitbucketGitHost Include=\"bitbucket.yourdomain.com\" Version=\"4.5\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\nThe item group `SourceLinkBitbucketGitHost` 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+).\n\n### gitweb\n\nFor projects hosted on-prem via [gitweb](https://git-scm.com/docs/gitweb) reference [Microsoft.SourceLink.GitWeb](https://www.nuget.org/packages/Microsoft.SourceLink.GitWeb) package: \n\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"Microsoft.SourceLink.GitWeb\" Version=\"8.0.0\" PrivateAssets=\"All\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\n### gitea\n\nFor projects hosted on-prem via [gitea](https://gitea.io) reference [Microsoft.SourceLink.Gitea](https://www.nuget.org/packages/Microsoft.SourceLink.Gitea) package: \n\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"Microsoft.SourceLink.Gitea\" Version=\"8.0.0\" PrivateAssets=\"All\"/\u003e\n\u003c/ItemGroup\u003e\n```\n\n### Multiple providers, repositories with submodules\n\nIf your repository contains submodules hosted by multiple git providers reference packages of all these providers, unless the project uses .NET SDK 8+ and submodules only use providers for which Source Link support is included. For example, projects in a repository hosted by Azure Repos that links a GitHub repository via a submodule should reference both [Microsoft.SourceLink.AzureRepos.Git](https://www.nuget.org/packages/Microsoft.SourceLink.AzureRepos.Git) and [Microsoft.SourceLink.GitHub](https://www.nuget.org/packages/Microsoft.SourceLink.GitHub) packages. [Additional configuration](https://github.com/dotnet/sourcelink/blob/main/docs/README.md#configuring-projects-with-multiple-sourcelink-providers) might be needed if multiple Source Link packages are used in the project.\n\n## Using Source Link in C++ projects\n\nSource Link package supports integration with VC++ projects (vcxproj) and VC++ linker.\n\nTo add Source Link support to your native project add package references corresponding to your source control provider to `packages.config` directly or using [NuGet Package Manager UI](https://docs.microsoft.com/en-us/nuget/tools/package-manager-ui) in Visual Studio. For example, the `packages.config` file for a project hosted on GitHub would include the following lines:  \n\n```xml\n\u003cpackages\u003e\n  \u003cpackage id=\"Microsoft.Build.Tasks.Git\" version=\"8.0.0\" targetFramework=\"native\" developmentDependency=\"true\" /\u003e\n  \u003cpackage id=\"Microsoft.SourceLink.Common\" version=\"8.0.0\" targetFramework=\"native\" developmentDependency=\"true\" /\u003e\n  \u003cpackage id=\"Microsoft.SourceLink.GitHub\" version=\"8.0.0\" targetFramework=\"native\" developmentDependency=\"true\" /\u003e\n\u003c/packages\u003e\n```\n\nOnce the packages are restored and the project built the Source Link information is [passed to the linker](https://docs.microsoft.com/en-us/cpp/build/reference/sourcelink) and embedded into the generated PDB.\n\nThe only feature currently supported is mapping of source files to the source repository that is used by the debugger to find source files when stepping into the code. Source embedding and embedding commit SHA and repository URL information in the native binary are not supported for native projects.\n\n## Prerequisites for .NET projects\n\nSource Link supports classic .NET Framework projects as well as .NET SDK projects, that is projects that import `Microsoft.NET.Sdk` (e.g. like so: `\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e`). The project may target .NET, .NET Framework or .NET Standard. All PDB formats are supported: Portable, Embedded and Windows PDBs.\n\n[.NET 8 SDK](https://www.microsoft.com/net/download/dotnet/8.0) or newer is required for .NET SDK projects. If building via desktop `msbuild` you'll need version 16.0 or higher.\n\nThe following features are not available in projects that do not import `Microsoft.NET.Sdk`:\n- Automatic inclusion of commit SHA in `AssemblyInformationalVersionAttribute`.\n- Automatic inclusion of commit SHA and repository URL in NuSpec.\n\nThese features can be added via custom msbuild targets.\n\n## Prerequisites for C++ projects\n\nDebugging native binary with Source Link information embedded in the PDB is supported since Visual Studio 2017 Update 9.\n\nThe VC++ linker supports `/SOURCELINK` [switch](https://docs.microsoft.com/en-us/cpp/build/reference/sourcelink) since Visual Studio 2017 Update 8, however the PDBs produced by this version are not compatible with case-sensitive source control systems such as git. This issue is fixed in [Visual Studio 2019](https://visualstudio.microsoft.com/vs/preview/).\n\n## Known issues\n\n- Issue when building WPF projects with embedding sources on and `BaseIntermediateOutputPath` not a subdirectory of the project directory: https://github.com/dotnet/sourcelink/issues/492\n\n## PDB distributions\n\nThere are three main ways to distribute PDBs for managed code: via a dedicated .snupkg, including them in the main package, and embedding them directly into the assembly. Each has advantages and drawbacks, depending on your use case.\n\n|                                         | snupkg                      | Include in main package | Embed in assembly |\n|-----------------------------------------|-----------------------------|-------------------------|-------------------|\n| No user opt-in required to load symbols | ✅                          | ❌                      | ✅                |\n| No increase in size of main package     | ✅                          | ❌                      | ❌                |\n| No increase in size of assemblies       | ✅                          | ✅                      | ❌                |\n| Supported by all package feeds          | ❌ (Supported on NuGet.org) | ✅                      | ✅                |\n\n### .snupkg symbol packages\n\nIf you distribute the library via a package published to [NuGet.org](http://nuget.org), it is recommended to build a [symbol package](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) and publish it to [NuGet.org](http://nuget.org) as well. This will make the symbols available on [NuGet.org symbol server](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg#nugetorg-symbol-server), where the debugger can download it from when needed.\n\n.snupkg symbol packages have following limitations:\n\n- They do not support Windows PDBs (generated by VC++, or for managed projects that set build property `DebugType` to `full`)\n- They require the library to be built by newer C#/VB compiler (Visual Studio 2017 Update 9).\n- The consumer of the package also needs Visual Studio 2017 Update 9 or newer.\n- Not supported by [Azure DevOps Artifacts](https://azure.microsoft.com/en-us/services/devops/artifacts) service.\n\nIf a .snupkg does not work for your scenario, consider including debug information in the main package via one of the alternatives.\n\n### Include in main package\n\nYou can include PDB files in the main NuGet package by setting the following property in your project:\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003cAllowedOutputExtensionsInPackageBuildOutputFolder\u003e$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb\u003c/AllowedOutputExtensionsInPackageBuildOutputFolder\u003e\n\u003c/PropertyGroup\u003e\n```\n\n\u003e [!IMPORTANT]\n\u003e Keep in mind that including debug information in the .nupkg increases the size of the package and thus restore time for projects that consume your package, regardless of whether the user needs to debug the source code of your library or not.\n\n\u003e [!IMPORTANT]\n\u003e When including PDB files in the main package, projects that consume the package must _also_ opt-in to copying the symbols into their own output directory. Starting in .NET 7 this can be controlled via the [`CopyDebugSymbolFilesFromPackages`](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#copydebugsymbolfilesfrompackages) property.\n\n\u003e [!TIP]\n\u003e Classic .NET projects should also consider changing the `DebugType` property to `portable` (or `embedded`) to match .NET SDK projects.\n\n### Embed in assembly\n\nYou can embed Portable PDB debug information directly in the assembly by setting the following property in your project:\n\n```xml\n\u003cPropertyGroup\u003e\n  \u003cDebugType\u003eembedded\u003c/DebugType\u003e\n\u003c/PropertyGroup\u003e\n```\n\n\u003e [!IMPORTANT]\n\u003e Keep in mind that embedding debug information in the assembly increases binary size. Larger binaries increase application size, NuGet restore time, assembly load time (if assemblies are very large), regardless of whether the user needs to debug the source code of your library or not.\n\n## Builds\n\nPre-release builds are available from Azure DevOps public feed: `https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet9/nuget/v3/index.json` ([browse](https://dev.azure.com/dnceng/public/_packaging?_a=feed\u0026feed=dotnet9)).\n\n[![Build Status](https://dnceng.visualstudio.com/public/_apis/build/status/SourceLink%20PR?branchName=main)](https://dnceng.visualstudio.com/public/_build/latest?definitionId=297?branchName=main)\n\n## Experience in Visual Studio\n\nThe following screenshot demonstrates debugging a NuGet package referenced by an application, with source automatically downloaded from GitHub and used by Visual Studio.\n\n![sourcelink-example](https://user-images.githubusercontent.com/2608468/39667937-10d7dabe-5076-11e8-815e-935724b3a783.PNG)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotnet%2Fsourcelink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotnet%2Fsourcelink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotnet%2Fsourcelink/lists"}