How to: Configure Microsoft Error Reporting

Microsoft Corporation

December 2006

Applies to: Microsoft Error Reporting

Summary: Microsoft Error Reporting is a client application for reporting crashes and errors to Microsoft. It is designed for use with applications running on operating systems earlier than Windows Vista, which instead offers this functionality through the WER API. (32 printed pages)

Contents

• About Microsoft Error Reporting

• Scenarios

• Diagnosing Reporting Problems

• Microsoft Error Reporting Installed Files

• Registering an Event Log Source

• Redistributing a Shared MSI

• Reporting Modes

• About Manifest Mode

• Queued Reporting

• Generic Reporting

• Generic Manifest Mode

• Generic Shared Memory Mode

• Sanitizing Strings

• Using Behavior Flags

• Examples of MER User Interface

• Manifest Mode Crash Reporting

• About Customizing Queued Reporting

• Registry Settings

• Group Policy Template

• Using Microsoft Error Reporting on Windows Vista and Later Operating Systems

• Managed Code

• Conclusion

• Additional Resources

About Microsoft Error Reporting

Microsoft Error Reporting enables independent software vendors (ISVs) to track and address errors relating to the operating system, Microsoft Windows components, and applications. This service gives administrators and users the opportunity to send data about errors to Microsoft and to receive information about errors. ISVs can use Microsoft Error Reporting as a problem-solving tool to address customer problems in a timely manner and to help improve the quality of Microsoft products.

Requirements for Microsoft Error Reporting

To integrate Microsoft Error Reporting, you must redistribute client binaries. You cannot assume that Microsoft Error Reporting is already installed, because it is not included with any operating system or service pack.

You must use Windows Installer to install Microsoft Error Reporting. If your application does not use Windows Installer, you must create an MSI (Microsoft Windows Installer) file for Microsoft Error Reporting, which your setup script executes as a separate process.

You must acquire the Shared MSI and link it to your own installation. Attempting to mimic our installation logic with another form of setup is not permitted, because it causes significant issues with DLLs and breaks other applications that use the shared binaries.

Compatible Operating Systems

Microsoft Error Reporting requires Microsoft Windows 2000 Service Pack 3 (SP3), Microsoft Windows XP, or Microsoft Windows Server 2003. It does not run on Microsoft Windows NT 3.5, Windows NT 4.0, Microsoft Windows 95, Microsoft Windows 98, Microsoft Windows 98 SE, or Microsoft Windows ME.

ISVs

Independent software vendors interested in error reporting may use the Windows Error Reporting Partner Analysis (WERPA) site to request crash data from Windows XP.

For more information about WERPA, visit Windows Quality Online Services.

For more information about accessing the data sent to Microsoft via Microsoft Error Reporting, visit Winqual Help.

Scenarios

You can customize Microsoft Error Reporting to report in many different modes. Use the following general scenarios to help you determine how you want to use Microsoft Error Reporting.

Using Microsoft Error Reporting with Client Applications

In most cases, the default Windows Error Reporting implementations in Windows XP and Windows Server 2003 can handle client application crashes. If your application needs specialized behavior, such as offering document recovery, you need to integrate Microsoft Error Reporting.

Using Microsoft Error Reporting with Server Applications

Server applications have different requirements than client applications. In general, server applications:

• Should not show any user interface (UI) when a crash or error occurs, because there might be no user logged on to see the dialog box.

• Should apply group policy on a per-computer basis.

• Should allow administrators on the computer to handle error reporting.

If your requirements match these requirements, then we recommend that you silently queue all of your error reports. When an administrator logs on at a later time, the queued reporting dialog box displays a list of reports and asks the administrator to send them to Microsoft.

To configure Microsoft Error Reporting this way, you need to set the following behavior flags:

• fDwrIgnoreHKCU

• fDwrForceToAdminQueue

• fDwrForceOfflineMode

• fDwuNoEventUI

Memory-intensive applications may choose not to snap memory heaps at the time of a crash, because it might degrade performance. If you are certain that you never need heap for debugging, then you can disable it with this flag:

fDwrNoHeapCollection

If you have special requirements for the mini dump, Microsoft Error Reporting allows you to customize it. For more information, see Generating Custom Mini Dumps in this article.

About Silent Reporting

Silent reporting, that is, reporting without a user's consent, is dangerous because we must respect our customers' privacy. Therefore, silent reporting is not recommended for Microsoft Error Reporting. For more information, contact werpasup@microsoft.com.

About Unattended Servers

An administrator might not log on to an unattended server with any regularity. Ideally, errors from an unattended server would be reported silently and automatically. This scenario is difficult to configure "out of the box" because the best way is to configure with a Corporate Error Reporting (CER) server.

If this scenario is important to your customers, we recommend that you provide documentation to help them configure CER with automatic reporting. The two most important polices are:

• Local error-reporting file path

• Queue bypass and send all reports

For more information about group policy, see Group Policy Template in this article.

For more information about CER, see Microsoft System Center Operations Manager Home.

About Non-Fatal Errors

There is a wide variety of uses for Microsoft Error Reporting beyond crashes. For more information about reporting errors other than crashes (for example, setup failures), see Generic Reporting in this document.

Diagnosing Reporting Problems

This section helps you diagnose reporting problems.

Enabling Diagnostic Logging

Diagnostic logging is much richer in Microsoft Error Reporting when compared with Windows Error Reporting. When you are getting started with integration, the log can save you time. For example, the log records Stage1 and Stage2 URLs, requests from the server, the bucket ID, and the full response URL.

The log is written to %TEMP%\Dw.log. Each new Microsoft Error Reporting event is appended to the log.

You can enable logging with this registry setting:

Key: HKEY_CURRENT_USER\Software\Microsoft\PCHealth\ErrorReporting\DW

Value: DWVerboseLog=1

Return Codes

The following table provides a description of the return codes provided by Microsoft Error Reporting.

Table 1. Microsoft Error Reporting return codes

