Windows Feedback Services

Developing with Windows Feedback Services

Windows Vista® allows application developers to control and customize error reporting through Windows Feedback and C-callable libraries. .NET Framework 3.0 applications can access this functionality through interoperability support in the Windows SDK. For more information, see the Interoperability & Migration section of this document.

For more information, see "Windows Error Reporting" in the Windows SDK.

Controlling Application Participation in Reporting

By default, all applications participate in the reporting mechanism, and any time an exception passes through an application to the operating system, a report is generated.

APIs allow an application to be excluded from participation in reporting by adding it to a list of excluded applications maintained under the HKLM registry hive.

Excluding Applications from Reporting

Typically, including or excluding an application in reporting is done by adding an application's base name (its name without path) to a list in the machine (HKLM) section of the registry. Applications with administrator privileges calling WerAddExcludedApplication will exclude all applications with that name from participating.

For example, an application can call:

HRESULT ret= WerAddExcludedApplication("C:\MyDir\AAA.exe");

In this case, the application will add AAA.exe to the exclusion list in the registry.

An application can be removed from the exclusion list, and therefore have its reports forwarded to the WinQual site, if its name is provided as an argument to WerRemoveExcludedApplication in an application executing with administrator privileges.

Because of the requirement for elevated privilege, these functions are designed for use in setup and installation.

For more information about Microsoft Windows Installer and ClickOnce, see the Installation and Update Management section of this document.

Programmatic Exclusion from Reporting

As reporting is initiated by the receipt of an unhandled exception by the Windows operating system, it is programmatically possible to avoid participating in it without registering for the exclusion list. Essentially, all that would be necessary would be to trap and not re-throw all exceptions at the top level of the application. However, unless some specific debugging and troubleshooting mechanism is built into an application, this is not advised.

Security and UAP Issues

As the HKLM registry hive is a system-critical registry hive, if UAP is enabled administrator privileges are required to modify the list of applications excluded from reporting using APIs.

If a 32-bit application calls either WerAddExcludedApplication or WerRemoveExcludedApplication, the function behavior will be virtualized. Either function will modify a private, user- accessible-only version of the HKLM hive. In this case, the system defaults for other users will not be changed.

Native 64-bit applications do not support virtualization. Any native 64-bit application needing to exclude or include an application in reporting will therefore need to support explicit privilege elevation. For more information on virtualization, see Virtualization: the Backwards Compatibility Application Execution Model.

Adding Data to Standard Reports

Any application can customize the standard error report by either registering new data objects for inclusion in the report sent to the WinQual site, or changing the report's default setting. It is possible to make these modifications at any point during the life cycle of an application, adjusting to a changing diagnostic environment.

Error Report Content

Data reported to WinQual is divided into Level One and Two Data. Level One Data is used to identify and categorize problems. The data is found in a set of up to 10 string parameters, which identify a particular classification of the problem. Parameters should only contain anonymous information and theoretically identify a class of problem. Standard or Simple reporting automatically fills this data. Generic or custom reporting needs to fill these fields by calls to WerReportSetParameter.

A typical set of parameters for a failure would include: application name, application version, module name, module version, and module offset. All reports are also automatically annotated with the user's language/country ID, operating system version information (including major and minor version numbers and the operating system build), and OEM information. As a collection, these parameters provide a unique way to accurately classify a failure.

Level Two Data consists of detailed information to be used in debugging a problem. This data includes but is not limited to associated files, a minidump for the failure, the heap, registry keys, outstanding queries ( for example, database and WMI queries), and so on.

Forcing Error Reports

In principle, it is even possible to make these modifications while processing an unrecoverable error. This would be done by an application that has created its own unhandled exception filter, where it would invoke the various error report modification functions and then re-throw the exception.

While modifying what information is contained in a potential error report during normal running can be a sensible practice, modifying a report in the course of an unrecoverable event is not recommended.

Secure Process Reporting

