How to integrate your application with Crash Server

To integrate an application with Crash Server you need to do some steps.

There are some mandatory steps:

Register yourself in Crash Server
To work with Crash Server you need to register yourself.
Register your application
To integrate your application with Crash Server you need to register this application and get application GUID that you will need in next step.
Setup your application
- Client library should be integrated into application
  You should integrate one of these libraries:
  - Preferred one is native Crash Server library that supports all Crash Server features (like full memory dump upload and custom responses to users).
    1. Download Crash Server SDK that contains a library (crshhndl.dll) that hooks some interesting events (unhandled exceptions, terminate() and so on) and sends a crash report when event happens.
    2. Instantiate a global object of class CrashHandler in your application (see sample here) (also a Sample Application exists that is integrated with Crash Server). If you write a library and is working inside a process you don't own (for example you are writing a plug-in) you also need to use CrashHandler::SendReport in all entry points to you code.
    3. Add crshhndl.dll only to the installer of your application that goes public (only public builds properly registered would be accepted by Crash Server (see below), also there is no reason to use Crash Server for local builds since it is easier to debug a problem locally).
    PS: Library is a .dll about 1,5 Mb in size (2,0 Mb for x64) but most of its size is dbghelp.dll. Actually Windows (since XP) has its own dbghelp.dll but experience shows that latest dbghelp.dll writes dumps better than one that is in some Windows versions. But if size matters, it is discussable to make a library without dbghelp.dll, its size will be about 300 Kb.
  - Second one is CrashRpt library.
    1. You should integrate CrashRpt library into your application using these instructions. To let CrashRpt to send the crash reports to the Crash Server you should setup CR_INSTALL_INFO structure to use HTTP transport and set pszUrl field to https://www.crash-server.com/DumpUploaderCrashRptGate.aspx?appid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is applicaton GUID you have got on the second step. Also you should set uMiniDumpType to MiniDumpNormal (Crash Server accepts big memory dumps only through native client now and if you will set uMiniDumpType to anything else these dumps will be discarded). Crash Server specific part of CR_INSTALL_INFO structure initialization should look like that:info.pszUrl = _T("https://www.crash-server.com/DumpUploaderCrashRptGate.aspx?appid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"); info.uPriorities[CR_HTTP] = 1; info.uPriorities[CR_SMTP] = CR_NEGATIVE_PRIORITY; info.uPriorities[CR_SMAPI] = CR_NEGATIVE_PRIORITY; info.uMiniDumpType = MiniDumpNormal;
    2. Configure your application/installer/environment/build conveyor so that only the builds that are available to wide usage by multiple users and that you upload symbols for will send crash reports to Crash Server. There is no reason to use Crash Server for local builds since it is easier to debug a problem locally. If you will upload a report for a build that you didn't upload the symbols you will get problem with unhelpful stack.
- Debug Symbol information should be created for all application binaries
  Debug Symbol information is needed for unrolling the stack and for memory dump analysis. Now only Microsoft *.pdb files are accepted. To create it you need to specify /Zi option for C++ compiler and /DEBUG option for linker. Or you may do this in Visual Studio project properties:

Setup post-build steps for public builds

Symbols and binaries for public builds should be uploaded to Crash Server
They needed to unroll the stack. You need to check that you building a public build (build that will be run by someone else) and if so - upload symbols and binaries (*.exe, *.dll). To upload the symbols and binaries you should use SymUpload.exe utility that is a part of Crash Server SDK.
To upload your symbols and binaries use command:
SYMUPLOAD <app-family-id> <version> <hotfix-id> <path>, where:

app-family-id	Is an application GUID that you can see in application registration page (you have got it on step 2, and used in step 3.2)
version	Application version in format "n.n.n.n", where n is from 0 to 32000
hotfix-id	0 if unknown
path	Path or mask to your symbol/image files

for example:
SYMUPLOAD FDB41CEF-257D-4583-A70A-7680E777BCDE 2.1.157.0 0 .\Release\*.pdb
SYMUPLOAD FDB41CEF-257D-4583-A70A-7680E777BCDE 2.1.157.0 0 .\Release\*.exe
SYMUPLOAD FDB41CEF-257D-4583-A70A-7680E777BCDE 2.1.157.0 0 .\Release\*.dll
PS: Only stripped symbols are needed by Crash Server. Any symbols you upload will be stripped. It is important for you to have all full symbols for all published builds since without symbols you cannot analyze a crash dumps. It is better to store symbols in symbol server. If you do not have your own symbol server it can be discussed to have it on Crash Server side.

Also some best practices exist that can make your work more effective:

Turn off "Omit Frame Pointer Optimization" compiler /Oy- option
Frame Pointer Optimization complicates stack unrolling (in many cases debugger says that it cannot show full stack, only some latest calls) and memory dump analyzing (since it is harder to find some local variables). Also that optimization has no affect on performance, you can see that all Windows binaries has no FPO and even in VS2010 that optimization was turned off by default.
Integrate source server information in .pdb files
When there is a lot of version it is very difficult to find proper sources to debug a dump. Fortunately WinDbg has very good feature - a source server. With some easy actions source information is injected in .pdb files and when source file is needed WinDbg extracts correct revision directly from source control system.
Write the dumps on asserts and continue execution
Practice of writing a dump on asserts shows that this is very useful feature. Crash dumps shows only a subset of errors with known effect (crash), but assert violations finds comparable amount of bugs that are sometimes very tricky to reproduce manually and with dumps on asserts you have an ability to investigate such cases more easily. Even more dumps on asserts can change your paradigm of debugging of some tricky issues. Before that you needed to add some logging to interesting place of code and to instruct a single user on how to make these logs. And those actions can repeat some times, because logs don't give full information about the case. With dumps on assert in that cases you often just write some asserts, and any user (not only one that report original bug) who reproduces the bug will send you a memory dump, so you have more information and you get it much faster.
Use application verifier on public (but not release) builds by default
That practice shows itself very well. It helps to find some subset of bugs early, most important are memory corruptions, but other kind of bugs also can be found. Drawback of application verifier is some performance penalty (but it is visible only on CPU intensive applications and it could be adjusted in some range), because of that it should be enabled only on non-release builds.
To turn on application verifier you just need to write some values to [HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\YouApp.exe] registry key on installation of you application. You may use GUI tool to setup that values and then just copy it to your installer. Full page heap options is very useful, but if you experience not acceptable performance penalty you can reduce full page heap impact by reducing full page allocation from 100% to any percent or to totally off it and use light page heap.

If you experience any troubles in any point of that instruction feel free to contact with us and we will try to help you.