CODEWITHSUNDEEP
c#visual-studiomsbuildnuget
monstertjie_za
monstertjie_za

Reputation: 7803

Include pdb files into my nuget (nupkg) files

I am using MSBuild to generate my nuget packages.

Is there any command I need to set, to allow it to include my .pdb files, for stepping into the source while debugging?

I do not want the source files to be included into the project that is pulling in the nuget package.

Upvotes: 81

Views: 46684

Answers (8)

Paul Hatcher
Paul Hatcher

Reputation: 8156

Producing

Simplest way of configuring is to have a Directory.Build.props with the common parameters something like this...

<Project>
  <PropertyGroup>
    <!-- Based on https://devblogs.microsoft.com/dotnet/producing-packages-with-source-link/ -->
    <!-- Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
    <PublishRepositoryUrl>true</PublishRepositoryUrl>

    <!-- Embed source files that are not tracked by the source control manager in the PDB -->
    <EmbedUntrackedSources>true</EmbedUntrackedSources>

    <!-- Embed symbols containing Source Link in the main file (exe/dll) -->
    <DebugType>embedded</DebugType>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
  </PropertyGroup>
<Project>

In each project that produces a package you can then reference the appropriate SourceLink assembly for your system.

Explaination as follows:

  • ContinuousIntegrationBuild: Causes your CI system to produce canonical paths to files, should only be set for CI server as otherwise you won't be able to find local sources DebugType
  • GeneratedDocumentationFile: Generates the XML documentation file for inclusion with the dll - you do write docs don't you ;-)
  • Embedded: Adds the pdb data to the assembly file, simplifies distribution at the cost of increasing your dll size

More information at this MS blog article

Consuming

NET 7

Copying the symbol files to the execution directory is now incorporated in the NET 7.0 SDK/VS2022 17.4+ as an opt-in approach. Add the following fragment to your project file...

<PropertyGroup>
  ...
  <CopyDebugSymbolFilesFromPackages>true</CopyDebugSymbolFilesFromPackages>
  <CopyDocumentationFilesFromPackages>true</CopyDocumentationFilesFromPackages>
</PropertyGroup>

This will copy all symbols and documentation files into your output directory; if you only want a subset, e.g. your files, you will have to implement a filtering mechanism on top of this

Earlier

If you are using VS2017 15.4 or later, you can define a MSBuild property in your project file

<AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>

This is discussed in NuGet #4142

However, there is still an issue as the new project system does not copy the pdbs from packages to the bin/publish folder for .NET Core 3.0+, a good summary is also at sourcelink/#628

As the fix is only supported in the .NET 7 SDK+, you will need a work-around which is to include the following fragment into API and test projects to ensure you have the appropriate pdbs to allow you to step into the remote source code.

<!-- https://github.com/dotnet/sdk/issues/1458#issuecomment-1063915490 -->
<Target Name="IncludeSymbolFiles" AfterTargets="ResolveAssemblyReferences" Condition="@(ReferenceCopyLocalPaths) != ''">
  <ItemGroup>
    <ReferenceCopyLocalPaths Include="%(ReferenceCopyLocalPaths.RelativeDir)%(ReferenceCopyLocalPaths.Filename).pdb;                                %(ReferenceCopyLocalPaths.RelativeDir)%(ReferenceCopyLocalPaths.Filename).xml" />
    <ReferenceCopyLocalPaths Remove="@(ReferenceCopyLocalPaths)" Condition="!Exists('%(FullPath)')" />
  </ItemGroup>
</Target>

Upvotes: 73

Xavier John
Xavier John

Reputation: 9437

In 2023, the right way to do this is using SymbolLink.

Include the following NuGet package and it will set all the necessary properties. https://github.com/dotnet/reproducible-builds

I have used it in my DLL and people are able to debug it. https://github.com/xavierjohn/FunctionalDDD

Upvotes: 5

Tal Aloni
Tal Aloni

Reputation: 1519

The newer approach would be to use the following .csproj properties:

<DebugType>embedded</DebugType>
<EmbedAllSources>true</EmbedAllSources>

EmbedAllSources - Will include source code in the PDB for easier debugging.

Setting DebugType to embedded will cause the PDB to be embedded in the .DLL.

So using the two options together the source code will be embedded in the DLL.

Upvotes: 3

Josef Ginerman
Josef Ginerman

Reputation: 1560

With the .csproj format of .NET Core NuGet creation is much easier, since MSBuild does most of the work.

In order to include your pdb files you just have to enter the tag <IncludeSymbols>true</IncludeSymbols> in a PropertyGroup in your project's .csproj file.

This will create an additional .symbols.nupkg package, which you can release to your [debug] feed.

Old .NET framework files can be easily mapped to the new csproj with open source libs, like hvanbakel's repo

Upvotes: 37

Tal Aloni
Tal Aloni

Reputation: 1519

The approach that worked for me was adding the PDB as content which had the benefit it will be copied alongside the DLL. (PackageCopyToOutput was required)

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <EmbedAllSources>true</EmbedAllSources>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="bin\$(Configuration)\$(AssemblyName).pdb" PackagePath="contentFiles\any\netstandard2.0\$(AssemblyName).pdb">
       <PackageCopyToOutput>true</PackageCopyToOutput>
    </Content>
  </ItemGroup>
</Project>

EmbedAllSources - Will include source code in the PDB for easier debugging.

You may also want to consider setting "Optimize" to false for improving debugging experience in release configuration.

Upvotes: 5

farlee2121
farlee2121

Reputation: 3347

This can also be accomplished with the dotnet CLI.

By packaging with 

dotnet pack --include-symbols --include-source [path-to-project-here]

I get full debugging on the packages I generated

Upvotes: 11

Milad
Milad

Reputation: 569

Refer to this link. Actually you should add -Symbols to the end of command to create a symbols package. You shouldn't add pdb files to main nuget package.

Upvotes: 3

Jeff Shepler
Jeff Shepler

Reputation: 2105

While it may not help for debugging, it's definitely useful to include .pdb files so that stack traces have line numbers.

In the nuspec file, include a <files> element (child of <package>, sibling of <metadata>). This is what I have in one of my class libraries:

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net452\" />
</files>

Make sure the target is the same folder as where your .dll file is put in the package.

Upvotes: 43

Related Questions