Reporting of secure processes, which contain data encrypted with a private key and are intended to restrict permission for specific users, is supported. For example, processes dealing with secure digital media.

To prevent any possibility of exploitation through the user interface, if a failure occurs on a secure process, another secure process will automatically be created and queued to run the required services. Consent will be obtained through normal means.

Setting

The configuration of a potential error report can be obtained by calling:

HRESULT WerGetFaultReportingSettings(

HANDLE hProcess,

PDWORD pdwFlags

);

These settings can be changed by calling:

HRESULT WerRegisterFaultReportingSettings(

DWORD dwFlags

);

Settings are specified as a DWORD bit mask. Currently, the only valid setting is WER_FAULT_REPORTING_FLAG_NOHEAP, which inhibits inclusion of a heap dump file with the error report.

Adding Data Objects

An application can add two types of data objects to an error report:

• Files

• Memory blocks

File Inclusion

Files can be registered for inclusion with an error report by calling:

HRESULT WerRegisterFile(

__in PCWSTR pwzFile,

_in WER_REGISTER_FILE_TYPE regFileType,

_in DWORD dwFlags

);

Files are removed from a report using:

HRESULT WerUnRegisterFile(CWSTR pwzFilePath);

When registering a file by calling:

• The file is identified by a full path. It is the responsibility of the application to verify the file in question is available for inclusion in a report. The file should be in a well-defined state and not locked.

• An argument of type WER_FILE_TYPE supplied to WerRegisterFile specifies the type of file being added to the error message.

  For more information on WER_REGISTER_FILE_TYPE, see its description in Data Types Description.

  It is up to the application to create the dump file. For more information on working with dump files, see Debugging OCA Minidump Files on Windows Quality Online Services (WinQual), or the discussions of Minidump Files and the Dumps section of the Windows SDK.

• Optionally, an application can set the dwFlag to provide the infrastructure with additional file handling instructions.

  The flag can be zero, or can contain the bitwise OR of the following values:

  WER_DELETE_FILE_WHEN_DONE	Indicates that the file can be deleted after report submission.
  WER_ANONYMOUS_DATA	Indicates that the file contains no information relating to an identifiable individual, and therefore can be added to publicly available information.

Memory Block Inclusion

All memory regions registered must be nonadjacent. Specific regions of application memory are registered for inclusion with an error report with:

HRESULT WerRegisterMemoryBlock(

PVOID pvAddress,

DWORD dwSize

);

Memory is removed from a report with:

HRESULT WerUnRegisterFile(PCWSTR pwzFilePath);

When adding a memory region for inclusion in a standard error report, an application must provide to WerRegisterMemoryBlock:

• The start address of the memory region to be included in the error report

• The length (in bytes) of the memory region

A memory region can be removed from inclusion in an error report by calling WerUnRegisterMemoryBlock with the start address of a memory region previously registered for inclusion.

Custom Error Report Type Submission

Windows Feedback supports the creation of custom or generic error reports created in response to non-standard events and submitted to the WinQual portal.

This provides developers with control over when reports are created, what files reports contain, and how reports are categorized or bucketed by WinQual.

Developers needing to create their own report types based on custom events must:

• Define custom events

• Create a report setup algorithm

• Specify report parameters

• Select data for inclusion in the report

• In response to the custom event, submit the report to WinQual

Defining Custom Events

The initial release of WER does not support the definition of custom error events, which would allow richer interaction of the application with WinQual. This capability is under consideration for a future release of WER.

Report Initialization

Report setup starts by initializing the report with a call to:

HRESULT WerReportCreate(

PCWSTR pwzEventType,

WER_REPORT_TYPE repType,

PWER_REPORT_INFORMATION pReportInformation,

HREPORT *phReportHandle

);

If initialization is successful, a report handle is returned, pointed to by phReportHandle. This handle is used in all further manipulation of the error report. If an error occurs, NULL is returned.

