getsentry/sentry-dotnet-minidump

Capture Minidump of .NET Applications

This repository is deprecated in favor of the Sentry NuGet package.

sentry-native is bundled by default on Sentry and can capture native crashes for AOT compiled .NET apps.

Sentry Minidump SDK for .NET

This repository bundles sentry-native with Google's crashpad and distribute via NuGet with a .NET API to initialize. It allows capturing minidumps of .NET applications caused by native libraries or the .NET runtime itself.

Current supported platforms are: Windows, macOS and Linux all on x64. We can extend this as needed.

At this time this minimum frameworks supported are .NET Standard 2.1 or .NET Framework 4.7. This is due to the current bindings generated by CppSharp. We can likely lower it to .NET Standard 2.0 and .NET Framework 4.6.1 if there's demand.

If this is useful to you, help us in building this on Discord, #dotnet.

Processed Minidumps from Windows, macOS and Linux

How does it work?

When Init is called, the sentry-native SDK initializes crashpad which monitors the process for crashes. In the event of a crash, a minidump is generated and uploaded to Sentry. Sentry will notify you with a few seconds of the crash and you can inspect the event in Sentry.

By default Sentry throws away the minidump after processing it.
If you'd like to keep the minidump to inspect on Visual Studio, you need to opt-in. Sentry has extensive docs on attachments, minidumps and data scrubbing.

A .NET 5 crash on macOS

Debug Symbols

In order to stack unwind and symbolicate the minidump, Sentry needs access the symbols.

You can upload the symbols of your app with sentry-cli.

Alternatively you can add more Symbol Servers to lookup via your project settings in case you host your own.

.NET provides debug symbols of all official releases on a Microsoft symbol server and Sentry includes it out of the box. Currently it's not probing it though so you can add it yourself: The endpoint is: http://msdl.microsoft.com/download/symbols, with SSQP layout. Sentry will resolve these automatically soon so you won't need to add it yourself.

Run The Sample

To test it out, build the sample project and start the executable from the bin folder.

Set your own DSN on Program.cs first so the test event goes to yours Sentry dashboard.

The example below is for macOS (osx-x64). If you're on Windows, use win-x64. For Linux, linux-x64:

cd sample/Sentry.Minidump.Sample
dotnet build -c Release -r osx-x64

cd bin/Release/net5.0/osx-x64

dotnet Sentry.Minidump.Sample.dll

Example:

➜  osx-x64 git:(main) ✗ dotnet Sentry.Minidump.Sample.dll
[sentry] INFO using database path "/Users/bruno/git/sentry-dotnet-native/sample/Sentry.Minidump.Sample/bin/Release/net5.0/osx-x64/.sentry-native"
[sentry] DEBUG starting backend
[sentry] DEBUG starting crashpad backend with handler "/Users/bruno/git/sentry-dotnet-native/sample/Sentry.Minidump.Sample/bin/Release/net5.0/osx-x64/crashpad_handler"
[sentry] DEBUG using minidump url "http://sentry.garcia.in:80/api/5428537/minidump/?sentry_client=sentry.native/0.4.4&sentry_key=80aed643f81249d4bed3e30687b310ab"
[sentry] INFO started crashpad client handler
Unhandled exception. System.AccessViolationException: Attempted to read or write protected memory. This is often an indication that other memory is corrupt.
   at System.Runtime.InteropServices.Marshal.ReadInt32(IntPtr ptr, Int32 ofs)
   at System.Runtime.InteropServices.Marshal.ReadInt32(IntPtr ptr)
   at Sentry.Minidump.Sample.Program.Main(String[] args) in /Users/bruno/git/sentry-dotnet-native/sample/Sentry.Minidump.Sample/Program.cs:line 16
[69212:36013020:20201227,230059.285955:WARNING process_memory_mac.cc:93] mach_vm_read(0x7ffee9bf8000, 0x2000): (os/kern) invalid address (1)
[1]    69205 abort      dotnet Sentry.Minidump.Sample.dll

A .NET 5 crash on Windows

Download the minidump

Note On Platform Requirement

This package bundles an executable called crashpad_handler (or crashpad_handler.exe on Windows). This process creates a memory dump of your .NET process and uploads to Sentry. That means the executable needs to be deployed with your app, and needs +x access in order to get started (on macOS and Linux). NuGet packaging makes sure the file is actually copied to the output directory, and the SDK will attempt to set +x when running on macOS and Linux. You can opt out of that with AddExecuteFlagCrashpadHandler=false but unless you set +x yourself, no minidump will be created.