Code	Description
0	Success. Microsoft Error Reporting exited normally. This includes the user clicking Don't Send or Cancel, or the server not requesting a CAB file.
1	Failure. This includes any failure, including inability to connect to a server, or an invalid manifest file.
16	User clicked Debug in Manifest mode. (In Manifest mode, the Debug button is shown if the DwuManifestDebug flag is set. In Shared Memory mode, Debug is shown if msoctdsOffer includes msoctdsDebug, or if there is a debugger registered in the AeDebug key and fDweIgnoreAeDebug is not set. If the user clicks Debug in Shared Memory mode, Microsoft Error Reporting sets msoctdsDebug in the msoctdsResult field in the shared memory block and returns 1).

Microsoft Error Reporting Installed Files

The following table shows the installed files included with Microsoft Error Reporting.

Table 2. Microsoft Error Reporting included installed files

File name	Installation Location	Comments
Dw20.exe	%CommonProgramFiles% \Microsoft Shared\DW	Primary executable.
Dwtrig20.exe	%CommonProgramFiles% \Microsoft Shared\DW	Subscriber for System Event Notification Service (SENS) notifications.
Dwdcw20.dll	%CommonProgramFiles% \Microsoft Shared\DW	Tells Disk Cleanup Wizard what can be deleted.
Dwintl20.dll	%CommonProgramFiles% \Microsoft Shared\DW\LCID	Resource file for UI strings.
Aer_1033.adm	%SystemRoot%\inf	Policy template (English).

Registering an Event Log Source

Your installation needs to register an event log source for your application. Otherwise, there will be malformed events in the event viewer—events that are not easily readable by end users.

In this key:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Eventlog\Application\SOURCE

You must create two named values:

• EventMessageFile (SZ): full path to Dw20.exe

• TypesSupported (DWORD): 7

Redistributing a Shared MSI

The Shared MSI has no UI and includes all languages in one package. You must chain it to your own setup program by running MSiexec.exe and passing in the APPGUID Property property.

MSI Components

You must set this bit in the Attributes field of the Component table:

msidbComponentAttributesLocalOnly

Feature

The Shared MSI component has a single, childless feature, which incorporates existing Microsoft Error Reporting merge modules.

The feature's components include non-localized binaries (Dw20.exe, Dwtrig20.exe) and localized resources (Dwintl20.dll, Aer_LCID.dll) for each language.

You must set these bits in the Attributes field of the Feature table:

msidbFeatureAttributesDisallowAdvertise 
msidbFeatureAttributesUIDisallowAbsent 

The feature and component attributes ensure that Microsoft Error Reporting cannot be advertised or run from source. It is always installed locally.

APPGUID Property

APPGUID is a public property that is passed to the Microsoft Error Reporting MSI at the command prompt at installation. The value of APPGUID is a Windows Installer ProductCode GUID for the product that is installing the Microsoft Error Reporting MSI. There is no default value.

To install the Microsoft Error Reporting MSI at the command prompt, type:

msiexec.exe /i path\dw20.msi APPGUID={GUID}

or this, which is equivalent:

msiexec.exe /i path\dw20.msi APPGUID={GUID} ADDLOCAL=ALL

APPGUID is required for installation and reinstallation. If APPGUID is not specified, the MSI closes without taking any action.

Uninstalling the Microsoft Error Reporting MSI looks like this:

msiexec.exe /x {DW20 ProdCode GUID}

APPGUID is not required to uninstall.

Implementing Refcounting

Refcounting counts the number of references to Microsoft Error Reporting so that it is removed on uninstall only if no other programs require it. This is performed at the ProductCode level, rather than the component level. Windows Installer does not provide this functionality, so it must be built into the MSI with custom actions.

Install

At installation, a custom action writes APPGUID into the registry. The registry data type is REG_DWORD. The value is always 1.

Key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PCHealth\ErrorReporting\DW\Products

Name:

{ProductCode GUID}

Value:

1

Reinstall

Reinstall acts the same as install: APPGUID is written to the registry. If the registry value is already present, the custom action overwrites it.

Uninstall

Uninstall does not require the application to pass APPGUID.

Reporting Modes

This section reviews the different reporting modes.

About Shared Memory Mode

Shared Memory mode is used primarily for reporting crashes. In Shared Memory mode, Microsoft Error Reporting records a mini dump by default.

Launching Microsoft Error Reporting in Shared Memory Mode

Microsoft Error Reporting is launched by calling CreateProcess() and passing in -x for Shared Memory mode and -s with a handle to your shared memory block. For sample code, contact werpasup@microsoft.com.

User Mode Exceptions

User mode exceptions have eight bucket parameters:

• szAppName

• szAppVer

• szAppStamp

• szModName

• szModVer

• szModStamp

• fDebug

• offset

szAppStamp and szModStamp are time/date stamps, added because sometimes a binary is updated without changing the version resource string. fDebug is from the file version resource (be sure to include VS_FF_DEBUG in the VS_FIXEDFILEINFO block).

About Generic Shared Memory Mode

Microsoft Error Reporting supports generic reporting in Shared Memory mode. With generic reporting, you are not constrained to use the eight parameters that define a crash bucket. You may specify up to ten parameters.

You must contact werpasup@microsoft.com to define a unique event type before you begin reporting. For more information, see Generic Reporting in this article.

Generic reporting is supported in Manifest mode and Shared Memory mode. Use Shared Memory mode if you want Microsoft Error Reporting to snap a mini dump at the time of the event.

Generating Custom Mini Dumps

Microsoft Error Reporting supports custom mini dump generation by passing flags through to the mini dump library when it makes a call to the MiniDumpWriteDump function. You can specify the mini dump type, flags for the current thread and all other threads, flags for a specific (preferred) module, and flags for all other loaded modules.

For more information, see MINIDUMP_TYPE. Also see THREAD_WRITE_FLAGS and MODULE_WRITE_FLAGS.

The following code is the section of header that defines the shared memory block structure for custom mini dumps.

typedef struct _CustomMinidumpBlock
{
    BOOL  fCustomMinidump;
    DWORD dwMinidumpType;
    BOOL  fOnlyThisThread;
    DWORD dwThisThreadFlags;
    DWORD dwOtherThreadFlags;
    DWORD dwThisThreadExFlags;
    DWORD dwOtherThreadExFlags;
    DWORD dwPreferredModuleFlags;
    DWORD dwOtherModuleFlags;
} CustomMinidumpBlock;

