For a NuGet library built with the .NET 10 SDK, what do Source Link, IncludeSymbols and SymbolPackageFormat=snupkg each contribute to debugging the package?
answer
- PDB maps code to a commit URL
- built into the SDK since .NET 8
- SymbolPackageFormat defaults to symbols.nupkg
- snupkg pushed beside the nupkg
- DebugType embedded as the alternative
basics
~20 sSource Link writes repository and commit URLs into the PDB so a debugger can fetch the exact source. IncludeSymbols makes pack produce a second, symbols package, and SymbolPackageFormat=snupkg makes it the portable-PDB .snupkg that nuget.org's symbol server accepts; the default is the legacy .symbols.nupkg.
solid answer
~50 sDebugging into a package needs two things: **symbols** (the PDB) and **source**. **Source Link** puts source-control information in the PDB, so a debugger can download each file at the exact commit; since the .NET 8 SDK it is built in for GitHub, Azure Repos, GitLab and Bitbucket, with `EmbedUntrackedSources` on by default, and `PublishRepositoryUrl=true` also writes the repository into the nuspec. `IncludeSymbols=true` (`dotnet pack --include-symbols`) creates a second package next to the `.nupkg`; its format is `SymbolPackageFormat`, which **defaults to `symbols.nupkg`**, the legacy format. Set it to `snupkg` for a portable-PDB symbol package, the only format nuget.org's symbol server accepts. `dotnet nuget push` of the `.nupkg` also pushes a `.snupkg` found beside it. Where the feed has no symbol server, `DebugType` `embedded` puts the PDB inside the DLL instead. On CI, set `ContinuousIntegrationBuild=true` for deterministic source paths.
code
xml · 8 lines<PropertyGroup>
<IncludeSymbols>true</IncludeSymbols>
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
<PublishRepositoryUrl>true</PublishRepositoryUrl>
</PropertyGroup>
<PropertyGroup Condition="'$(CI)' == 'true'">
<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>go deeper
Recall that Source Link lets a debugger fetch a package's source and that symbols ship as a .snupkg beside the .nupkg.
Explain IncludeSymbols, the symbols.nupkg default versus snupkg, how push sends both packages, and what Source Link records in the PDB.
Choose a symbol strategy per feed — snupkg, embedded or in-package PDBs — and wire PublishRepositoryUrl and ContinuousIntegrationBuild into CI correctly.
Decide how internal libraries expose source and symbols to consuming teams, weighing debuggability against package size and exposure of repository details.
## What a consumer needs to step into your code When a service team hits a bug inside the shared validation library, their debugger needs: - **Symbols** — the portable PDB, which maps IL back to file names and line numbers. - **Source** — the files at the exact commit that was built. Source Link solves the second; symbol packages, or an embedded PDB, solve the first. ## Source Link Source Link records, inside the PDB, how to fetch each source file from the repository host at the built commit. Since the **.NET 8 SDK** it is part of the SDK and enabled by default for repositories hosted on GitHub (and GitHub Enterprise), Azure Repos, GitLab 12.0+ and Bitbucket 4.7+. Such projects need no package reference and no property to get source information into the PDB; referencing a `Microsoft.SourceLink.*` package explicitly overrides the SDK's built-in version. Useful properties around it: | Property | Effect | |---|---| | `EmbedUntrackedSources` | embeds generated files that are not in source control into the PDB; defaulted to `true` by the SDK | | `PublishRepositoryUrl` | publishes the repository URL and branch into the nuspec's `<repository>` element; off by default so private URLs are not leaked | | `ContinuousIntegrationBuild` | set to `true` on the build server so source paths are deterministic; never on developer machines | ## Symbol packages `IncludeSymbols=true` — or `dotnet pack --include-symbols` — makes pack write a **second** package beside the main one. Its format comes from `SymbolPackageFormat`, and the pinned pack targets default it to **`symbols.nupkg`**: - `symbols.nupkg` — the legacy format: a full copy of the package plus PDBs, named `*.symbols.nupkg`. Kept for compatibility, for example native packages. - `snupkg` — a **symbol package** containing only portable PDBs, named `*.snupkg`. nuget.org's symbol server accepts only this format, and only portable PDBs. So `--include-symbols` alone gives the legacy file, which nuget.org's symbol server will not index. The usual project setting is therefore both properties together. ## Publishing and consuming symbols 1. Pack: `dotnet pack -c Release -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg` writes `Shared.Validation.2.3.0.nupkg` and `Shared.Validation.2.3.0.snupkg`. 2. Push: `dotnet nuget push Shared.Validation.2.3.0.nupkg` pushes the `.nupkg` first and then the `.snupkg` if it sits in the same folder; `--no-symbols` skips it and `--symbol-source` / `--symbol-api-key` target a separate symbol server. 3. Consume: a developer adds `https://symbols.nuget.org/download/symbols` (for nuget.org packages) to the debugger's symbol locations, and Source Link fetches the files. ## What goes wrong in practice - **Only `IncludeSymbols` set.** Pack writes a `.symbols.nupkg`, push sends it, and nuget.org's symbol server does not index it. The fix is `SymbolPackageFormat` `snupkg`. - **Windows PDBs.** A project with `DebugType` set to `full` produces Windows PDBs, which `.snupkg` and nuget.org's symbol server do not support; .NET SDK projects default to portable PDBs. - **Local paths in the PDB.** Without `ContinuousIntegrationBuild` on the build server, PDBs record agent-specific paths and builds are not fully deterministic. - **Private repository URLs.** `PublishRepositoryUrl` publishes the repository URL into the nuspec; leave it off for a package that leaves the organisation while its repository must stay private. - **Generated code.** Files produced during the build are not in source control, so Source Link cannot fetch them; `EmbedUntrackedSources` embeds them into the PDB instead. ## When .snupkg does not fit The Source Link README notes that `.snupkg` is supported on nuget.org but not by every feed. For an internal library published only to a private feed, two alternatives avoid a symbol server: - **Embed in the assembly** — `<DebugType>embedded</DebugType>` puts the portable PDB inside the DLL. No opt-in for consumers, at the cost of larger binaries. - **Include in the main package** — add `.pdb` to `AllowedOutputExtensionsInPackageBuildOutputFolder`; consumers must also opt in to copying symbols from packages, and every restore downloads them. | Option | Consumer opt-in | Main package size | Assembly size | |---|---|---|---| | `.snupkg` | none (symbol server) | unchanged | unchanged | | PDB in `.nupkg` | yes | larger | unchanged | | embedded PDB | none | unchanged | larger | For the internal validation library on a private feed, embedding the PDB is often the pragmatic choice, with Source Link pointing at the internal repository.
- A team sets only IncludeSymbols=true and nuget.org never shows their symbols. Why?`SymbolPackageFormat` defaults to `symbols.nupkg`, so pack produced a legacy `.symbols.nupkg`. nuget.org's symbol server accepts only `.snupkg` containing portable PDBs. Setting `SymbolPackageFormat` to `snupkg` and re-packing fixes it.
- Do you still need a Microsoft.SourceLink package reference in a .NET 10 project?Not for GitHub, Azure Repos, GitLab or Bitbucket: the SDK has included Source Link for those since .NET 8. A package reference is still needed for other hosts, and adding one for a supported host overrides the SDK's bundled version.
- IncludeSymbols=true produces a .snupkg by default.
- Source Link copies the library's source files into the .nupkg.
- Every .NET 10 project needs a Microsoft.SourceLink.GitHub reference for Source Link.
- ContinuousIntegrationBuild should be set to true on developer machines too.
- nuget.org's symbol server indexes legacy .symbols.nupkg files.
Assumes the .NET 10 SDK with NuGet 7 and Source Link 10.0.401; Source Link has been built into the SDK since .NET 8, while SymbolPackageFormat still defaults to symbols.nupkg in the pinned pack targets.