From 297801152e3b1e52d255ec67c613a774101cfe74 Mon Sep 17 00:00:00 2001 From: Skyrunner-Dev-ops Date: Mon, 26 Oct 2026 23:08:23 +0530 Subject: [PATCH] Clarify debugging requirements when embedding symbols in NuGet packages (Fixes #29417) --- docs/standard/library-guidance/nuget.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/standard/library-guidance/nuget.md b/docs/standard/library-guidance/nuget.md index 51c244eb1e172..ff7697cb87b2b 100644 --- a/docs/standard/library-guidance/nuget.md +++ b/docs/standard/library-guidance/nuget.md @@ -107,6 +107,9 @@ An alternative to creating a symbol package is embedding symbol files in the mai The downside of embedding symbol files is that they increase the package size by about 30% for .NET libraries compiled using SDK-style projects. If package size is a concern, you should publish symbols in a symbol package instead. +> [!NOTE] +> Embedding symbol files (`*.pdb`) in a package only provides debug symbols with source file paths from the build machine. To enable consumers to step into source code when debugging on another machine, configure [Source Link](sourcelink.md) or embed the source code files by setting `true`. + ✔️ CONSIDER publishing symbols as a symbol package (`*.snupkg`) to NuGet.org > Symbol packages (`*.snupkg`) provide developers a good on-demand debugging experience without bloating the main package size and impacting restore performance for those who don't intend to debug the NuGet package.