When called, WerReportCreate must:

• Be supplied with a valid event type name registered with WinQual.

• Specify a report type. Supported report types are specified by the WER_REPORT_TYPE enumeration and can be:

  WerReportNonCritical	The default report type. Used for reporting recoverable errors. By default, processes submitting non-critical reports will not be terminated or restarted. WinQual might not archive these reports.
  WerReportCritical	Used for reporting unrecoverable errors or application failures. By default, processes submitting critical reports will be terminated or restarted. WinQual will always archive these reports.

• Optionally, a report can be further configured if the pReportInformation argument is a valid WER_REPORT_INFORMATION structure.

  For more information on WER_REPORT_INFORMATION, see Data Types Description.

Report Parameters

Applications submitting custom reports must be sure that each instance of a submitted report is uniquely identified.

One set of required primary parameters and one set of optional secondary parameters are provided to ensure identification of every reported event.

Primary Parameters

Every custom or Generic report has a signature defined by a zero-based array of up to 10 parameters. These parameters form the Level One Data for an error report. For more information on the error report structure, see the Error Report Content section below.

Each parameter is a null-terminated Unicode representation of a 16-bit string. They are set by calling:

HRESULT WerReportSetParameter(

HREPORT hReportHandle,

DWORD dwFlags,

PCWSTR pwzName, //optional

PCWSTR pwzValue

);

Applications calling WerReportSetParameter must specify:

The handle, returned by WerReportCreate, of the report the parameters are being set for.

• The index of the parameter being set (dwparamID). A separate call needs to be made for each parameter.

• The value of the parameter (pwzValue) expressed as a Unicode representation of a 16-bit string.

Optionally, the name of the parameter can also be supplied.

Secondary Parameters

Secondary parameters, which are optional, are a group of name/value pairs that can be added to the report signature. Typically, secondary parameters are used to add brand and custom query information to the report, and are set by calling:

HRESULT WerReportAddSecondaryParameter(

HREPORT hReportHandle,

PCWSTR pwzKey,

PCWSTR pwzValue

);

Applications calling WerReportAddSecondaryParameter must specify:

• The handle, returned by WerReportCreate, of the report the parameters are being set for.

• The name of the parameter (pwzKey) and its value (pwzValue). Both name and value must be expressed as a Unicode representation of a 16-bit string.

Data Selection

Data is supplied to custom error reports by specifying application dump files and other files for inclusion.

Custom error reports do not support the direct inclusion of memory blocks into their reports. Memory blocks can be included by specifying data to be included in a dump file, or by including the information in a file added to an error report.

Dump files generated are governed by the settings conventions that apply to the ordinary creation of dump files using MiniDumpWriteDump and the MINIDUMP_TYPE enumeration.

For more information on permitted flags, see the Debug Help Library, MINIDUMP_TYPE, and MiniDumpWriteDump sections in the Windows SDK.

Custom Dump File Inclusion

Applications are allowed to generate dump files and add them to an error report.

Dumps are configured and specified by calling:

HRESULT WerReportAddDump(

HREPORT hReportHandle,

HANDLE hProcess,

HANDLE hThread,

WER_DUMP_TYPE dumpType,

PWER_EXCEPTION_INFORMATION pExceptionParam,

PWER_DUMP_CUSTOM_OPTIONS pDumpCustomOptions,

DWORD dwFlags

);

Applications calling WerReportAddDump must specify:

• The handle, returned by WerReportCreate, of the report the parameters are being set for.

• The process (hProcess) and thread (hThread) for which the dump file is to be generated. These handles must allow read and query access to the process and thread.

• The type of dump file to be generated. The type is specified by a value from the WER_DUMP_TYPE enumeration. For mor information on the WER_DUMP_TYPE enumeration, see the Data Types Description section below.

