guidance for embedding pdb in nupkg vs snupkg #255
Comments
The NuGet team collected numbers on this and the results show that this "slight" increase significantly affects download times in some regions.
Definitely. We could potentially use the same model for XML documentation files as for PDBs - that is move them to a "doc" server.
This is a point in time problem. I expect that the feature will be added to all NuGet servers in future.
I agree. That doesn't mean Symbol Servers need to retire though. One solution is to add symbol download to |
|
@ctaggart I have exactly the case that I want to use local feeds and Artifactory instead of Nuget.org. Can you please point me to the current best approach to embed PDBs and source files? I want to use it for debugging as well as for code coverage analysis. |
I expect that this too would be fixed in future. Meanwhile I would gladly trade slower download times for a simpler debugging experience. |
|
We are in the same situation as @TFTomSun. We are implementing SourceLink against BitBucket, and we feel that while Artifactory may have symbol server support, it would be easier to put the PDB in the NuGet package for a few reasons:
So guidance/best practices on how to best package PDB files in NuGet assemblies would definitely be appreciated. |
|
@casperOne Makes sense. It's pretty straightforward to add the PDB to the package: https://github.com/dotnet/sourcelink#alternative-pdb-distribution |
* Re-added SourceLink support Getting this to work was quite a challenge. I started out with the minimal example described at https://blog.jetbrains.com/dotnet/2020/02/03/sourcelink-consuming-apis-nuget-dependent-code/ and the guidance at https://github.com/dotnet/sourcelink/. This creates a .snupkg (containing symbols) next to the .nupkg, both of which need to be uploaded to nuget.org. At the moment, nuget.org is the only package registry that supports this. It does not work for local feeds, AppVeyor or any other registry (https://stackoverflow.com/questions/54211644/publish-snupkg-symbol-package-to-private-feed-in-vsts). And requires an internet connection during debug, as there is currently no command to fetch all symbols upfront. After uploading to NuGet.org, stepping into sources did not work on my machine (VS Debug settings: Enable Source Link support checked and Enable Just My Code unchecked). Then I enabled the NuGet.org Symbol Server, which started downloading symbols for all .NET Core packages during my debug session, which took forever so I aborted. It turned out that in the past, SourceLink worked by including the PDB in .nupkg, but [guidance was changed](dotnet/sourcelink#255) to use the nuget.org symbol server instead. I installed the sourcelink global tool (https://www.meziantou.net/how-to-debug-nuget-packages-using-sourcelink.htm) and ran it with the `test` switch, which failed and reported that AssemblyInfo.cs could not be found. This sounds reasonable, because the file is auto-generated by the .NET Core build chain. As discussed [here](dotnet/sdk#2679), symbol server support is not working very well for numerous reasons. So I reverted to [including the PDB](https://www.hanselman.com/blog/ExploringNETCoresSourceLinkSteppingIntoTheSourceCodeOfNuGetPackagesYouDontOwn.aspx) instead of using symbol server (using `$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>`) and setup a local nuget feed. This worked, but only because the DLL and PDB contained hardcoded paths to my sources on disk. There was no prompt to download sources from GitHub. Renaming the JADNC directory or adding `<DeterministicSourcePaths>true</DeterministicSourcePaths>` (which changes paths like `c:\source\repos\JsonApiDotNetCore\...` to `\_\JsonApiDotNetCore\...`) broke the experience. I had to manually browse to the PDB file on disk (via Modules, Load Symbols) to be able to step into sources again. The only way I got this working without intervention was to embed the PDB inside the DLL, using `<DebugType>embedded</DebugType>`. Note you need to push first, so that the commit hash stored in .nupkg exists on GitHub. And have Enable Just My Code unchecked in VS Debug settings. Other changes in this PR: - Fixed package tags (must be single words, because tags are space-delimited in .nuspec) - Added description (shown in VS Package Manager UI) - Removed RepositoryType and RepositoryUrl, so they are calculated (and use the URL of my fork) * Removed unneeded folder in project file * Empty commit to restart TravisCI * Empty commit to restart TravisCI
* Re-added SourceLink support Getting this to work was quite a challenge. I started out with the minimal example described at https://blog.jetbrains.com/dotnet/2020/02/03/sourcelink-consuming-apis-nuget-dependent-code/ and the guidance at https://github.com/dotnet/sourcelink/. This creates a .snupkg (containing symbols) next to the .nupkg, both of which need to be uploaded to nuget.org. At the moment, nuget.org is the only package registry that supports this. It does not work for local feeds, AppVeyor or any other registry (https://stackoverflow.com/questions/54211644/publish-snupkg-symbol-package-to-private-feed-in-vsts). And requires an internet connection during debug, as there is currently no command to fetch all symbols upfront. After uploading to NuGet.org, stepping into sources did not work on my machine (VS Debug settings: Enable Source Link support checked and Enable Just My Code unchecked). Then I enabled the NuGet.org Symbol Server, which started downloading symbols for all .NET Core packages during my debug session, which took forever so I aborted. It turned out that in the past, SourceLink worked by including the PDB in .nupkg, but [guidance was changed](dotnet/sourcelink#255) to use the nuget.org symbol server instead. I installed the sourcelink global tool (https://www.meziantou.net/how-to-debug-nuget-packages-using-sourcelink.htm) and ran it with the `test` switch, which failed and reported that AssemblyInfo.cs could not be found. This sounds reasonable, because the file is auto-generated by the .NET Core build chain. As discussed [here](dotnet/sdk#2679), symbol server support is not working very well for numerous reasons. So I reverted to [including the PDB](https://www.hanselman.com/blog/ExploringNETCoresSourceLinkSteppingIntoTheSourceCodeOfNuGetPackagesYouDontOwn.aspx) instead of using symbol server (using `$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>`) and setup a local nuget feed. This worked, but only because the DLL and PDB contained hardcoded paths to my sources on disk. There was no prompt to download sources from GitHub. Renaming the JADNC directory or adding `<DeterministicSourcePaths>true</DeterministicSourcePaths>` (which changes paths like `c:\source\repos\JsonApiDotNetCore\...` to `\_\JsonApiDotNetCore\...`) broke the experience. I had to manually browse to the PDB file on disk (via Modules, Load Symbols) to be able to step into sources again. The only way I got this working without intervention was to embed the PDB inside the DLL, using `<DebugType>embedded</DebugType>`. Note you need to push first, so that the commit hash stored in .nupkg exists on GitHub. And have Enable Just My Code unchecked in VS Debug settings. Other changes in this PR: - Fixed package tags (must be single words, because tags are space-delimited in .nuspec) - Added description (shown in VS Package Manager UI) - Removed RepositoryType and RepositoryUrl, so they are calculated (and use the URL of my fork) * Removed unneeded folder in project file * Empty commit to restart TravisCI * Empty commit to restart TravisCI
|
#1141 has fixed this, I believe. The README now recommends symbol packages when publishing to NuGet.org, and no longer recommends against including symbols in the main package.
5 years later, the Azure Artifacts proposal has not progressed past the initial "Under Review" stage and the various GitHub Packages feedback discussions have not received any response. According to https://github.com/NuGet/docs.microsoft.com-nuget/issues/2343#issuecomment-796313766 GitHub "have a firm stance of not supporting them", but I could not find a source for that claim. |
I'd like to revisit the change in guidance from f92b277 as a fix to #229.
This is only when publishing to NuGet.org. The only time a snupkg would be useful is when publishing to NuGet.org. If you are using any other NuGet feed such as:
Including PDBs in the .nupkg works all of those places and NuGet.org as well. It works at every step of development. It decreases the size of the nupkg download only slightly. The same can be said for embedded XML documentation.
Symbol Servers need to retire
One of the most time frustrations for me is when Visual Studio debugger HTTP queries symbol servers for symbols when I want to debug something. I should be able to lock dependencies and have
dotnet restorebring all of the available symbols asynchronously for all of the locked dependencies directly after a restore. It would be nice if all NuGet servers supported snupkg too anddotnet restoreof symbols would look for snupkg first before querying Symbol Servers.The text was updated successfully, but these errors were encountered: