BugSplat 9.0.0

BugSplat for .NET on Windows

Crash reporting for .NET 10 and .NET Framework 4.7.2+ apps on Windows, through the BugSplat native SDK. Crashes and handled exceptions are reported as minidumps, which BugSplat symbolicates from your uploaded symbols. Managed frames get file names and line numbers without you shipping PDBs.

Install

dotnet add package BugSplat

The package includes BugSplat's native runtime for x86, x64 and ARM64. At build time it copies the set that matches your app's architecture next to the executable: BugSplat.dll, BugSplatMonitor.exe, BugSplatReporter.exe and BugSplatWer.dll, plus their PDBs. They must ship with your app. The monitor is a separate process that writes the report after a crash and uploads it, and the reporter shows the crash dialog.

Use

using BugSplatDotNet;

var bugSplat = new BugSplat("YourDatabase", "YourApp", "1.0.0");

// Unhandled exceptions and native faults are now reported automatically.

try
{
    DoWork();
}
catch (Exception ex)
{
    // Call from inside the catch: the dump is taken at the throw site.
    bugSplat.Post(ex);
}

Upload your app's .exe, .dll and .pdb files to BugSplat with symbol-upload so reports show function names, files and line numbers. Build with <DebugType>full</DebugType> (Windows PDBs).

Architecture

The native runtime must match the architecture your process runs as. It is chosen from, in order:

1. RuntimeIdentifier, for example win-arm64.
2. PlatformTarget (x86, x64 or ARM64).
3. For .NET AnyCPU, the architecture of the .NET SDK doing the build. That is also what the app's .exe runs as.
4. For .NET Framework AnyCPU with Prefer32Bit, x86. Otherwise x64.

To override the choice, set <BugSplatNativeArchitecture>x86|x64|arm64</BugSplatNativeArchitecture>.

The files are copied for executables and test projects. A library loaded by a native host (a plugin, or a CLR hosted from C++) can set <BugSplatCopyNativeFiles>true</BugSplatCopyNativeFiles>. The files must then be deployed next to the host's executable, because that is where BugSplatMonitor.exe is looked for.

Run the app through its .exe. dotnet YourApp.dll makes dotnet.exe the process, and the monitor won't be found next to it.

Customize the crash dialog

The dialog's colours, fonts, layout, logo and wording come from a theme folder that BugSplatReporter.exe reads at run time. To ship one, add a folder named BugSplatTheme next to your project file:

YourApp.csproj
BugSplatTheme\
  theme.json
  strings.en-US.json
  logo.png

Write only what you change. Customize the crash dialog lists every key in theme.json and strings.en-US.json with its default. The dialog's source is available to Enterprise customers who need more than a theme can change.

The build copies the folder's contents, subfolders included, to theme\ in the output and publish folders, beside BugSplatReporter.exe, which is the only place the reporter looks. A single-file publish leaves it as a loose folder, because the reporter is a separate process that reads it from disk.

To keep the theme somewhere else, set its path, relative to the project:

<BugSplatThemeDirectory>..\Branding\CrashDialog</BugSplatThemeDirectory>

If that folder doesn't exist, the build fails (BSTHEME000) rather than quietly shipping the default dialog.

The reporter never fails on a bad theme: anything it can't use falls back to the default, so a crash report is never lost to a typo. That also makes mistakes quiet, so every build checks the folder with the same code the dialog uses and reports each fallback as a warning:

To silence one kind of finding, add its code to <NoWarn>. Set <BugSplatCheckTheme>false</BugSplatCheckTheme> to turn the check off. It runs only when building on Windows.

A library loaded by a native host that copies the native files with <BugSplatCopyNativeFiles>true</BugSplatCopyNativeFiles> gets the theme the same way, in its own output's theme\ folder; deploy that folder next to the host's executable along with the native files. If you copy BugSplat's files to the host yourself instead, copy your theme folder there as theme\ too.

Learn more

• BugSplat documentation
• Samples and source