• NULL or a pointer to a valid instance of the WER_EXCEPTION_INFORMATION structure (pExceptionParam) containing information about the exception that caused the error report. If the parameter is NULL, no exception information will be sent with the error report.

  For more information on the WER_EXCEPTION_INFORMATION structure, see the Data Types Description section below.

• NULL or a pointer to a valid instance of the WER_DUMP_CUSTOM_OPTIONS structure (pDumpCustomOptions) specifying advanced customization of the error report. It is through this structure that standard dump file configuration settings, as defined by the MINIDUMP_TYPE, THREAD_WRITE_FLAGS, and MODULE_WRITE_FLAGS enumerations, are supplied to the system.

  For more information on the WER_DUMP_CUSTOM_OPTIONS structure, see the Data Types Description section below.

Custom File Inclusion

Applications are allowed to add specified files to a custom or Generic error report by calling:

HRESULT WerReportAddFile(

HREPORT hReportHandle,

PCWSTR pwzPath,

WER_FILE_TYPE repFileType,

DWORD dwFileFlags

);

Applications calling WerReportAddFile must specify:

• The handle, returned by WerReportCreate, of the report the parameters are being set for.

• The complete path (pwzPath) to the file that needs to be added. The path can contain environment variables.

• The type of file being included, specified by a WER_FILE_TYPE argument.

  For more information on WER_FILE_TYPE, see the Data Types Description section below.

• Optionally, an application can set the dwFileFlag to provide additional file handling instructions. The flag can be zero, or can contain the bitwise OR of the following values:

  WER_DELETE_FILE_WHEN_DONE	Indicates that the file can be deleted after report submission.
  WER_ANONYMOUS_DATA	Indicates that the file contains no information relating to an identifiable individual, and therefore can be added to publicly available information.

User Interface Customization

Optionally, an application developer can decide to modify information displayed by the system error handling dialog box.

To modify one of the strings that appear in the user interface applications, call:

HRESULT WerReportSetUIOption(

HREPORT hReportHandle,

WER_REPORT_UI repUITypeID,

PCWSTR pwzValue

);

WerReportSetUIOption can be called at any time before report submission, even during event handling. Applications calling WerReportSetUIOption must specify:

• The handle, returned by WerReportCreate, of the report the parameters are being set for.

• The section of the error handling user interface to be modified by supplying a value (repUITypeID) from the WER_REPORT_UI enumeration.

  For more information on WER_REPORT_UI, see the Data Types Description section below.

• A string (pwzValue) containing the new value to be displayed.

An application can modify any or all of the fields that can be specified by the members of WER_REPORT_UI. A separate call for each UI element is required.

Report Submission

The standard or Simple error report is generated by the operating system whenever it receives an unhandled exception from an application. An application producing custom or Generic error reports is solely responsible for event handling and report submission. There is no automated system for submitting custom reports.

To submit a report, an application must trap and handle the appropriate error conditions, and then it must call:

HRESULT WerReportSubmit(

HREPORT hReportHandle,

WER_CONSENT consent,

DWORD dwFlags,

PWER_SUBMIT_RESULT pSubmitResult

);

Calling WerReportSubmit will, if user consent is required, produce an appropriate user interface and then queue the report for delivery to WinQual. After submitting a report by calling WerReportSubmit, the application should release the report handle by calling:

HRESULT WerReportCloseHandle(HREPORT hReportHandle);

Applications calling WerReportSubmit must specify:

• The handle, returned by WerReportCreate, of the report the parameters are being set for.

• A flag (consent) indicating the level of user consent already obtained. Depending on the value of this argument, which must be a member of the WER_CONSENT enumeration, appropriate consent or notification dialog boxes are generated.

  For more information on the WER_CONSENT enumeration, see the Data Types Description section below.

• A bitwise OR of additional flags (dwFlags) that, if non-zero, will further customize the submission. This parameter will only support values defined in the list of WER Report Submission Flags.

  For more information on WER Report Submission Flags, see the Data Types Description section below.

