You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+38-32Lines changed: 38 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,53 +2,55 @@
2
2
3
3
Source 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.
4
4
5
-
Source Link is a [set of packages](https://www.nuget.org/packages?q=Microsoft.SourceLink) and a [specification](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md#source-link-file-specification)for describing source control metadata that can be embedded in symbols, binaries and packages.
5
+
Source 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.
6
6
7
7
Visual 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.
8
8
9
9
The [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.
10
10
11
-
> If you arrived here from the original Source Link documentation - you do not need to use `SourceLink.Create.CommandLine`. You only need to install the packages listed below.
11
+
> If you arrived here from the original Source Link documentation - you do not need to use `SourceLink.Create.CommandLine`.
12
12
13
-
## <aname="using-sourcelink">Using Source Link in .NET projects
13
+
## Using Source Link in .NET projects
14
14
15
-
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:
15
+
Starting with .NET 8, Source Link for the following source control providers is included in the .NET SDK and enabled by default:
16
+
-[GitHub](http://github.com) or [GitHub Enterprise](https://enterprise.github.com/home)
17
+
-[Azure Repos](https://azure.microsoft.com/en-us/services/devops/repos) git repositories (formerly known as Visual Studio Team Services)
18
+
-[GitLab](https://gitlab.com) 12.0+ (for older versions see [GitLab settings](#gitlab))
19
+
-[Bitbucket](https://bitbucket.org/) 4.7+ (for older versions see [Bitbucket settings](#bitbucket))
20
+
21
+
If 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.
22
+
23
+
**Otherwise**, you can enable Source Link experience in your project by setting a few properties and adding a PackageReference to a Source Link package specific to the provider:
16
24
17
25
```xml
18
-
<ProjectSdk="Microsoft.NET.Sdk">
26
+
<Project>
19
27
<PropertyGroup>
20
-
<TargetFramework>netcoreapp2.1</TargetFramework>
21
-
22
28
<!-- Optional: Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
23
29
<PublishRepositoryUrl>true</PublishRepositoryUrl>
24
30
25
31
<!-- Optional: Embed source files that are not tracked by the source control manager in the PDB -->
<!-- Optional: Build symbol package (.snupkg) to distribute the PDB containing Source Link -->
29
-
<IncludeSymbols>true</IncludeSymbols>
30
-
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
31
33
</PropertyGroup>
32
34
<ItemGroup>
33
35
<!-- Add PackageReference specific for your source control provider (see below) -->
34
36
</ItemGroup>
35
37
</Project>
36
38
```
37
39
38
-
If 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. Alternatively, you can [include the symbols in the main package](#alternative-pdb-distribution). However, doing so is not recommended as it increases the size of the package and thus restore time for projects that consume your package.
39
-
40
-
Source Link packages are currently available for the following source control providers.
40
+
Source Link packages are currently available for the source control providers listed below.
41
41
42
42
> Source Link package 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 of your nuget package from attempting to install Source Link.
43
43
44
+
> Referencing any Source Link package in a .NET SDK 8+ project suppresses Source Link that is included in the SDK.
45
+
44
46
### github.com and GitHub Enterprise
45
47
46
48
For projects hosted by [GitHub](http://github.com) or [GitHub Enterprise](https://enterprise.github.com/home) reference
47
49
[Microsoft.SourceLink.GitHub](https://www.nuget.org/packages/Microsoft.SourceLink.GitHub) like so:
### Multiple providers, repositories with submodules
160
162
161
-
If your repository contains submodules hosted by other git providers reference packages of all these providers. 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.
163
+
If 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.
162
164
163
165
## Using Source Link in C++ projects
164
166
@@ -168,9 +170,9 @@ To add Source Link support to your native project add package references corresp
@@ -202,29 +204,33 @@ The VC++ linker supports `/SOURCELINK` [switch](https://docs.microsoft.com/en-us
202
204
- Issue when building WPF projects with `/p:ContinuousIntegrationBuild=true`: https://github.com/dotnet/sourcelink/issues/91
203
205
- 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
204
206
205
-
## Alternative PDB distribution
207
+
## PDB distributions
208
+
209
+
If 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.
206
210
207
-
Prior availability of [NuGet.org symbol server](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg#nugetorg-symbol-server) the recommendation used to be to include the PDB in the main NuGet package by setting the following property in your project:
211
+
Alternatively, Portable PDBs can be included in the main NuGet package by setting the following property in your project:
Including PDBs in the .nupkg is generally no longer recommended as it increases the size of the package and thus restore time for projects that consume your package, regardless of whether the user needs to debug through the source code of your library or not. That said, .snupkg symbol packages have some limitations:
219
+
Keep in mind that including PDBs 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 through the source code of your library or not.
220
+
221
+
.snupkg symbol packages have following limitations:
216
222
217
-
- They do not currently support Windows PDBs (generated by VC++, or for managed projects that set build property `DebugType` to `full`)
223
+
- They do not support Windows PDBs (generated by VC++, or for managed projects that set build property `DebugType` to `full`)
218
224
- They require the library to be built by newer C#/VB compiler (Visual Studio 2017 Update 9).
219
225
- The consumer of the package also needs Visual Studio 2017 Update 9 debugger.
220
226
- Not supported by [Azure DevOps Artifacts](https://azure.microsoft.com/en-us/services/devops/artifacts) service.
221
227
222
-
Consider including PDBs in the main package only if it is not possible to use .snupkg for the above reasons.
228
+
Consider including PDBs in the main package if it is not possible to use .snupkg for the above reasons.
223
229
For managed projects, consider switching to Portable PDBs by setting `DebugType` property to `portable`. This is the default for .NET SDK projects, but not classic .NET projects.
224
230
225
231
## Builds
226
232
227
-
Pre-release builds are available from Azure DevOps public feed: `https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json` ([browse](https://dev.azure.com/dnceng/public/_packaging?_a=feed&feed=dotnet-tools)).
233
+
Pre-release builds are available from Azure DevOps public feed: `https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet8/nuget/v3/index.json` ([browse](https://dev.azure.com/dnceng/public/_packaging?_a=feed&feed=dotnet8)).
0 commit comments