|
FAQ
What is crashrpt?CrashRpt is an open source library providing a set of error handling, reporting and post-processing tools for applications created in Microsoft Visual C++ and running in Windows. What license does crashrpt use?CrashRpt is licensed under the New BSD License. Other software included in CrashRpt distribution is provided under other licenses, as listed in the table below. Is crashrpt a fully open-source?Actually, the Microsoft Debug Help Library (dbghelp.dll) CrashRpt depends on is not an open-source software. However, currently there is no possibility to remove this dependency. You can consider dbghelp.dll as a standard system library that is distributed with CrashRpt to avoid problems with older dbghelp.dll's versions installed on end-users` computers. Why should I use crashrpt in my Visual C++ project?If you have ever tried to determine the reason of a crash on user's machine, you might know how difficult it is when you have user's directions only: "I opened something, then I clicked something and then it stopped working". Most users won't contact you to tell about the problem and just give up using the program after several crashes. Users who decide to report the problem might not have technical knowledge, so it is difficult to determine the reason of the problem based on their instructions. This makes debugging remote crashes almost impossible, except in the simplest situations. That's why it is important to use special tools to report errors automatically. What are the main features of crashrpt?
Are there any beginner's tutorials?You may read the Integrating Crash Reporting into Your Application - A Beginners Tutorial article on CodeProject.com. A good starting point for learning CrashRpt is the FAQ you are currently reading and the Online Documentation. If you speak Russian you may read this article Using the CrashRpt Library on rsdn.ru. Can I use crashrpt in a commercial application?According to New BSD licence, you can freely use CrashRpt in any application. Should I give credits if my application uses crashrpt?The New BSD License clearly states that an application that distributes CrashRpt in compiled (binary) form must reproduce the copyright notice, the list of conditions and the disclaimer in the documentation and/or other materials provided with the distribution. Where would you like your copyright notice reproduced? Is the About dialog and an accompanying Readme sufficient?Yes, feel free to redroduce the copyright notice in your About dialog. The accompanying Readme would be sufficient, too. I want to sign crashrpt binaries with some tools. Is this a violation of the crashrpt license?No, the New BSD License that is used by CrashRpt permits to distribute the CrashRpt binaries with or without modification. So, feel free to sign CrashRpt binaries or modify them any other way. How to deal with those licenses of other software included in crashrpt distribution? It seems to me that one have to read all licenses and do what they require, isn't it?Yes, you are right. You should follow the instructions listed in those licenses. In most cases including those licenses into your distribution would be sufficient. What programming languages can I use crashrpt in?You can use CrashRpt in C++ programs created using Visual C++. You can not use it in .NET or in Visual Basic. Can I use crashrpt in an MFC-based application? ATL/WTL-based application? WinAPI application?Yes, you can use CrashRpt in a Visual C++ project using any of the technologies: MFC, ATL/WTL or pure WinAPI. I install crashrpt to my MFC app, but exceptions are not caught. What do I do?You can override your CWinApp::Run() method and install CrashRpt there. In the CPP file containing your App class, add the following code: int CYourApp::Run()
{
// Call your crInstall code here ...
BOOL bRun;
BOOL bExit=FALSE;
while(!bExit)
{
bRun= CWinApp::Run();
bExit=TRUE;
}
return bRun;
}What is an exception?An exception or a critical error typically means that a program stops working normally and needs to stop its execution. For example, an exception may occur because of the following:
Where can I find the latest version of crashrpt?The latest version of CrashRpt can be found at Downloads page. For the list of changes, see WhatsNew. How do I open crashrpt distribution archive?CrashRpt uses 7z file format for its distribution archive, because this format offers better compression than regular zip format. You can open the archive using 7-Zip program. I can't find the answer to my crashrpt-related question in this FAQ. What do I do?You can sign in using Google account and add a comment for this wiki page. Or you can ask a question using our Forum (Google account is also required). How do I report a bug in crashrpt or request a new feature?You can create an issue at our Issues page. We appreciate your feedback. Note that creating an issue requires you to be signed in using Google account. I found a bug in CrashRpt.dll or in CrashSender.exe (it crashes itself :)) and want to debug it in Visual C++ to determine the reason of the problem. What to I do?Its easy to run CrashRpt.dll code in step-by-step debugging mode. Just trigger an exception in the application. But there may be a problem if Visual C++ doesn't allow you to debug after exception had occurred. To workaround this, generate error report manually without exception, using crGenerateErrorReport() function. This way you should be able to debug. If the code in CrashRpt.dll works fine, but CrashSender.exe crashes, you need to attach to CrashSender.exe process when it is launched. In Visual C++ window, open Debug | Attach to process... menu and select CrashSender.exe in the list of processes. Then you will be able to run the code in step-by-step debugging mode. How do I contribute into crashrpt project development?First of all create a topic in our Forum and describe there how you would like to contribute. Then we will add your email to the list of project members and you will be able to make changes in the source code. How can I show my appreciation of crashrpt project?If you like CrashRpt and use it in your software, you can show your appreciation by adding your project name and logo to the WhoUsesCrashRpt page. By doing this you make CrashRpt more significant for other users and also support further development. Another way to support further development is by donating to CrashRpt.
Are there any analogous software for crash reporting?Yes, they are listed in the table below:
What Windows versions crashrpt can work in?CrashRpt supports Windows 2000/XP/2003/Vista and Windows 7. What Visual C++ versions can I use crashrpt in?You can compile CrashRpt in Visual C++ .NET 2003, Visual C++ 2005, Visual C++ 2008 and in Visual C++ 2010. Visual C++ 6.0 is not supported. You can also compile CrashRpt in Visual C++ Express Edition. For additional info on compiling CrashRpt in VC++ Express, see below. How do I compile crashrpt in Visual C++ Express Edition?In order to compile CrashRpt in Visual C++ Express Edition, you additionally have to download and install either Microsoft Windows Driver Kit 7.0 (recommended) or Microsoft Platform SDK for Windows Server 2003 SP1. Below these two alternatives are described: a. You can download Windows Driver Kit from here. After installing WDK, in VC++ Express window, open menu Tools->Options...->Projects and Solutions->VC++ Directories. In the 'Show directories for' combo, select 'Include files' and then add [WDK_Folder]\Inc\crt\atl71 path to the list of include directories ([WDK_Folder] should be replaced with actual folder name). b. You can download Platform SDK from this place. After installing Platform SDK, in VC++ Express window, open menu Tools->Options...->Projects and Solutions->VC++ Directories. In the 'Show directories for' combo, select 'Include files' and then add [Platform_SDK_Folder]\Include\atl path to the list of include directories ([Platform_SDK_Folder] should be replaced with the actual folder name). Note: In VC++ 2010 Express, there is no usual VC++ Directories page. Instead, open the Property Manager window, multi-select all projects and right click the selection. In the appeared dialog, open Configuration Properties->VC++ Directories. In the Include Directories field, enter the required path. That's all. Now you are be able to compile CrashRpt. Why do I have to install Windows Driver Kit or Platform SDK for Windows Server 2003 to be able to compile crashrpt in Visual C++ Express?This is because CrashRpt depends on WTL library, which in turn depends on Microsoft's ATL library. ATL library is a part of Visual Studio SDKs. The latest version at the moment is ATL 8.0. An older version, ATL 3.0 is also included into Microsoft Platform SDK for Windows Server 2003. Since then, Platform SDK was renamed into Windows SDK. However, Microsoft didn't include ATL into Windows SDK to encourage using of commercial Visual Studio having ATL. The dependency on ATL introduces a lot of problems for WTL, so in the future WTL developers might remove this dependency at all (if possible). For additional info on using WTL with VC++ Express, see this article. Where do I look for VC++ Directories in Visual C++ 2010?In VC++ 2010, there is no usual VC++ Directories page. Instead, you open the Property Manager window, multi-select all projects and right click the selection. In the appeared dialog, open Configuration Properties->VC++ Directories. For additional information, see this post. What platforms crashrpt can be compiled for?Since v1.2.1, CrashRpt can be compiled for both 32-bit (Win32) and 64-bit (x64) platforms. Earlier versions supported Win32 platform only. Why is it strongly recommended that I compile crashrpt myself?It is strongly recommended that you compile CrashRpt yourself to ensure CrashRpt uses the same C run-time DLLs as your application. CrashRpt distribution already has compiled CrashRpt binaries, but it is not recommended to use them with your software, because your software may use different C run-time DLLs, and CrashRpt won't be able to intercept exceptions in your C run-time libraries. Where do I look for crashrpt documentation?The documentation is usually included into the CrashRpt distribution archive. To open the documentation, click the index.html in the top level directory of the CrashRpt distribution. Online documentation for the latest CrashRpt version is also available here: Online Documentation. How do I properly install crashrpt?This depends on CrashRpt version you use. Typically, you download and unzip CrashRpt archive to some folder and then follow installation instructions listed in the documentation. How does crashrpt support multi-lingual user interface?Since v.1.1.3, CrashRpt supports multi-lingual user interfaces. You can find a language file inside of the lang_files subdirectory of crashrpt distribution. The language file contains localized strings used by CrashRpt dialogs. You should place a valid language file named as crashrpt_lang.ini to the directory where CrashSender.exe file is located in order to make CrashRpt work properly. The language file is a text document in UNICODE format and having INI extension. If your software supports several languages, you can distribute several language files with your software. On install, rename an appropriate file to crashrpt_lang.ini and copy it to the folder where your CrashSender.exe is located. Can I contribute a language file?If there is no language file for your favorite language, you can contribute one. Also, if you see that there are some mistakes in an existing language file, you may want to improve it and then contribute your changes. For additional information, please see the Internationalization Support section of the documentation. How does crashrpt work internally?CrashRpt consists of two core modules: CrashRpt.dll and CrashSender.exe. CrashRpt.dll contains functionality for intercepting exceptions in a client software. CrashSender.exe contains functionality for compressing and sending error reports to the software's support team. It is unsafe to do complex operations in the crashed program which may be unstable. CrashRpt is separated into these modules to be able to close the application which have crashed and to continue sending the error report in CrashSender.exe in background. Typically a process (executable file) loads CrashRpt.dll into its address space when process starts. This single instance of CrashRpt is shared between all DLL modules that are loaded into the address space of the process. Client application uses CrashRpt API functions to set exception handlers in the process once, typically in its main() function. In a multi-threaded program, client additionally sets exception handlers in the beginning of thread procedure of each worker thread. How can I use crashrpt without CrashSender.exe?You can not generate crash reports without CrashSender.exe. It is unsafe to do complex operations in the crashed program which may be unstable. CrashSender.exe collects information about the crash, closes the application which have crashed and continues sending the error report in background. What .h file should I include in my code and what .lib file should I link my code to?Include CrashRpt.h header file in the beginning of your code. // Include CrashRpt header #include "CrashRpt.h" You also need to add CrashRpt.lib to the list of input libraries for your project. In the Solution Explorer window, right-click your project and choose Properties item in the context menu. Then open Configuration Properties->Linker->Input->Additional Dependencies and then add CrashRpt.lib to the list of libraries. How is crashrpt.dll loaded and how is it shared between other modules loaded into process address space?Typically your process (EXE) loads CrashRpt.dll into process address space when process starts. This single instance of CrashRpt is shared between all DLL modules that are loaded into the address space of the process. My software is not an EXE, but DLL (e.g. a plugin for another software). Can I use crashrpt in such case?Generally, it is not recommended to use CrashRpt if your software is a plugin DLL. It would be better if the client process (EXE) take care of exception handling instead of your DLL. You may try to install exception handlers in your DllMain() function, but typically you can't guarantee that the client process (EXE) won't install its own exception handlers above yours. And there might be some problems if the client process uses several worker threads that call functions from your DLL. In such case you would have to somehow install per-thread exception handlers too. How do I use crashrpt across process boundaries?Each process loads its own copy of CrashRpt.dll. It is difficult to imagine how you can share single loaded instance of CrashRpt.dll between several processes. Currently CrashRpt doesn't support such possibility. How do I use crashrpt in a multi-threaded application?You should use CrashRpt API functions to set exception handlers in the beginning of thread procedure of each of your worker threads. Do not forget to unset handlers in just before exiting the thread procedure. Does using crashrpt affect performance of my application?No, using CrashRpt doesn't affect performance of your application. CrashRpt doesn't perform any tasks in background and doesn't use additional memory. CrashRpt code is executed just when an exception is raised. Does using crashrpt make it easier for somebody to reverse engineer my code?No, actually not. In order to use CrashRpt, you enable program database generation in Release configuration (/Zi compiler flag and /DEBUG linker flag) and this generates .PDB file for your project. PDB files contain information which can be used to reverse engineer your code, however you typically store such information locally and do not distribute it with your software release package. So, using CrashRpt doesn't affect the difficulty of reverse engineering your code. Do crashrpt API functions support UNICODE character set? multi-byte character set (MBCS)?Yes, all CrashRpt functions using character set dependent arguments have two versions of function name (multi-byte versions are A-suffixed and wide character versions are W-suffixed). For example, crInstall() function has two versions of function name: crInstallA() and crInstallW(). Typically you use a character set independent mapping of function name in your program, for example use crInstall() that expands into crInstallW() if you use wide character set or into crInstallA() if you use multi byte character set. All my projects use multi-byte character set, so I changed it also in crashrpt library, but I experience some compilation problems. What do I do?It is not recommended to modify character set related settings in CrashRpt solution projects. CrashRpt should be always compiled using the UNICODE character set. In your multi-byte application, you can use A-suffixed functions from CrashRpt API. For example, use crInstallA(), crAddFile2A() and so on. Typically, you use a character-set-independent mapping of a function name, for example crInstall() name automatically expands into crInstallA() in a multi-byte program, and into crInstallW() in a wide-char prorgam. I need to modify some crashrpt configuration info (i.e. uPriorities) based on information collected after crInstall(). What is the best way ?Currently, there are no ways to modify the CrashRpt configuration info after calling crInstall(). I would recommend to hardcode the info you pass to crInstall() function, that means not reading it from an INI file or from another source. However, if you strongly wish to read crashrpt configuration info from an external file, call crInstall() after reading the info from that file. Simple file reading functionality is not likely to crash, I suppose. So the probability you miss a crash while reading the file is small. Why would I want to add a custom file (e.g., a log file) to the error report?If your application creates and maintains a log file where operations and errors are written, then such log file might be helpful for crash analysis and should be added to the error report. Why would I want to add a screen shot to the error report?It may be useful to have a screen shot of user's desktop at the moment of crash. This may help to see which button user clicked before the crash, and to see the desktop state. Sometimes it may be enough to see only the region of the desktop occupied by your application and not the rest of desktop. But there is one thing to take in account. By enabling screen shot capture, you should be careful about user's privacy. Some parts of the desktop screen shot may contain private or user identifying information: folder names, wallpapers, photos, text fragments and so on. That's why you should always provide a link to your Privacy Policy page describing what information you collect on crash and what purposes you use it for. For example, see PrivacyPolicyTemplate. Why would I want to add a custom text property to the crash description XML?One way to add application-defined info to the error report is adding a custom file. But sometimes you may want to extend the crash description XML file by adding a custom named literal property to the XML file. You can do this through the crAddProperty() function. For example, you may need to add the info about amount of free disk space on a specific disk drive at the moment of crash, or about the version of the graphics card driver installed on user's machine. We ship a software (game etc.) and certain crashes only happen on certain hardware. So we need some sort of functionality that gathers GPU/CPU/general hardware information upon crash report generation. What do we do?We introduced a function crAddProperty() specially for purposes of extending the crash description XML as you wish. You can also use the crAddFile2() function, which allows to add a user-defined file to the crash report. Why would I want to add a registry key dump to the crash report?If your application stores its settings as a registry key under HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE, you may want to add the dump of the key to the crash report. Since v.1.2.6, you can do this with the help of the crAddRegKey() function. I want to uniquely identify the installation by what the error reports are sent. What do I do?In CrashRpt v.1.2.1, we introduced a function crAddProperty() specially for purposes of extending the crash description XML as you wish. You can create the installation GUID in your program, store it in the registry or in a file and pass this GUID to the crAddProperty() function, so the named property will be added to the crashrpt.xml and you will be able to identify the installation and associate the bugs together. The following code example shows how to do this (code provided by tdev): // ... upon program start, check if GUID is not existing, if not create one:
GUID *g = new GUID();
CoCreateGuid(g);
char buf[120];
sprintf( buf, "%08x-%04x-%04x-%02x%02x-%02x%02x%02x%02x%02x%02x",
g->Data1, g->Data2, g->Data3, UINT(g->Data4[0]), UINT(g->Data4[1]), UINT(g->Data4[2]),
UINT(g->Data4[3]), UINT(g->Data4[4]), UINT(g->Data4[5]), UINT(g->Data4[6]), UINT(g->Data4[7]));
delete g;
std::string guid = std::string(buf);
//... later, add it to the crashreport:
crAddProperty("SystemGUID", guid);Why would I want to generate error report without crash?Sometimes it may be required to remotely debug some application logics error. Such an error, for example, infinite loop in a worker thread, may not cause program crash. To collect the information about such error, a software developer might provide an ability to generate error report manually on user demand, for example on a key combination press. My software's worker thread hangs up on users machine (but no crash happens). How do I debug the problem?To collect information about such error, you may provide an ability to generate error report manually, for example on a key combination press. When the key combination is pressed, generate error report manually using crGenerateErrorReport() function. I would like to force the user to enter a description of what happened just before the crash. What do I do?The user has an ability to enter the description of the problem in the Error Report dialog by clicking the link "Provide additional information (recommended)". However, my CrashRpt usage experience shows most users do not enter anything meaningful into this field. What do I do to save a local copy of an error report to my disk?Since v.1.2.2, you can use the 'Export...' button on the Error Report Details dialog to save a local copy of the error report. Does crashrpt support a non-GUI (silent) mode?Yes, since v.1.2.2, CrashRpt supports non-GUI mode. In the non-GUI mode, CrashRpt doesn't show any windows and sends the report without any user interaction. You can use such mode if your application is a service which has no GUI and usage of crash reporting is still desired. However, it is not recommended to use the non-GUI mode with regular GUI applications that create windows and interact with user. Does crashrpt support automatic restart of the application that crashes?Yes, since v.1.2.4, CrashRpt supports automatic application restart. But the restart is performed if two conditions are satisfied:
What is the recommended way of CRT linkage for crashrpt to work properly?It is recommended that you configure your project to use C runtime libraries (CRT) as Multi-threaded DLL (/MD) for Release configuration. This is the way recommended in MSDN. In the Solution Explorer window, right-click your project and open project Properties. Then choose Configuration Properties->C/C++->Code Generation. In the Runtime Library field, choose Multi-threaded DLL (/MD). This should be done for all projects in your solution to ensure all modules will share single CRT DLL. What do I do if modules of my application use different versions of CRT?Ensure that all modules that exist in your application use the same version of CRT. If some dependent modules were compiled using an older version of CRT, you should recompile them to ensure the single version or CRT DLL is used. For example, assume you use Visual Studio 2005 and CRT 8.0 linked as DLL, but some dependent module in your application was compiled in Visual Studio .NET 2003 and uses CRT 7.1 linked as DLL. In such situation a CRT error in the dependent module won't be intercepted by CrashRpt, because CrashRpt will intercept exceptions in CRT 8.0 only. However, CrashRpt will intercept SEH exceptions in all modules not depending on CRT version. What do I do if my project uses CRT as a static library?You can try to compile CrashRpt in Release LIB configuration. This configuration is experimental and may be removed in future versions. Actually, it is recommended that you configure your project to use C runtime libraries (CRT) as Multi-threaded DLL (/MD) for Release configuration. This is the way recommended in MSDN. And you may have troubles if CRT is used in different way. Below is explained why CRT DLL is better than the static LIB. Each module (EXE, DLL) in your project is linked to CRT (C runtime libraries). You may link CRT as multi-threaded static library or as multi-threaded dynamic link library (DLL). When you set CRT error handlers, such as pure call handler or invalid parameter handler, they will work for the CRT the caller module is linked to and won't intercept exceptions in different CRT modules (if exist). Several project modules may share single CRT DLL. This reduces to minimum the overall size of linked CRT code. And all exceptions within that CRT DLL can be handled at once. That's why multi-threaded CRT DLL is the recommended way of CRT linkage. If your project uses CRT as a static link library (which is not recommended to do) and you want to use some crash reporting functionality, you would have to compile the functionality as static a lib with /NODEFAULTLIB linker option. Then you would have to install CRT error handlers for EACH module that your program loads into its address space. What is Release LIB build configuration?The Release LIB configuration is an addition to the standard Debug and Release build configurations. Typically, you do not compile CrashRpt in this configuration. However, it may be useful if you use static CRT linkage. In the Release LIB configuration, the build generates CrashSender.exe executable file and CrashRptLIB.lib static library. In this configuration, CrashSender.exe and CrashRptLIB.lib use static linkage to CRT. Why should I enable Program Database (/Zi) compiler flag and Generate Debug Info (/DEBUG) linker flag?To get the most out of the crash minidump, the debugger needs your application's debug symbols. By default, Release builds don't generate debugging symbols. The crash minidump is unusable without the debugging symbols database (program database, PDB).
These steps should be done for all projects in your solution that support program database (EXE, DLL). Should I use rebase.exe to set preferred load address for modules of my application to be able read minidumps later?This is not necessary, because a minidump file itself contains the list of loaded modules of your application and their actual load addresses. Does crashrpt intercept exactly all exceptions that may occur in my program?CrashRpt intercepts all exceptions that are allowed to intercept by C runtime libraries (CRT). Note that some exceptions related to security can't be intercepted. Since CRT 8.0 you can't intercept security errors in your code. When buffer overrun is detected, CRT invokes Dr.Watson directly instead of calling unhandled exception filter. This is done because of security reasons and Microsoft doesn't plan to change this behavior. For more information, see this link. I cannot seem to catch the crash at all, the application just closes. No crash window courtesy of Windows, nothing at all. It just poof, closes. What do I do?The problem with silently disappearing application window may be related to stack overflow. When stack is overflown, the process doesn't have anough memory even for invoking crash handler. So it looks like a silent exit. The advice for you is to maintain a log file for your application. See this link for example of a logging functionality. The log file will help you to see where is the stack overflow happens. For example, if there is an infinite recusion in your code, you will see many log messages looking very similar. Can crashrpt intercept Boost's Exception ?CrashRpt intercepts structured Win32 exceptions (SEH exceptions), C run-time (CRT) exceptions and signals. Boost is built on top of CRT, so I beleive CrashRpt can intercept its exceptions. However, I didn't test CrashRpt with Boost. I'd like to be able to display a different message in the CrashSender.exe process for different types of crashes. Maybe also display a different icon, too. Can I do this?CrashRpt currently can't customize its behavior based on crash type. I'm not sure this feature would be widely used. Typical users do not have technical knowledge about memory. So, I'm not very encouraged to implement this. It seems my Visual Studio IDE interfers the exception: It does not let the exception run through to crashrpt. If I call the .exe from command line, everything works fine as expected. What do I do?Visual Studio IDE will always intercept exceptions in your software while debugging. There are no ways to fix this. If you need to test CrashRpt under IDE, use crGenerateErrorReport() function, it will generate a error report without raising an exception. How do I test if crashrpt intercepts exceptions in my application?When you install crash reporting support to your program, it is important to test if CrashRpt intercepts exceptions properly. Use crEmulateCrash() function to emulate an exceptional situation. Call this function in your main() function and in the thread procedure of each of your working threads. Do program optimizations (/O compiler switch) affect the minidump generation?Yes, if you enable optimizations, the stack trace recovered from minidump may be incomplete (e.g., see issue 25 ). However, this is not the reason to turn the optimizations off. Instead, you can manage some error log file which is not affected by optimizations. What is the minidump type? What minidump type should I use?The minidump type defines what information is contained in the minidump. The default minidump type is MinidumpNormal. However, the MinidumpNormal contains only essential info required to recover the stack traces for each thread. To recover the state of global variables, other minidump types should be used. For additional info, see the Effective Minidumps article. What files do I save locally before my software is released?When you are ready for a software release, the following steps must be performed to be able to properly read the error reports received from end-users:
These steps should be performed for exactly the same software build that you plan to release. If you rebuild the project after files are copied, you must copy the files again. When a crash report comes in, you use the release binaries, source code and debug symbols you saved, along with the minidump included in the crash report, to debug the crash. I use a packer for my EXE or DLL (e.g. PECompact, UPX and so on). How does this affect the way I read the generated minidump file?If you use a compression utility for reducing the size of your executable or DLL, be careful of the following. To read the minidump, you need to save a local copy of the uncompressed EXE (DLL) file and a PDB file generated for that EXE (DLL). You also need to have the source code that you used when building the EXE (DLL). These should be enough to read the minidump generated by the compressed version of your EXE. If you use PECompact compression utility, be sure you turn the debug info stripping off by specifying the /StripDebug:No option. By default, PECompact removes (strips) the debugging information from the executable file. I sign my EXE with a digital certificate (Authenticode). How does this affect the way I read the generated minidump file?If you use an Authenticode utility for signing your executable, be careful of the following. In order to read the minidump, you need to save a local copy of the unsigned EXE file and a PDB file generated for that EXE. You also need to have the source code that you used when building the EXE. These should be enough to read the minidump generated by the signed version of your EXE. I need to edit a resource embedded into my compiled EXE (DLL) binary (e.g. I need to upgrade its version). How this affects the way I read the generated minidump file?If you edit resources in your compiled binaries, be careful of the following. In order to read the minidump, you need to save a local copy of the original (unmodified) EXE (DLL) file and a PDB file generated for that EXE (DLL). You also need to have the source code that you used when building the EXE (DLL). These should be enough to read the minidump generated by the resource-modified version of your EXE (DLL). I use IncrediBuild for compiling my project. Does crashrpt work with PDB files generated such way?Yes, CrashRpt works with PDB files generated with help of IncrediBuild. IncrediBuild is a platform for accelerating Visual C++ builds through by distributing the build processes over local area network. What files should I never distribute with my software release package?
What crashrpt files do I distribute with my software release package?The list of files you should distribute depends on your version of CrashRpt. Not depending on version, it is recommended that you distribute the following files with your software release:
It is recommended that you place these files to the directory where your application executable file is located. The CrashRpt.dll and CrashSender.exe are core CrashRpt modules. dbghelp.dll (Microsoft Debug Help Library) is the module CrashRpt depends on. crashrpt_lang.ini is the language file. What version of dbghelp.dll should I distribute?You can distribute the version of dbghelp.dll that is shipped with CrashRpt archive. Or you can distribute dbghelp.dll from Debugging Tools for Windows. I know that dbghelp.dll is shipped with Windows. Why should I distribute it?It is recommended that you distribute dbghelp.dll with your software, because some end-user machines may not have dbghelp.dll installed or dbghelp.dll's version may be different on different user machines. You may ignore distribution of dbghelp.dll at your own risk. Even though dbghelp.dll is included in versions of Windows starting from XP, this is rarely the most current version of DbgHelp available. Furthermore, the version of DbgHelp that ships in Windows has reduced functionality from the other releases. I use C run-time libraries (CRT) as a multithreaded DLL. What CRT files should I distribute with my software?First of all, determine what DLL modules your application depends on. You can do this with the help of the Dependency Walker (depends.exe) tool. Open your executable file with the depends.exe to see what CRT modules it depends on. Typically these modules are msvcrXX.dll and msvcpXX.dll, where XX is the version number of your Visual Studio (for example, Visual Studio 2005 has version number 80). Next, you need to determine the exact version of CRT libraries you use. Microsoft usually upgrades CRT version when releasing service packs and hot fixes for Visual Studio, so this step is very important. To determine the version of your CRT, do the following. In your Visual Studio window, click menu File->Open and open your executable module to view its embedded resources. In appeared window, click RT_MANIFEST folder to see the embedded manifest XML file. The version of CRT is defined by the version attribute. An example CRT manifest is presented below: <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<dependency>
<dependentAssembly>
<assemblyIdentity type="win32" name="Microsoft.VC80.CRT" version="8.0.50608.0"
processorArchitecture="x86" publicKeyToken="1fc8b3b9a1e18e3b"></assemblyIdentity>
</dependentAssembly>
</dependency>
</assembly>Next you should choose how to distribute the CRT files. There are two ways: either by installing a Visual C++ redistributable package or by installing the DLLs to application local folder (an application local folder is a folder that contains an executable application file). Below these two alternatives are described. a. You can download a Visual C++ Redistributable package from the Microsoft Download Center. There are different packages for x86 and x64 architectures, choose the correct one. Also ensure the package has exactly the same version that your CRT manifest has. If version doesn't match, search again for the correct redistributable package. When the correct package is downloaded, you can include it into your application installer and install it with your software. b. You can copy CRT DLL files and Microsoft.VCXX.CRT.manifest file to your application folder, where XX is the version number. This is called a private installation, because these CRT DLLs won't be available to other applications. This way may also reduce the size of your installer, because CRT DLLs usually take less space than a redistributable package. You can take the correct CRT DLL files from redist subfolder of your Visual Studio folder or from the Visual C++ redistributable package (it is installed to `C:\WINDOWS\WinSxS directory). For additional information, see these links: Redistributing Visual C++ Files, Determining Which DLLs to Redistribute, Troubleshooting C/C++ Isolated Applications and Side-by-side Assemblies, Redistributing an Application and Binding It to Specific Libraries. My application doesn't start because of error message 'The application configuration is incorrect'. What do I do?This error typically means your application can't load the correct C run-time libraries (CRT). To determine what DLL modules your application depends on are missing, use the Dependency Walker (depends.exe) tool. Open your executable file with the depends.exe to see what CRT modules it depends on, and which ones are missing. Typically these modules are msvcrXX.dll and msvcpXX.dll, where XX is the version number of your Visual Studio (for example, Visual Studio 2005 has version number 80). You should install CRT libraries either by running a Visual C++ Redistributable Package or by copying CRT DLL files and Microsoft.VCXX.CRT.manifest file to your application folder. Also ensure the version and architecture of the CRT files you install is correct. I do not like that I should distribute all these DLLs. Can I compile them all as static libs?No, this is impossible. Architecture of CrashRpt requires two modules: CrashRpt.dll and CrashSender.exe. You may ignore distribution of dbghelp.dll, but a end-user's operating system may not have dbghelp.dll installed. So, you have to distribute all these binaries. What is an error report?An error report refers to a collection of files intended to help the developer diagnose the cause of a crash. The error report contains crash minidump file (crashdump.dmp), which has operating system version, processor type, CPU registers state and local variables and stack trace for each execution thread. The minidump can be used on developer's side to determine the reason of the crash and try to fix the problem. In addition, CrashRpt generates XML crash description file. The file contains various complementary information that might be useful for crash analysis. Crash report can optionally contain application-defined files, for example, application log files, included into crash report via the crash callback. How does crashrpt create an error report when crash occurs?When crash occurs, CrashRpt runs another process named CrashSender.exe. The parent process is then terminated. If you generate error report manually, the parent process is not terminated. CrashRpt saves the error report files to LOCAL_APP_DATA\CrashRpt\UnsentErrorReports\AppName_AppVersion folder. What is the Privacy Policy? Where can I find a template for the Privacy Policy?Since v.1.1.2, you can use a privacy policy which describes what user information your software collects on crash. You provide the URL of your privacy policy document, which you may publish on your web site or distribute with your software. If you need a template you may use this one: PrivacyPolicyTemplate. I don't want to provide the Privacy Policy. What do I do?Just set the CR_INSTALL_INFO::pszPrivacyPolicyURL parameter with NULL. This will hide the Privacy Policy link. How does crashrpt deliver me error reports from end users?CrashRpt sends error reports back to your software support team using any of the following ways:
If one of these ways fails, CrashRpt tries others in turn. You can define the preferred order of ways used to send reports. Are there any crash report size limitations?Yes, they are. Although CrashRpt supports large error reports, the crash report should be as small as possible. If you use E-mail for error reports delivery, there may be mail size limits on the SMTP server. If the error report is larger than the limit, it is possible that the error report will be rejected. If you use HTTP (or HTTPS) for error report delivery, there may also be POST data size limits on the web-server. You should check your web-server settings to figure out the maximum error report size. How does crashrpt send me error reports using HTTP (or HTTPS) connection?Many software products have web sites on the Internet. Such web servers typically have some scripting engine enabled, for example PHP and so on. CrashRpt can establish HTTP (or HTTPS) connection to the server and send an error report as a script parameter. This way is not affected by firewalls, because most firewalls have HTTP port 80 open. However, this way requires a server with some script that you create and deploy yourself. How does crashrpt send me error reports using SMTP connection?CrashRpt has a simple built-in SMTP client. It can try to send an error report to recipient using SMTP connection without any user interaction. The error report is sent as an E-mail message with attachments. This way CrashSender.exe creates SMTP connection with a mail server (port 25) and sends crash reports without additional user interaction. There are two SMTP servers that can be used to relay email: sender's mailbox and recipient's mailbox. If user provides his/her email address, CrashRpt tries to use the address' MX domain record to determine local SMTP server name and relay the email message to that server. If user doesn't provide his/her email address, CrashRpt tries to send the email directly to recipient using the MX record of recipient's domain. Many SMTP servers may block direct access to them to avoid spam. This way won't work when firewall is enabled and port 25 is closed for outbound traffic (SMTP client won't be able to even connect). Since many organizations and even home users have firewalls that silently block port 25, this way fails for many users. How does crashrpt send me error reports using Simple MAPI programming interface?CrashRpt can use the default E-mail client, for example, Mozilla Thunderbird, to send the error report as email. The error report is sent as E-mail multi-part message. This requires some user interaction. This way has the lowest priority by default. Mircosoft declared Simple MAPI deprecated and removed its support from recent versions of Mircosoft Outlook. What does crashrpt do when all attempts to send error report fail?This depends on how you have configured CrashRpt. CrashRpt can queue error reports for later submission (by default the report files are stored in LOCAL_APP_DATA\CrashRpt\UnsentErrorReports\AppName_AppVersion folder. Alternatively, if queue is disabled, CrashRpt erases the error report files when delivery fails. What do I do when I start receiving error reports after software release?After software release, if CrashRpt support is enabled in your software, sooner or later you start receiving crash reports. Count of received crash reports may depend on robustness of your software to various errors and on how much your software popular. So it's nothing unusual if you receive hundreds of error reports a day. If there are many incoming error reports, you can monitor and analyze them for the first few days after release, and prepare a hot fix release. The purpose of an error report is to help you determine the reason of the problem and try to fix it. The keyword is 'try', because in most cases you can't fix crash reports as you usually do with normal bugs. You usually can't reproduce the error on your machine, so you can't guarantee it is fixed. So the only way to check is to make fixes in parts of code that could cause the crash most probably and to release a new version of software. The normal scenario is that your software becomes more and more stable with each release and less and less error reports are received. How do I check integrity of a received error report?You may calculate MD5 hash for your error report and compare it with the MD5 hash that is attached to the error report. When you receive error reports using HTTP (or HTTPS) connection, the MD5 hash is passed to the server-side script through the 'md5' parameter. Since CrashRpt v1.1.1., when you receive error reports using email, the MD5 hash is attached to the email. How do I use an error report for debugging a crash?A crash report is a ZIP file containing several files, such as crash minidump (crashdump.dmp), crash description XML (crashrpt.xml), and optional application-specific files, e.g. application log files. The crash description is an XML file that contains the basic information about the crash, for example exception type, operating system name, application name and version. The crash dump file is a collection of memory ranges, CPU register states, the call stack and local variables for each execution thread, the list of loaded and unloaded modules and system information. You can open the minidump in your Visual Studio or in WinDbg program and see the place of your code where exception had occurred. Does crashrpt support bidirectional communication (the user gets an email with updates on his issue)?We currently do not support bidirectional communication, because this would require some complex server-side functionality. I want the user to directly send me the stack trace, w/o me need to postprocess anything with that on my side. Does crashrpt support this somehow?No, CrashRpt can't generate readable stack traces on the side of the user. It supports developer-side error report processing. User-side error report processing would require you to distribute your PDB files with your software. Typically you do not distribute PDB files, because it makes someone easier to reverse-engineer your program. Our approach is developer-side post-processing. This means users send you error reports and you post-process them on your machine, where PDB files, binaries and source code is located. How do I open a crash description XML file?You can use notepad, another text editor or your web browser. What is crash GUID?A crash description XML contains CrashGUID tag. The crash GUID is an unique identifier that is assigned to the error report. GUIDs are generated using special algorithm which guarantees very low probability of generating the same GUID twice, even on different user machines. The crash GUID can be used, for example, as the primary key if you plan to store crash reports in a database. How do I determine the name and version of the application that generated the error report?The crash description XML file contains AppName and AppVersion tags. You use them to determine what application sent you the report. You are typically interested in analyzing error reports from the latest version of your software and ignore reports from older versions. How do I determine the OS version for the error report?A crash description XML contains OperatingSystem tag which is the friendly name of end user's operating system, including name, build number and service pack. It is useful information because many errors are OS-specific. What is an ExceptionType tag in the crash description XML?The exception type shows what exception handler caught the exception. For example, type 0 means that the SEH exception was intercepted by the unhandled exception filter set with SetUnhandledExceptionFilter() function. The exception type can be used to divide exceptions in some categories. See the documentation for more information about exception type. How do I open a crash minidump file (.DMP)?Double-click on the minidump file name. This should open it using an associated program (for example, Visual Studio). When minidump file is loaded in Visual Studio, press F5 to run it. If debug symbols are loaded successfully, you are now able to see the place in your source code where exception had occurred. Alternatively, you can open the minidump file using WinDbg program from Microsoft Debugging Tools. It is freely distributed. Can I open crash minidumps with WinDbg?Yes, you can open crash minidumps (.DMP files) with WinDbg program that is a part of Debugging Tools for Windows. How do I identify if the symbol files fit to a certain executable?Symbol files are identified by timestamps (in older versions of PDB) or by GUIDs (in newer versions of PDB). You do not need to identify matching PDB yourself. Symbol handler will do that for you. Just specify the list of folders to search in and the symbol handler will look for correct PDB files itself. If I've saved all the source code, should building from the source recreate the correct PDBs?No, the recreated PDB files will not be the same as the original ones. The recreated PDB files won't have matching time stamp (or GUID). The building environment may also be different, so generated binaries may be different. The recommended way is to save the original PDB files (that were produced when building the project), binary files (EXE and DLL) along with the source code. I open minidump, but symbols are not loaded. What do I do?Sometimes you can't determine the location of the crash and the error message is displayed 'No symbols loaded for any stack frame'. This may be because of the following reasons.
How do I automate crash report processing?Automating the error report processing becomes the critical task when you receive a lot of error reports after software release. Among hundreds of reports there may be only several different problems, while others just duplicate the information about these problems. Opening so many reports manually in Visual Studio or in WinDbg and analyzing their content may become boring and take a lot of time. Since v1.2.0, CrashRpt provides a way for automating the report processing. The command line tool named crprober.exe is introduced for processing error report files and outputting the results to a text file or to terminal. The CrashRptProbe API is introduced to provide base crash report processing services to your custom error report processing applications. How do I use the crprober.exe tool?Since v1.2.0, CrashRpt provides a tool named crprober.exe that can be used for automating crash report processing. To run the tool, go to bin directory and type crprober.exe in the command line. The tool can be used to open error report files generated by any version of CrashRpt. However it works the best with reports created by version 1.1 and higher. For usage examples, please see the documentation. How do I calculate some statistics about processed error reports?You can write some C++ program or for example Python script that would parse output text files and calculate the desired statistics. For example, see the SampleProcessingPythonScript provided by RoRThom. Is it possible to use crprober under Linux? with Wine?I would not recommend to use crprober.exe in an operating system other than Windows because of license dbghelp.dll uses. The crprober.exe tool depends on dbghelp.dll (Microsoft Debug Help Library), which is licensed using Microsoft Software License Terms for Microsoft Debugging Tools for Windows. This license doesn't allow to distribute dbghelp.dll "to run on a platform other than the Windows platform". What is crashrptprobe API?The CrashRptProbe API is the application programming interface for processing error reports generated by crashrpt. The API includes several functions you can use in your own error report processing tool. The API is used internally by the crprober.exe tool. The error report processing functionality is encapsulated inside of CrashRptProbe.dll. Internally CrashRptProbe.dll uses functions provided by dbghelp.dll (Microsoft Debug Help Library) for loading the minidump file contained in the report. What .h file should I include and what .lib file should I link in order to use CrashRptProbe API?You should include CrashRptProbe.h and link CrashRptProbe.lib. | |||||||||||||||||||||||||||||||||||||||||||||
► Sign in to add a comment