BugSplat for Windows (C++)

Need help upgrading from an older version of BugSplat? Check out our upgrade guide to get started.

Overview 👀

This document explains how to modify your Microsoft Visual C++ application to provide full debug information to the BugSplat web application when it crashes.

Getting Started 🚦

To begin, download and unzip the BugSplat SDK for Microsoft Visual C++.

The SDK is organized per platform (win32, x64, ARM64) and configuration (Release, Debug):

Folder	Contents
BugSplat\inc	BugSplat.h (C++ API) and BugSplatC.h (C API)
BugSplat\<platform>\<config>\bin	Runtime files that ship next to your executable: BugSplatMonitor.exe, BugSplatRc.dll, BugSplatWer.dll, and BugSplat.dll
BugSplat\<platform>\<config>\lib\md	Static BugSplat.lib built with /MD (dynamic CRT)
BugSplat\<platform>\<config>\lib\mt	Static BugSplat.lib built with /MT (static CRT)
BugSplat\<platform>\<config>\lib\dll	Import library for BugSplat.dll

Link exactly one BugSplat.lib from the lib subfolder that matches your link model and runtime library setting, and ship the contents of bin with your application (BugSplat.dll is only needed if you link the import library).

To get a feel for the BugSplat service before enabling your application, feel free to experiment with the MyConsoleCrasher sample application, which is included as part of the software development kit and is also available on GitHub. For a native desktop application example, see the MyCrasher sample, an ATL/MFC Windows app.

Integration 🏗️

For WinUI 3 applications, BugSplat must be registered as a WER RuntimeExceptionModule. This process is demonstrated in the MyWinUI3Crasher sample, which is available in the SDK and on GitHub.

Add BugSplat to your application using the following steps:

1. Link with BugSplat.lib by adding an entry to Linker > Input > Additional Dependencies, and add the matching folder to Linker > General > Additional Library Directories: lib\md if your application builds with /MD (the Visual Studio default), or lib\mt if it builds with /MT.

2. Add BugSplatMonitor.exe, BugSplatWer.dll, and BugSplatRc.dll (from the SDK's bin folder) to your application's installer.

3. Ensure your installer runs with Administrator privileges and creates a RuntimeExceptionHelperModules registry key with a name containing the full path to BugSplatWer.dll. For more information about configuring WER see this doc.

BugSplat's runtime files (BugSplatMonitor.exe, BugSplatWer.dll, and BugSplat.dll if you use the dynamic library) depend on the Visual C++ 2015–2022 runtime: MSVCP140.dll, VCRUNTIME140.dll, and VCRUNTIME140_1.dll on x64. These DLLs are not part of Windows and are missing on machines where no application has installed the redistributable. If they're absent, your application will run normally but crash reporting will fail. End users may see a "MSVCP140.dll was not found" error at crash time.

This applies even if your own application doesn't need the Visual C++ runtime (for example, if it's built with /MT). Make sure your installer either:

• chains the Visual C++ Redistributable installer that matches the architecture of the BugSplat files you ship (vc_redist.x64.exe, vc_redist.x86.exe, or vc_redist.arm64.exe), or

• copies msvcp140.dll and vcruntime140.dll (plus vcruntime140_1.dll on x64) from the redistributable into your application folder alongside the BugSplat runtime files.

1. Include BugSplat.h in your application's source.

2. Create an instance of BugSplat following the example in MyConsoleCrasher. The BugSplat constructor requires three parameters: database, application, and version. A new BugSplat database can be created on the Database page. Choose values for application name and version to match your product release. These same values are typically used when uploading symbol files for your application. Learn more about symbol uploads at symbol-upload.

#include "BugSplat.h"

BugSplat g_BugSplat(BUGSPLAT_DATABASE, APPLICATION_NAME, APPLICATION_VERSION);

1. Modify your build settings so that symbol files are created for release builds. Set C/C++ > General > Debug Information Format to Program Database /Zi. Be sure to also set Linker > Debugging > Generate Debug Info to Yes (/DEBUG).

2. Configure a Post-Build step to upload your application's symbol files. Your script should authenticate using OAuth Client Credentials. You can create credentials on the Integrations page under the OAuth tab.

symbol-upload-windows.exe -b your-database -a your-app -v your-version -i your-client-id -s your-client-secret -d "$(OutputDir)\"

To get complete symbolicated call stacks and variable names for each crash, you should upload all .exe, .dll, and .pdb files for your product every time you build a release version of your application for distribution or internal testing.

Dynamic Library 🔗

The SDK also ships as a dynamic library, BugSplat.dll, with a flat C API declared in BugSplatC.h. The DLL exposes the same crash reporting engine as BugSplat.lib through BugSplat_* functions. Choose the dynamic library when:

• You don't want your runtime library setting (/MT vs /MD) coupled to BugSplat's. Only the C ABI crosses the DLL boundary, so your application's CRT choice doesn't need to match the SDK's.

• You're calling BugSplat from another language (C#, Rust, Python, etc.) via P/Invoke or FFI.

To integrate the dynamic library, follow the steps above with these differences:

1. Link with the import library lib\dll\BugSplat.lib instead of a static BugSplat.lib, and include BugSplatC.h instead of BugSplat.h.

2. Ship BugSplat.dll alongside your executable, in addition to BugSplatMonitor.exe, BugSplatWer.dll, and BugSplatRc.dll.

3. Initialize BugSplat with the C API:

#include "BugSplatC.h"

BugSplat_Init(BUGSPLAT_DATABASE, APPLICATION_NAME, APPLICATION_VERSION);
BugSplat_SetUser(L"fred");
BugSplat_SetAttribute(L"branch", L"main");

The C API is also available to static library consumers: define BUGSPLAT_STATIC before including BugSplatC.h. See the API documentation for the full list of BugSplat_* functions.

Verification ✅

Test your application by forcing a crash.

*(volatile int *)0 = 0;

Verify that the BugSplat dialog appears, and that crashes are posted to your BugSplat account. Ensure that symbol names in the call stack are resolved correctly. If they aren’t, double-check that the correct version of symbol files and all executables for your application have been uploaded to BugSplat.

If everything was configured correctly, you should see a crash report that looks like this in your BugSplat database.

BugSplat Crash Page

Crash Dialog

Instructions for modifying the default crash dialog can be found on the Windows Dialog Box page.

User Feedback

In addition to crash reporting, BugSplat supports collecting non-crashing user feedback such as bug reports and feature requests. Feedback reports appear in BugSplat with the "User Feedback" type, grouped by title.

Set user details and an application key, then call PostFeedback on your BugSplat instance:

g_BugSplat.SetUser(L"Jane");
g_BugSplat.SetEmail(L"[e-mail]");
g_BugSplat.SetKey(L"en-US");

bool success = g_BugSplat.PostFeedback(L"Login button broken", L"Nothing happens when I tap it");

To include file attachments such as screenshots or log files:

std::vector<const wchar_t*> attachments = {
    L"C:\\path\\to\\screenshot.png",
    L"C:\\path\\to\\log.txt"
};
bool success = g_BugSplat.PostFeedback(L"Login button broken", L"Nothing happens when I tap it", attachments);

You can also add attachments individually with AddAttachment() before calling PostFeedback(). All attachments passed to PostFeedback are cleared after each feedback upload whereas attachments added via AddAttachment() are added the current report and future reports during the current session.

Dependencies

See technology dependencies on our dependencies page.