Build from source

The result of building sentry-native on Windows, macOS and Linux for x64 is already checked in, and the CppSharp binding generated too. So you can just dotnet pack if you only want to change the .NET solution. If you want to modify sentry-native, you'll need to regenerate the CppSharp bindings. There are scripts for everything in this repository.

Requirements:

• .NET 5 SDK
• Whatever is required to build sentry-native (depends on platform)
• Whatever is required to build CppSharp (depends on platform)

If you want to build all artifacts from source, the steps involved are:

Init submodules

Run setup.sh on macOS or Linux or setup.cmd on Windows This will initialize all git submodules.

Build native dependencies

Under sentry-native: Run build.sh on macOS or Linux or build.cmd.

This will build sentry-native, and copy the generated native library and the crashpad_handler to the relevant folder under sentry-native/sentry-native-artifacts. These are bundled in the NuGet package.

On Linux, make sure to install openssl lib, otherwise crashpad will fail to compile. For example, on Ubuntu: sudo apt-get install libssl-dev

Resources

• 
• 
• 
• 
• 

sentry-dotnet-minidump's Issues

Alternative Minidump creation

The minidump created by crashpad works fine and all native frames get correctly symbolicated. But to expand the server into symbolicating managed frames, DAC EnumMemoryRegions needs to be used to read the memory sections needed by the .NET debugger like ClrMD or sos into the minidump. That would require a patch to crashpad (tough to get accepted) and a lot more low level work than simply using the cross platform tool provided by .NET to create minidumps cross platform.

More context here: dotnet/diagnostics#1885

There are many options too instead of shelling out a program. A wealth of information on this comment from @noahfalk:

dotnet/diagnostics#151 (comment)

Alternative 1: Bundle .NET's createdump tool to create the minidump

It's possible the lib would need to multi-target and provide a version of createdump for the right CLR version.

Alternative 2: Use Microsoft.Diagnostics.NetCore.Client

This is to use the main Sentry .NET SDK to kick off the dump creation programatically and on restart/or a bundled handler .NET program to upload it. Or even upload on app restart with the .NET SDK, minidump in envelope.

Alternative 3: Call WriteDump from Microsoft.Diagnostics.NetCore.Client

Docs

Some limitations:

The process hosting the library needs to be NS2.0 or a netcoreapp2.1 or later. However, the target process needs to be 3.1 or above (5.0 if you want windows dumps, and 6.0 for machO native dumps as Noah pointed out) to get the dump support.
From this comment

Thanks @dbruning for the link

Explore binding `sentry-native` API with `cswin32`

https://github.com/microsoft/cswin32

Might only work with Win32 API though

SentryMinidump initialization

Environment

How do you use Sentry?
sentry.io

Which SDK and version?
latest

Steps to Reproduce

 SentryMinidump.Init(o =>
            {
                o.Dsn = "https://[email protected]/52132112";
                o.Debug = true;
            });

Leads to
System.EntryPointNotFoundException: 'Unable to find an entry point named 'sentry_options_new' in DLL 'sentry'.'

Expose the `sentry-native` API

We could expand the public API and maybe ship it as Sentry.Native in that case.

Unable to find an entry point named 'sentry_options_new' in DLL 'sentry'

Environment

How do you use Sentry?
Sentry SaaS (sentry.io)

Which SDK and version?
.NET 3.8.2

Steps to Reproduce

1. My app was already using Sentry for .NET
2. Added a call to SentryMinidump.Init(), as per the sample program.cs
3. Ran my app

Expected Result

App would run

Actual Result

App exited immediately, with message: Process finished with exit code -532,462,766."
If I debug, I see that an exception is thrown by SentryMinidump.Init():
System.EntryPointNotFoundException: Unable to find an entry point named 'sentry_options_new' in DLL 'sentry'.
at sentry.sentry.__Internal.SentryOptionsNew()

If I look at my app's bin directory, I can see that sentry.dll is 359KB and has version 3.8.2.0 (and Date Modified of 7/17/2021)
If I look in the sample app's bin directory, it has sentry.dll with no version info and with size 204KB (and Date Modified of 12/27/2020)

I must admit I'm not clear on the relationship between Sentry.Minidump and Sentry nuget packages. Do I need them both, or does Sentry.Minidump replace Sentry package? If I need them both, what order should the Init's occur?

Thanks!