WerRegisterFile

Adds an additional crash artifact (e.g. game log) to be collected at crash time, along with the crash dump file.

Syntax

HRESULT WerRegisterFile(
         PCWSTR pwzFile,
         WER_REGISTER_FILE_TYPE regFileType,
         DWORD dwFlags
)  

Parameters

pwzFile
Type: PCWSTR 

[in] The absolute path of the file to register. This parameter must refer to a file on the title (G:), title scratch (D:), or title temp (T:) drives. The maximum length of this path is MAX_PATH characters.

regFileType
Type: WER_REGISTER_FILE_TYPE 

[in] This parameter is unused and must be WER_REGISTER_FILE_TYPE::WerRegFileTypeOther. Passing a value for this parameter other than WER_REGISTER_FILE_TYPE::WerRegFileTypeOther will cause this function to return HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER).

dwFlags
Type: DWORD 

[in] This parameter is unused and must be zero. Passing a non-zero value for this parameter will cause this function to return HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER).

Return value

Type: HRESULT 

Remarks

The maximum number of files that can be registered is WER_MAX_REGISTERED_ENTRIES.

At crash time, each of the files registered using WerRegisterFile will be copied and uploaded along with the crash dump file. If local dumps are enabled, the registered files will get copied to the title scratch drive, alongside the crash dump file.

No verification is done on the existence of the file; if a registered file doesn’t exist at the time of the crash, it’s simply ignored.

Note Previously, local dumps were written to the root of the title scratch drive, but now that the files registered using WerRegisterFile are included, all of the files related to a single crash are written to a subfolder of the D:\LocalDumps folder (e.g. D:\LocalDumps\ComputeParticles140Debug.exe_2017-1-2-31-19-23-17-673).

Registered files won’t be able to be copied at crash time if the game still has an open handle to the file. To prevent this, the game can use an unhandled exception filter to flush the file buffers and close the open handles. (See example code below.)

Personally identifiable information should not be sent with any of the registered files.

To remove the file from the registered-files list, call the WerUnregisterFile function.

Example

static HANDLE g_hLogFile;

//
// Register the unhandled exception filter.
//
SetUnhandledExceptionFilter(XboxOneUnhandledExceptionHandler);

//
// Store the log file in the title local storage folder.
//
auto applicationData = Windows::Storage::ApplicationData::Current;
auto storageFolder = applicationData->LocalFolder;
std::wstring fileName(storageFolder->Path->Data());
fileName.append(L"\\GameLog.txt");

//
// Create the log file.
//
g_hLogFile = CreateFileW(fileName.data(),
  GENERIC_READ | GENERIC_WRITE,
  0,
  NULL,
  CREATE_ALWAYS,
  FILE_ATTRIBUTE_NORMAL,
  NULL);

//
// Register the log file to be collected along with the crash dump.
//
WerRegisterFile(fileName.data(), WER_REGISTER_FILE_TYPE::WerRegFileTypeOther, 0);

  .
  .
  .

static LONG WINAPI XboxOneUnhandledExceptionHandler(struct _EXCEPTION_POINTERS * exceptionInfo)
{
  //
  // Flush the file buffers and close the handle so that the log file can be copied.
  //
  FlushFileBuffers(g_hLogFile);
  CloseHandle(g_hLogFile);

  //
  // Return EXCEPTION_CONTINUE_SEARCH so that the platform will collect the crash.
  //
  return EXCEPTION_CONTINUE_SEARCH;
}  

Requirements

Header: Declared in werapi.h.

Library: Use kernelx.lib.

See also

WER_REGISTER_FILE_TYPE Enumeration