About Manifest Mode

In contrast to Shared Memory mode, Manifest mode enables you to start more than one process at a time without waiting. You write out a manifest with reporting instructions and execute Microsoft Error Reporting. There is no conversation between the application and Microsoft Error Reporting other than a simple return code.

In Manifest mode, Microsoft Error Reporting cannot snap a mini dump. If you need a mini dump, you probably want to use Shared Memory mode (rather than snap the mini dump yourself).

Launching Microsoft Error Reporting

Microsoft Error Reporting is launched by calling CreateProcess() and passing a command line of -d with a path to your manifest file. From a command prompt, type:

dw20.exe -d path\file name

About the Manifest File Format

The manifest file must be a Unicode text file with a blank first line. If the manifest does not contain the required elements, Microsoft Error Reporting does not attempt to report.

Required Elements for a Manifest

For a manifest to be valid, it must contain the following elements. The UI strings, flags, and other manifest elements are discussed elsewhere in this article. This section is included so that you can do a quick check to see if you are missing a required element.

Table 5. Elements required for a valid manifest

Element	Description	String
Version	The version of the manifest format. There has been only one version so far: 0x00020000	This is decimal 131072. The manifest must contain Version=131072.
General_AppName	Title bar contents	The manifest must contain General_AppName=MyAppName.
FilesToKeep or FilesToDelete	Indicates what to put in the CAB for Microsoft Error Reporting	The manifest must contain a FilesToKeep or FilesToDelete Line: FilesToKeep=path\file name or FilesToDelete=path\file name.
Bucket Parameters	Indicates how to bucket your report for Microsoft Error Reporting	The simplest way to do this is with a generic event and at least one parameter value (for information, see Generic Reporting in this article). For example: EventType=MyEventType P1=MyParameterValue

The following code is a sample of a very simple manifest that contains all of the required elements.

Version=131072
General_AppName=SampleApp
FilesToKeep=c:\Directory\file name
EventType=Type
P1=Parameter Value

About Behavior Flags

There are four bit fields for behavior flags: UIFlags, ReportingFlags, LoggingFlags, and ExceptionModeFlags. (For a list of flags, see the list of Using Behavior Flags in this article). The flags have an f, r, l, or e in the name to help you remember how they are grouped. For example, fDwuNoEventUI is a UI flag.

To set flag values, add a line to your manifest with the appropriate bit field name and value for the flags you want to set. For example, to set the fDwrIgnoreHKCU (0x00000002) and fDwrForceOfflineMode (0x00000008) flags, add this line to your manifest:

ReportingFlags=10

Queued Reporting

Reports can be queued for three reasons: the user is offline, the application chooses to queue the report, or the logged-on user does not have sufficient privileges to view the report. The following table provides a description for each queue mode.

Table 6. Queue descriptions

