What are Just My Code, symbols (PDB files) and Source Link, and how do you step into framework or NuGet package code?

1. From DLL to source line

 Orders.Api.dll is loaded by the runtime
      |
      v
 debugger reads the DLL's debug directory: PDB id (GUID + stamp) and file name
      |
      v
 search for a PDB with the SAME id, in order:
   1. embedded inside the DLL (<DebugType>embedded</DebugType>)
   2. next to the DLL
   3. local symbol cache
   4. symbol servers: Microsoft, NuGet.org, your Azure Artifacts feed
      |
      +-- not found or id mismatch --> "symbols not loaded": no source, no breakpoints
      |
      v
 PDB gives: sequence points + local names + Source Link JSON
      |   {"documents": {"/_/*": "https://raw.githubusercontent.com/org/repo/<commit>/*"}}
      v
 debugger maps /_/src/Abn/AbnValidator.cs to that URL at that exact commit
      |
      v
 downloads the file (once, then cached) --> shows source, binds breakpoints

The id match is strict. A PDB from a different build of the same code won't load, which protects you from seeing source that doesn't match the running code.

2. What a portable PDB contains

The .NET SDK produces portable PDBs by default on every OS. The older Windows-only PDB format is only needed for a few legacy tools.

3. Just My Code: what counts as "my code"

Visual Studio treats a module as user code when:

• its symbols are loaded, and
• it isn't optimised (a Debug build), and
• it isn't marked as non-user code (for example with [DebuggerNonUserCode]).

The default is on because most debugging is about your own code.

4. Step-by-step: stepping into ASP.NET Core or a NuGet package

The first session is slow while symbols download; they are cached afterwards. In Visual Studio, "Load only specified modules" avoids downloading symbols for everything.

When no symbols exist at all, Visual Studio and Rider can decompile the assembly so you can still read and step through it, with generated names instead of the original locals.

5. Source Link for your own libraries

Since the .NET 8 SDK, Source Link support for GitHub, Azure Repos, GitLab and Bitbucket is built in, so a library mostly needs publishing properties:

Pushing the .nupkg to NuGet.org or Azure Artifacts pushes the .snupkg next to it, and the feed serves it as a symbol server.

6. Deterministic builds and path mapping

Without ContinuousIntegrationBuild, a PDB contains paths such as D:\a\1\s\src\Abn\AbnValidator.cs from the build agent. With it, the compiler maps the repository root to /_/, so:

• builds of the same commit produce identical output (reproducible builds);
• agent folder structures don't leak into published packages;
• Source Link has a stable prefix to map to the repository URL.

Set it only on CI. Locally you want real paths so the IDE opens your own files.

7. Symbols in production

• Deploy PDBs with the app (or use embedded PDBs) so exception stack traces logged in production include file and line numbers.
• When analysing a dump from production, the dotnet-symbol tool downloads matching symbols for the modules in the dump, for example dotnet-symbol -o ./symbols ./core_20261022. Then point dotnet-dump or Visual Studio at that folder.
• Keep PDBs for every release you ship, for example in your artifact store or an internal symbol server, so old dumps stay readable.

8. Security

• Symbol servers and Source Link fetch content from the network. Configure only servers you trust. For private repositories the IDE uses your signed-in account to download source.
• Downloaded source is someone else's code. Reading it is fine; don't copy it into your project without checking the licence.
• PDBs reveal method names, local names and source paths, but they don't add secrets that aren't already in the code. Shipping PDBs is usually acceptable and makes crash dumps far more useful. Never put secrets in source in the first place.

9. .NET 11 awareness

Portable PDBs, Source Link and .snupkg are stable. Watch the .NET 11 SDK release notes for changes to default packaging or Source Link providers.

10. Try it yourself

1. In an ASP.NET Core app, set a breakpoint in an endpoint and look at the Call Stack: [External Code].
2. Turn off Just My Code, enable the Microsoft and NuGet.org symbol servers, and restart debugging.
3. Show external code in the Call Stack, double-click a Kestrel or routing frame, and watch Source Link download the file.
4. Open Debug > Windows > Modules and check the symbol status and symbol file path for Microsoft.AspNetCore.Routing.dll.
5. Pack one of your own libraries with the code example's .csproj and open the .snupkg as a zip to see the PDB.
6. Build the library twice with ContinuousIntegrationBuild=true and compare the DLL hashes: they match.

Library .csproj set up for symbols and Source Link:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <PackageId>Contoso.Abn</PackageId>
    <Version>1.4.0</Version>

    <!-- Symbols published as a separate .snupkg -->
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>

    <!-- Source Link: record the repo URL and embed files not in source control -->
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>

    <!-- Deterministic, path-mapped builds on CI (GitHub Actions sets GITHUB_ACTIONS=true) -->
    <ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
  </PropertyGroup>
</Project>

Pack and push both packages:

dotnet pack -c Release -o ./artifacts
dotnet nuget push "./artifacts/*.nupkg" --source "https://api.nuget.org/v3/index.json" --api-key "$NUGET_API_KEY"

VS Code launch.json settings to step into external code:

{
  "name": "Api (external code)",
  "type": "coreclr",
  "request": "launch",
  "program": "${workspaceFolder}/src/Api/bin/Debug/net10.0/Api.dll",
  "justMyCode": false,
  "suppressJITOptimizations": true,
  "symbolOptions": {
    "searchMicrosoftSymbolServer": true,
    "searchNuGetOrgSymbolServer": true
  }
}