Cymbal

Cymbal is an MSBuild task that enables bundling dotnet symbols for references with a deployed app. The goal being to enable line numbers for exceptions in a production system.

Cymbal performs two operations

1. Copies symbols from references

Works around symbols not being copied from references. This is done via manipulating ReferenceCopyLocalPaths:

<Target Name="IncludeSymbolFromReferences"
        AfterTargets="ResolveAssemblyReferences"
        Condition="@(ReferenceCopyLocalPaths) != ''">
  <ItemGroup>
    <ReferenceCopyLocalPaths
            Include="%(ReferenceCopyLocalPaths.RelativeDir)%(ReferenceCopyLocalPaths.Filename).pdb"
            DestinationSubDirectory="%(ReferenceCopyLocalPaths.DestinationSubDirectory)" />
    <ReferenceCopyLocalPaths Remove="@(ReferenceCopyLocalPaths)"
                             Condition="!Exists('%(FullPath)')" />
  </ItemGroup>
</Target>

^{snippet source | anchor}

This is done at Build time.

2. Run dotnet-symbol

On a dotnet-publish any missing symbols are attempted to be downloaded via the dotnet-symbol tool (Source).

This is done at Publish time.

Usage

Install the NuGet package in the top level project. i.e. the project that 'dotnet publish' is called on

https://nuget.org/packages/Cymbal/

Install-Package Cymbal

dotnet-symbol required

To install the dotnet-symbol tool, the recommended approach is to install it as a local tool.

In the root of a repository execute:

dotnet new tool-manifest
dotnet tool install dotnet-symbol

This will result in a .config/dotnet-tools.json file:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-symbol": {
      "version": "1.0.335501",
      "commands": [
        "dotnet-symbol"
      ]
    }
  }
}

^anchor

dotnet tool restore can then be run locally or in a build environment:

dotnet tool restore

Or to point to a nested directory:

dotnet tool restore --tool-manifest src/.config/dotnet-tools.json

Scanned symbol servers

• https://symbols.nuget.org/download/symbols
• https://msdl.microsoft.com/download/symbols/

Overriding symbol servers

Add the following to the project or Directory.Build.props:

<ItemGroup>
  <SymbolServer Include="http://localhost:88/symbols" />
  <SymbolServer Include="http://localhost:89/symbols" />
</ItemGroup>

^{snippet source | anchor}

Cache Directory

The cache directory can be controlled via either:

• An environment variable CymbalCacheDirectory. Must contain a full path. Or:
• An MSBuild property CymbalCacheDirectory. This can be passed into a dotnet publish using -p:CymbalCacheDirectory=FullOrRelativePath. Path.GetFullPath() will be used on the value.

The resolved directory will be created if it doesn't exist.

The MSBuild property take priority over the environment variable.

Icon

Cymbals designed by Eucalyp from The Noun Project.