Queue	Description
Offline Mode	Microsoft Error Reporting supports offline reporting. When the crash or other event occurs, Microsoft Error Reporting calls the InternetGetConnectedState() application programming interface (API). If the user is not connected, the main dialog box is changed slightly to inform the user. If the user chooses the option to send the report later, the report is queued for delayed reporting.
Application Choice	If you prefer to queue a report (or all of your application's reports), you can force the report to be sent to the queue with no option for immediate reporting. For example, server applications should try to avoid stopping the application with an error dialog box at the time of the exception, so they might choose to silently queue all reports. To send a report to the queue, set the fDwrForceOfflineMode flag. Note If you do not suppress UI at the time of the event, the user sees the main dialog box, just like in the offline case. In general, we recommend using the fDwrForceOfflineMode and fDwuNoEventUI flags together (otherwise, a connected user might be confused), but there might be special cases where you suspect that InternetGetConnectedState does not return an accurate value.
Unprivileged User	If the context of the application is different from the context of the user, then, for security reasons, Microsoft Error Reporting cannot show the user the report UI. For example, if a system service crashes and the logged-on user is not an administrator, Microsoft Error Reporting must suppress the UI at the time of the event and queue the report. Note You can force reports to be queued until an administrator logs on, by setting the fDwrForceToAdminQueue flag.

Queue Types

There are two distinct types of queues, plus the administrator version of the signoff queue.

Table 7. Queue types

Queue Type	Description
Regular Queue	The regular queue is used for reports that the user has seen before. For example, if an application crashes while the user is offline, and the user chooses to send the report later, the report is sent to the regular queue. Regular queue CAB filess and instruction files are stored in this folder: %USERPROFILE%\Local Settings\Application Data\PCHealth\ErrorRep\QRegular
Signoff Queue	The signoff queue is used for reports that the user has not seen before. Ship assert reports are sent to the signoff queue. Signoff queue CAB files and instruction files are stored in this folder: %USERPROFILE%\Local Settings\Application Data\PCHealth\ErrorRep\QSignoff
Administrator Queues	The admin queues are used for reports that unprivileged users should not be able to access. They can be thought of as "any administrator" queues because they are not associated with a particular user, but can be reported by the first user who logs on with administrator privileges. If your application runs with elevated privileges, you should suppress UI at the time of the exception and send reports to the administrator signoff queue. Set the fDwrForceToAdminQueue and fDwuNoEventUI flags. There is an administrator signoff queue. There is no administrator regular queue, because if UI is shown to a user who has administrator privileges at the time of the event, the report is either sent to Microsoft immediately or put in that user's regular queue. Administrator queue CAB files and instruction files are stored in this folder: %SYSTEMROOT%\PCHEALTH\ErrorRep\QSignoff Access to the folder is controlled via an access control list (ACL) such that any user can write to the folder but only administrators can read from it.
Headless Queue	The headless queue is used for reports that are reported silently.  This mode requires the integrator to provide UI for the user to opt-in.  We do not usually recommend that you use headless mode, and we ask that you contact us before proceeding. Headless queue CAB files and instruction files are stored in this folder: %USERPROFILE%\Local Settings\Application Data\PCHealth\ErrorRep\QHeadles

Reporting from a Queue

Reporting from a queue is very similar to reporting at the time of the event. The Microsoft Error Reporting client goes through the same four-stage conversation with the Watson servers, or sends the reports to a Corporate Error Reporting file tree.

Table 8. Reporting descriptions

Reporting	Description
Second-Level Data	When second-level data is requested for a bucket, it is collected when reporting from the queue. (It is not collected at the time of the event because it is not known if there is a request for second-level data until it is reported.) The exception to this rule is the memory dump (heap). It is not possible to snap a memory dump after the event. Therefore, heap is always snapped and stored in the queue. If the server requests heap, it is sent. If the server does not request heap, it is removed from the CAB prior to reporting. Collection of user documents is not supported in Queued Reporting mode. Queuing reports creates the possibility that second-level data will be stale. Registry data, for example, might change between the time of the event and the time the report is sent.
Selecting a Queue	If more than one queue has reports, Microsoft Error Reporting randomly selects one queue (regular or signoff) and sends the reports from that queue. If there are reports in the administrator queue, they are moved to the queue of the user who is reporting (that user must be an administrator, of course).
Size of Queues	Each queue holds a maximum of 50 reports (50 is the default; the maximum number can be changed by using system policy). When a queue is full, additional reports are not queued. Note The first 50 reports in the queue are kept, not the last 50.
Pester Throttle	The Pester Throttle prevents the user from being constantly harassed by queued reporting dialog boxes. Each time a queued reporting dialog box is displayed to the user, the date and time is recorded in the registry. Before a queued dialog box is displayed again, the registry is checked to determine whether at least three days have passed. If fewer than three days have passed, the queued reporting dialog box is not displayed.

WatsonPersistentRunKey

To trigger queued reporting at each startup, set the following property:

WatsonPersistentRunKey = 1

This does not override the Pester Throttle, but it causes Dwtrig20.exe to run, evaluates the queues, and reports if appropriate. See also Queued Reporting in this article.

Reporting Triggers

There are several ways to trigger queued reporting. When Microsoft Error Reporting is triggered to begin reporting, Microsoft Error Reporting displays a queue reporting dialog box only if the user is connected, there are reports available to the current user, and the Pester Throttle does not prevent reporting. If one or more of these conditions is not met, Microsoft Error Reporting closes.

Table 9. Reporting trigger descriptions

Reporting trigger	Description
System Event Notification Service	When a report is queued, Microsoft Error Reporting registers with the System Event Notification Service (SENS). SENS notifies Microsoft Error Reporting when the user connects. Microsoft Error Reporting waits four minutes after the SENS notification and then starts reporting from the queue. Note There are cases where registering for SENS is unreliable and Microsoft Error Reporting does not get the proper notification. In those cases, queued reporting does not happen until the next logon.
Logon	When a report is queued, Microsoft Error Reporting writes to the run key (the HKEY_CURRENT_USER run key for user queues or the HKEY_LOCAL_MACHINE run key for administrator queues). At the next logon, Microsoft Error Reporting is triggered. There is a four-minute delay after the user logs on, to prevent the queued dialog box from interfering with important work the user needs to do at logon.
Force Queued Reporting	In certain scenarios, it is appropriate for the application to trigger queued reporting directly. For example, when synchronizing a handheld device to a host computer, saved error reports can be transferred to the queue and reported immediately, rather than waiting for one of the other triggers. Forcing queued reporting can have an adverse affect on the user experience. Contact Microsoft before implementing it in your application. To force queued reporting, CreateProcess on Dwtrig20.exe with the appropriate command line parameters: dwtrig20.exe -f parameter Where parameter is one of the following: 1   report from regular queue 2   report from signoff queue For example, Dwtrig20.exe -f 2 forces immediate reporting from the signoff queue.
Persistent Run Key	When Dw20.exe is running in the context of an unprivileged user, it cannot write the registry keys necessary to trigger queued reporting. The solution is a persistent run key, which causes Dwtrig20.exe to run at each startup. This is a small performance hit, but is necessary to flush the administrator queue. To enable this feature, add the property WatsonPersistentRunKey=1 to your MSI.

Generic Reporting

Generic reporting is for errors other than crashes. Think about using generic reporting when something happens that you want to know about. It can be triggered by a line of code or by a user action.

With generic reporting, you are not constrained to use the eight parameters that define a crash bucket. You may specify up to ten parameters. Each parameter may contain up to 255 characters.

Generic reporting is supported in Manifest mode and Shared Memory mode. Use Shared Memory mode if you want Microsoft Error Reporting to snap a mini dump at the time of the event. In most cases, you are uploading data files other than a mini dump, and you use Manifest mode.

Generic Manifest Mode

To use Generic Manifest mode, launch Microsoft Error Reporting according to the instructions in About Manifest Mode in this document.

The manifest you use for generic reporting must specify the name of your event type and values for each of the parameters. For example, an event type with two parameters has these lines in the manifest:

EventType=MyEvent
P1=Parameter Value
P2=Parameter Value

It is important to provide values for the correct number of parameters for your event type. If you have too many or too few values, your report is rejected by the server. You cannot skip parameters. If you have no value for a parameter, use a placeholder value like P1=x or P1=NULL.

Sample Generic Manifest

This manifest demonstrates generic reporting. Copy the text into Notepad, and save it as a Unicode text file. Leave the first line in the file blank.

Version=131072
UI LCID=1033
UIFlags=0        
ReportingFlags=0
LoggingFlags=0
General_AppName=Generic Demo
Main_Intro_Bold=SampleIntro!
Main_Intro_Reg=Intro text. It is entirely optional, as are most of these strings.
Main_Plea_Bold=Please tell Microsoft about this problem.
Main_Plea_Reg=We have created an error report that you can send to help us fix bugs. We will treat this report
as confidential and anonymous.
Queued_EventDescription=Event
EventType=Type
P1=Parameter Value
P2=Parameter Value
FilesToKeep=c:\file_you_want_to_upload

Generic Shared Memory Mode

To use Generic Shared Memory mode, populate the GenericModeBlock in your shared memory block with fInited, an EventTypeName, and values for up to 10 parameters.

typedef struct _GenericModeBlock
{
    BOOL fInited;
    WCHAR wzEventTypeName[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP1[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP2[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP3[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP4[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP5[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP6[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP7[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP8[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP9[DW_MAX_BUCKETPARAM_CWC];
    WCHAR wzP10[DW_MAX_BUCKETPARAM_CWC];
} GenericModeBlock;

Sanitizing Strings

Microsoft Error Reporting "sanitizes" all URLs before reporting. Sanitization happens when reporting crashes and when reporting generic errors, but the topic is included here to provide additional information in case you experience errors while using generic reporting. Some of the characters are banned by the operating system because they are not valid for creating files. Some characters create problems in the Microsoft Error Reporting Service's Stage2 ASP and SQL operations.

About Unicode

If a field value contains any non-ASCII characters, the whole string is turned into a hexadecimal representation. For this reason, we recommend you avoid Unicode strings.

About Invalid Characters

Invalid characters are changed to an underscore (_) before reporting. Invalid characters include:

• Characters 1–31 inclusive

• : \ / \\ < > | * ? & , %

About Invalid Words

These words are invalid; the first letter is changed to an "X" before reporting:

• CON, PRN, AUX, CLOCK$, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9

The word is converted if it is on its own, or if it is followed by a period and what looks like a file name extension, but not when it is part of other words.

For example, "con" is changed to "Xon", "con.exe" is changed to "Xon.exe", but "connection" is not changed.

Using Behavior Flags

The behavior flags are broken into four categories: reporting, user interface, logging, and Shared Memory mode. Each of the four categories is a DWORD bit field holding up to 32 flags.

Refer to the header file for enumerations and hexadecimal values.

For testing Manifest mode, add a line to the manifest with the sum of the decimal values. For example, the line ReportingFlags=3 in a manifest sets the fDwrDeleteFiles and fDwrIgnoreHKCU flags.

Reporting Flags

The following flags affect the client server conversation in Manifest mode (ReportingFlags line) and Shared Memory mode (EDwReportingFlags enum).

Table 10. Client server reporting flags

Flag Name	Decimal	Action
fDwrDeleteFiles	1	Delete files listed in FilesToDelete. Also delete the heap, mini dump, and manifest.
fDwrIgnoreHKCU	2	Look only in HKLM for the registry value(s) that affect behavior. Default is to look in both HKCU and HKLM.
fDwrForceToAdminQueue	4	Also set fDwrForceOfflineMode. Force the report to be queued to the administrator-only queue.
fDwrForceOfflineMode	8	If displaying UI, offer to queue reports. If not displaying UI, then always queue. It does not matter whether the user is connected.
fDwrDenyOfflineMode	16	Never queue reports. Report immediately if user is connected. If offline and unable to report, cancel upload, and delete the CAB file.
fDwrNoHeapCollection	32	Do not snap heap. This is a performance optimization if you are certain you will never request heap.
fDwrNoSecondLevelCollection	64	Also set fDwrNoHeapCollection. Protect privacy with silent reporting. If second-level data is requested, cancel the report.
fDwrNeverUpload	128	Show UI, but hide the Send Report button, and never upload a CAB file.
fDwrDontPromptIfCantReport	246	Suppress UI when no report will be sent anyway. This is useful for non-fatal errors.
fDwrNoDefaultCabLimit	512	Do not default to five-CAB limit when reporting to CER tree. Policy can still limit number of CABs.
fDwrFilesAreSafe	1024	Ignored by Microsoft Error Reporting. Affects how the Windows Vista intercepts treat the files added by using the FilesToKeep or FilesToDelete line of the manifest. If set, these files are understood to be safe by the Windows Vista interception.
fDwrCriticalEvent	2048	Ignored by Microsoft Error Reporting. This flag instructs the Windows Vista interception to treat the event as critical and show event-time UI.

User Interface Flags

These flags affect the user interface in Manifest mode (UIFlags line) and Shared Memory mode (EDwUIFlags enum).

Table 11. User interface flags

Flag Name	Dec	Action
fDwuNoEventUI	1	Do not display dialog boxes at the time that Microsoft Error Reporting is invoked. If report is not to be queued, upload it silently.
fDwuNoQueueUI	2	Also set fDwuNoEventUI. NoEventUI determines whether UI is shown when the error is initially reported. NoQueueUI determines whether UI is shown when reports are taken off the queue.
fDwuShowFeedbackLink	4	Display "Why should I send this report" link in the main dialog box, and open the page that provides more information about using Microsoft Error Reporting.
fDwuUseIE	8	Always launch Internet Explorer for URLs. If this is not set, Microsoft Error Reporting uses the default browser (except when the response uses a Trident window).
fDwuUseLitePlea	16	Not implemented.
fDwuManifestDebug	32	Display a Debug button if a JIT debugger is installed.
fDwuDenySuspend	64	Deny OS suspend request in main, second-level, and queued dialog boxes. If not set, deny suspend only when transferring.

Logging Flags

The following flags turn on and turn off the three events written to the system event log in Manifest mode (LoggingFlags line) and Shared Memory mode (EDwLoggingFlags enum).

Table 12. Logging flags

Flag Name	Dec	Action
fDwlNoParameterLog	1	Suppress logging bucket parameters prior to contacting the server. EventID is 1000 for crashes and 5000 for generic.
fDwlNoBucketLog	2	Suppress logging bucket ID and parameters after contacting the server. EventID is 1001 or 5001.
fDwlResponseLog	4	Log an event with ID 1010. Write a response URL with extra arguments to the data section (unless prevented by policy).

Shared Memory Mode Flags

The following flags apply only to Shared Memory mode (EDwExceptionModeFlags enum).

Table 13. Shared memory mode flags

Flag Name	Dec	Action
fDweCheckSig	1	Check signatures of (the crashed) EXE and loaded DLLs. Notify the user if the aggregate trust level indicates corrupt binaries.
fDweTagCommandLine	2	Add DW_CMDLINE_TAG to the command line when restarting the application.
fDweDefaultQuit	4	Set the Restart/Quit check box default to Quit. This can be set if a crash occurs while an application is closing.
fDweKeepMinidump	8	Do not delete the mini dump when finished reporting. Write the mini dump to %TEMP%.

Restart

Microsoft Error Reporting automatically restarts the application only if it is called in Shared Memory mode and bfmsoctdsOffer is set by the Microsoft Error Reporting integrator. If fDweTagCommandLine is specified, then Watson=1 is appended to the command line.

Examples of MER User Interface

The following section gives examples of Microsoft Error Reporting UI.

Shared Memory Mode Crash Reporting

These screenshots demonstrate using Shared Memory mode to report crashes.

Main Dialog

Connected

Microsoft Office offers document recovery. If you do not offer document recovery, by default there is no check box. But you have the option to display a check box with the text Don't show me this again.

Figure 1. Sample Application error message, connected

Offline

Figure 2. Sample Application error message, offline

Queued Reporting Dialog

Regular Queue

Figure 3. Regular queue, hide details

Regular Queue Details

Figure 4. Regular queue, show details

Signoff Queue

Figure 5. Signoff queue, hide details

Signoff Queue Details

Figure 6. Signoff queue, show details

Error Report Details Dialog Box

The Error Report Details dialog box displays when the user clicks the What data does this error report contain? link in the main dialog box. Notice that the "Error signature" section includes the three new bucket parameters.

Figure 7. Error report details

Error Report Contents Dialog Box

The Error Report Contents dialog box shows the contents of the mini dump in Shared Memory mode, and a list of additional files in the CAB. You get to this dialog by clicking the View the contents of the error report link in the Error Report Details dialog box.

Figure 8. Error report contents

Document Recovery Dialog Box

The Document Recovery dialog box appears only if your application does document recovery at crash time. For small documents, it appears and disappears quickly and might not be noticed.

Figure 9. Document recovery

Second-Level Dialog Box

If the bucket is configured to request second-level data and Microsoft Error Reporting wants a CAB, then this dialog box appears after the user agrees to send the report.

Figure 10. Second-level data

Transfer Dialog Box

Notice the new Close when done check box, which is selected by default. (There is an updated AVI for high-color mode, not shown in this screenshot.)

Figure 11. Transferring report

Deny Suspend Request Dialog Box

Microsoft Office uses custom text to deny requests to standby or hibernate.

Figure 12. Deny request to standby or hibernate

Final Dialog Box

The final dialog box appears only if there is a response URL for the bucket, and the response is configured to display a final dialog box. If a response is configured to auto-launch a full browser window or Trident dialog box, then the final dialog box is not displayed.

Fix or Workaround Link

Microsoft Error Reporting displays the response this way when DisplayType = 0 in the Stage2 server response.

Figure 13. Error Reporting dialog box with more information link

Survey Link

You can configure the final dialog box to display a different string for surveys, so that Microsoft Error Reporting does not tantalize users with the hope of help, only to surprise and pester them. (Microsoft Error Reporting displays the response this way when DisplayType = 2 in the Stage2 server response.)

Figure 14. Error Reporting dialog box with survey link

Manifest Mode Crash Reporting

These screen shots were generated by setting all of the customizable UI strings to their names. For example, the manifest has a line Main_Intro_Bold=Main_Intro_Bold. The purpose is to demonstrate where each string is displayed in the UI. Most of the UI strings have default values, and you do not need to set them.

Main Dialog Box

Connected

Figure 15. Manifest mode main dialog box, connected

Offline

Figure 16. Manifest mode main dialog box, offline

Details Dialog Box

Figure 17. Details dialog box

Error Report Contents Dialog Box

Figure 18. Report contents

Document Recovery Dialog Box

The Document Recovery dialog box is never shown in Manifest mode.

Second-Level Dialog Box

Figure 19. Manifest mode, second-level contents

Transfer Dialog Box

Transferring

Figure 20. Transfer status, Manifest mode

Transfer Complete

This dialog box is displayed only if the user clears the Transfer check box.

Figure 21. Transfer complete, Manifest mode

Deny Suspend Request Dialog Box

Figure 22. Deny suspend request, Manifest mode

Final Dialog Box

Figure 23. Final dialog box

About Customizing Queued Reporting

The queues are shared by all applications, so the UI is not customizable. However, there is a string (Queued_EventDescription) that you can customize for each event. We recommend that you set your own string in Manifest mode. If you do not set Queued_EventDescription, the user sees the default string "Unexpected Error," which is not very informative.

Queued Dialog Box with Queued_EventDescription

Figure 24. Queued_EventDescription

Registry Settings

You can control some Microsoft Error Reporting behaviors with registry settings.

Unlike previous versions of Microsoft Error Reporting, you do not need to specify a registry key with RegSubPath. In fact, Microsoft Error Reporting does not support specifying a different registry key from the default.

Registry Keys

Microsoft Error Reporting looks for specific named values in the following four registry keys, in order from highest to lowest precedence:

• HKEY_CURRENT_USER\Software\Policies\Microsoft\PCHealth\ErrorReporting\DW

• HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\PCHealth\ErrorReporting\DW

• HKEY_CURRENT_USER\Software\Microsoft\PCHealth\ErrorReporting\DW

• HKEY_LOCAL_MACHINE\Software\Microsoft\PCHealth\ErrorReporting\DW

The first two keys are in the policies branch of the registry, which is where group policy is set. Settings in the policies branch of the registry cannot be changed by non-administrator users.

The last two keys may be used by other tools (such as the Office Custom Installation Wizard) that write registry settings during application deployment. By default, users can change settings in HKCU but not in HKLM.

You can configure Microsoft Error Reporting to look only in the two HKLM registry keys, by setting the fDwrIgnoreHKCU flag.

Registry Values

The following table lists registry value names that affect Microsoft Error Reporting behavior. All DWORD values are enabled if equal to 1 and disabled if equal to 0 or not present.

Table 15. Registry values affecting Microsoft Error Reporting behavior

Registry Value Name	Type	Notes
DWAlwaysReport	DWORD	Hide Don't Send button, and encourage the user to send a report.
DWBypassQueue	DWORD	Report immediately if the user is online. Cancel report if offline.
DWCloseTransferDialogWhenDone	DWORD	Turned on and turned off by a check box on the Report Transfer Progress dialog box.
DWExplainerURL	SZ	Replace the data use feedback link with the corporate page.
DWFileTreeRoot	SZ	UNC or link to System Center Operations Manager for more information about Corporate Error Reporting.
DWMaxQueueSize	DWORD	Maximum number of reports in each queue.
DWNeverUpload	DWORD	Hide Send Report button, and cancel report.
DWNoExternalURL	DWORD	Suppress response URL or Trident.
DWNoFileCollection	DWORD	Cancel upload when a file or user document is requested.
DWNoSecondLevelCollection	DWORD	Cancel upload for any second-level request.
DWNoSignOffQueueReporting	DWORD	Turned on and turned off by a check box on the Signoff Queued dialog box.
DWQueuePesterInterval	DWORD	Allow this number of minutes to elapse before prompting user again.
DWReporteeName	SZ	Replace "Microsoft" with another company name in reporting dialog boxes.
DWTracking	DWORD	Log user name, computer name, and time/date to the CER log.
DWURLLaunch	SZ	Ignore response, and always display this URL in the final dialog box.
DWVerboseLog	DWORD	Display a diagnostic log for integrators.

Group Policy Template

Microsoft Error Reporting includes a policy template, or ADM file, which is included with the Watsonintl.msm merge module and localized into all of the Microsoft Error Reporting languages.

The template is installed to the %WINDIR%\Inf folder and named Aer_LCID.adm, where LCID is the decimal LCID. The English version of the template is Aer_1033.adm.

List of Policies

The following table lists registry value names and the corresponding policy name as it appears in the template.

Table 16. Registry value names and policy names

Registry Value Name	Policy Name
General Category
DWNeverUpload	Disable error reporting
DWNoFileCollection	Do not upload user documents
DWNoSecondLevelCollection	Do not upload any additional data
DWNoExternalURL	Do not display Microsoft Web page
Corporate Error Reporting Category
DWFileTreeRoot	Local error reporting file path
DWTracking	Log error report details
DWAlwaysReport	Hide Don't Send Button
DWReporteeName	Replace "Microsoft" with your company name
DWURLLaunch	URL to launch after reporting
DWExplainerURL	URL to explain why user should report
Queued Reporting Category
DWBypassQueue	Bypass queue and send all reports
DWMaxQueueSize	Maximum number of queued reports
DWQueuePesterInterval	Time between queued reporting requests

To load the Microsoft Error Reporting template and view policies

1. Install Microsoft Error Reporting.

2. On the Start menu, click Run, and then type gpedit.msc.

3. In the tree view, click Local Computer Policy\Administrative Templates.

4. Right-click Add/Remove Templates, and then click Add.

5. Click Aer_1033.adm, and then click Open.

6. Expand the Administrative Templates branch (in Computer Configuration or User Configuration), and then select Application Error Reporting.

7. Click one of the three categories: General Reporting, Corporate Error Reporting, or Queued Reporting.

8. Click a policy to read its Help text.

Using Microsoft Error Reporting on Windows Vista and Later Operating Systems

Microsoft Error Reporting on Windows Vista is intercepted by the operating system. Expect different behavior on Windows Vista and later operating systems. Windows Vista contains a centralized error reporting system, which intercepts calls to Microsoft Error Reporting. As a result, Microsoft Error Reporting is less customizable on Windows Vista than on Windows XP. The functionality on Windows Vista supersedes the Microsoft Error Reporting functionality described earlier, so some settings are not honored.

Microsoft Error Reporting allows callers to report crashes and other types of events. Differences in behavior between calling Manifest mode and Shared Memory mode are defined below.

Crash Processing

Because Windows Error Reporting supersedes Microsoft Error Reporting integration, it reports and processes crashes by using the same logic as Windows Crash Reporting. This section specifies all functionality when Windows Error Reporting supersedes the Microsoft Error Reporting integration. This functionality deviates from typical crash reporting:

• If fDwrForceOfflineMode is set, the report is queued.

• If fDwuManifestDebug or msoccdsDebug is set, the Debug button is allowed on the reporting UI.

• If fDweDefaultQuit is set, restart and recovery are not executed for this report.

Crash Reporting

Crash handling occurs only when Microsoft Error Reporting is called:

• In Shared Memory mode with a populated Pointer Exception Block.

When reporting a crash, Windows Error Reporting does the following to supersede the Microsoft Error Reporting integration:

1. Registers for restart (as appropriate) and recovery (as appropriate).

2. Reports the crash.

Parameters

If the crash is reported by using Shared Memory mode, the crash parameters are determined by the crash reporting as defined in the crash reporting specification.

If the crash is reported by using Manifest mode, the crash parameters are determined by the application.

Generic Reporting Report Properties

The following table lists commands and flags and their related actions.

Table 17. Command or flag behavior

Command/Flag	Action
EventType	Value for WerReportCreate::pwzEventName is respected.
General_AppName	Value for WerReportSetOptions::wzApplicationName is respected.
fDwrForceOfflineMode	Queue the report.
fDwuManifestDebug	Allow a Debug button in the report.
fDweDefaultQuit	Do not execute restart and recovery for this report.

Parameters

WerReportSetParameter is called once for every P1 … P10 command found in the report. If the parameters are not found in a Manifest-mode report and the caller has specified a Stage1 URL and a Stage2 URL, then Microsoft Error Reporting calls the URLs directly. P1 … P10 are, in other words, respected.

Files

WerReportAddFile is called for each FilesToKeep and FilesToDelete command in the report.

Generating Mini Dumps

A mini dump is an API that can be collected only if Microsoft Error Reporting is being called from Shared Memory mode. A mini dump is a subset of the crash reporting data; it is smaller and can be transmitted more quickly. If the caller is using Manifest mode, this API is never called.

Report Description

The report description is concatenated from the following respected UI strings:

• Main_Intro_Bold

• Details_Pre_Body

Privacy

If fDwuNoEventUI or fDwuNoQueueUI are set, then the report is submitted as if the application has consent from the user (as if the WerReportSubmit() parameter for dwConsentResult were set to WerConsentAskedApproved).

If fDwrForceOfflineMode is set, then the report is sent to the consent queue (where it is subject to normal consent-setting evaluation).

For more information about consent settings, see WER Settings.

User Experience

If the report is submitted through Shared Memory mode, then Microsoft Error Reporting assumes the report is a fatal report.

If the report is submitted through Manifest mode, then Microsoft Error Reporting assumes the report is non-fatal.

The user experience in either case is as specified in the Windows File Protection (WFP) Infrastructure specification. For more information, see Windows Error Reporting.

Not Respected Commands, Flags, Strings, and Settings

Commands

Version

Flags

The following flags are not respected and are ignored.

Table 18. Not respected flags

Flag Name	Decimal	Action
fDwrIgnoreHKCU	2	Look only in HKLM for registry values that affect behavior. The default is to look in both HKCU and HKLM.
fDwrDenyOfflineMode	16	Never queue reports. Report immediately if user is connected. If offline and unable to report, cancel upload, and delete CAB file.
fDwrNeverUpload	128	Show UI, but hide the Send Report button, and never upload a CAB file.
fDwrDontPromptIfCantReport	246	Suppress UI when no report will be sent anyway. This is useful for non-fatal errors.
fDwrNoDefaultCabLimit	512	Do not default to five-CAB limit when reporting to Corporate Error Reporting (CER) tree. Policy can still limit the number of CAB files.
fDwuShowFeedbackLink	4	Display "Why should I send this report" link in the main dialog box. Open the page that explains why customers should send error reports.
fDwuUseIE	8	Always launch Internet Explorer for URLs. If this is not set, use the default browser (except when the response uses a Trident).
fDwuUseLitePlea	16	Not implemented.
fDwuDenySuspend	64	Deny an OS suspend request in main, second-level, and queued dialog boxes. If this is not set, deny suspend only when transferring.
fDwlNoParameterLog	1	Suppress logging bucket parameters prior to contacting the server. EventID is 1000 for crashes and 5000 for generic.
fDwlNoBucketLog	2	Suppress logging bucket ID and parameters after contacting the server. EventID is 1001 or 5001.
fDwlResponseLog	4	Log an event with ID 1010. Write a response URL with extra arguments to the data section (unless prevented by policy).
fDweKeepMinidump	8	Do not delete the mini dump when finished reporting. Write the mini dump to %TEMP%.

UI Strings

None of the UI strings defined for Microsoft Error Reporting are respected by the Windows Feedback Platform, except for the following:

Shared Memory mode

• wzMain_IconFile

• wzMain_Intro_Bold

• wzMain_Intro_Reg

• wzDetails_Pre_Body

• wzMain_ReportBtn

• wzMain_NoReportBtn

• wzMain_QueueBtn

Manifest mode

• Main_IconFile

• Main_Intro_Reg

• Main_Intro_Bold

• Details_Pre_Body

• Main_ReportBtn

• Main_NoReportBtn

• Main_QueueBtn

Registry Keys

Table 19. Registry value names and actions

Registry Value Name	Type	Action
DWAlwaysReport	DWORD	Hide the Don't Send button, and encourage user to send report.
DWBypassQueue	DWORD	Report immediately if user is online. Cancel report if user is offline.
DWCloseTransferDialogWhenDone	DWORD	Turned on and turned off by a check box in the Report Transfer Progress dialog box.
DWExplainerURL	SZ	Replace the data-use feedback link with the corporate page.
DWFileTreeRoot	SZ	UNC or link to System Center Operations Manager for more information about Corporate Error Reporting.
DWMaxQueueSize	DWORD	Maximum number of reports in each queue.
DWNeverUpload	DWORD	Hide the Send Report button, and cancel report.
DWNoExternalURL	DWORD	Suppress the response URL or Trident.
DWNoFileCollection	DWORD	Cancel upload when a file or user document is requested.
DWNoSignOffQueueReporting	DWORD	Turned on and turned off by a check box in the Signoff Queued dialog box.
DWQueuePesterInterval	DWORD	Allow this number of minutes to elapse before prompting the user again.
DWReporteeName	SZ	Replace Microsoft with another company name in reporting dialog boxes.
DWTracking	DWORD	Log user name, computer name, and time/date to the CER log.
DWURLLaunch	SZ	Ignore response, and always display this URL in the final dialog box.
DWVerboseLog	DWORD	Display the diagnostic log for integrators.

Managed Code

Microsoft Error Reporting cannot support managed applications natively, but is designed for integration with the Common Language Runtime (CLR).

Error reporting from managed code differs from error reporting from native code. There are important considerations to take into account, particularly when trying to take dumps of memory and setting bucketing parameters for exceptions, as follows:

• Bucketing parameters must be different for exceptions originating in managed code (the CLR does this and provides a Hosting API so that applications can access it).

• Memory dumps need additional data for managed processes, which Microsoft Error Reporting handles.

• Writing managed code to invoke Microsoft Error Reporting can create the shared memory block.

Microsoft .NET Framework 2.0 installs Microsoft Error Reporting and supports automatic reporting of unhandled managed exceptions (similar to Windows Error Reporting for unmanaged applications). Custom error reporting of handled exceptions is also supported.

For more information about automatic reporting, see Enabling JIT-Attach Debugging.

For more details about exception-mode reporting, see ICLRErrorReportingManager::GetBucketParametersForCurrentException Method.

Conclusion

Microsoft Error Reporting is a set of technologies that capture crash data and support reporting of crash information to Microsoft. ISVs developing applications for operating systems earlier than Windows Vista can use Microsoft Error Reporting to address device, driver, and application failures. Crash reports provided through Microsoft Error Reporting can also help ISVs identify problems in code.

Additional Resources

• Windows Quality Online Services

• Winqual Help

• Office Developer Center