An application calling WerReportSubmit obtains status information about its submission from the WER_SUBMIT_RESULT enumeration that is returned to it (pSubmitResult).

For more information on WER_SUBMIT_RESULT, see the Data Types Description section below.

Resources

Libraries	Description
Kernel32	The libraries containing all the Windows Feedback technologies.

Headers	Description
werapi.h	The header file for error-reporting functionality.

New Report Type APIs	Description
WerReportCreate	Initiates a non-standard type report, and returns a report handle. The report is defined by WER_REPORT_TYPE and WER_REPORT_INFORMATION objects supplied to the function.
WerReportAddDump	Indicates that a specific dump file is to be included in the new report type. The dump is specified by WER_DUMP_TYPE, WER_EXCEPTION_INFORMATION, and WER_DUMP_CUSTOM_OPTIONS arguments supplied to the function.
WerReportSetParameter	Sets the parameters that uniquely identify a particular error report. A separate call must be made for each parameter, which is selected by index.
WerReportAddSecondaryParameter	An optional method to add name/value pairs to the report. Used, for example, to add brands and parameters supporting a custom query to the report.
WerReportAddFile	Indicates a file to be included in a new type report. The type of file is specified by a WER_REGISTER_FILE_TYPE argument.
WerReportSetUIOption	Configures user interface features based on a WER_REPORT_UI argument.
WerReportSubmit	Creates and submits a report to WinQual. Returns a WER_SUBMIT_RESULT value.
WerReportCloseHandle	Closes the report handle.

Data Collection APIs	Description
WerRegisterFaultReportingSettings	Registers flags to determine specific aspects of error handling.
WerGetFaultReportingSettings	Obtains reporting settings for the current application.
WerRegisterFile	Marks a non-standard file to be added to an error report. The type of file is supplied by a WER_REGISTER_FILE_TYPE argument.
WerUnRegisterFile	Removes a file from an error report.
WerRegisterMemoryBlock	Marks a specific block of memory to be added to a specific error report.
WerUnRegisterMemoryBlock	Removes a specific block of memory previously marked to be added to a specific error report.

Application Setup APIs	Description
WerAddExcludedApplication	Marks an executable file as not participating in error reporting. Typically called by an installation or setup routine.
WerRemoveExcludedApplication	Marks an executable file as participating in error reporting.

Data Types	Description
WER_DUMP_CUSTOM_OPTIONS	A structure containing information about how an application should be dumped.
WER_DUMP_TYPE	The type of dump file returned with the report, such as microdump, minidump, full dump, or heap dump file.
WER_EXCEPTION_INFORMATION	A structure containing information about the exception that generated the failure report.
WER_FILE_TYPE	The type of file to be added to a custom or Generic report.
WER_REGISTER_FILE_TYPE	The type of file to be added to a standard or Simple report.
WER_REPORT_INFORMATION	A structure containing information about report content, such as application name, user consent, and description.
WER_REPORT_TYPE	The type of report to be submitted: critical, or non-critical.
WER_REPORT_UI	The type of user interface the system should generate in support of the failure report.
WER_SUBMIT_RESULT	The code returned from submitting a failure report.

WERReport Submission Flags

Value	Definition
WER_REPORT_HONOR_RECOVERY	If the application has registered for data recovery, attempt data recovery.
WER_REPORT_HONOR_RESTART	If the application has registered for automatic restart, attempt automatic restart.
WER_REPORT_QUEUE	The submitted report is queued on disk instead of being immediately uploaded, even if the application is connected to the Internet.
WER_SHOW_DEBUG	Show the debug button on the dialog box.
WER_ADD_REGISTERED_DATA	Add registered data to the submitted report.
WER_REPORT_OUTOFPROCESS	Force the report to go out of process.
WER_REPORT_NO_CLOSE_UI	Do not show the Close dialog box for the critical report.
WER_REPORT_NO_PROGRESS	Do not show the Progress dialog box for the critical report.