Commit 5d4204f

We've made it possible to store a precisely diagnosed error, reported by the Address Sanitizer runtime, for post-mortem debugging in Visual Studio. You can capture a precisely diagnosed error and view it on another machine.

Your testing automation could do this on remote machines before running your tests against code compiled with -fsanitize=address.

If you would like to see further Cloud based customization please [provide feedback](https://aka.ms/feedback/suggest?space=62) that might help you take advantage of [Azure OneFuzz](https://www.microsoft.com/security/blog/2020/09/15/microsoft-onefuzz-framework-open-source-developer-tool-fix-bugs/).

Once you set a file name in the environment variable **ASAN_SAVE_DUMPS** then upon error, your application will produce "MyFileName.dmpx" which is a [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) that can be displayed by using Visual Studio at a later date on another machine.

**The .exe, .pdb and source code used to produce those, must match** for Visual Studio to display the precise Address Sanitizer error within the debugger IDE. As with normal debugging, displaying information, within the context of the original source code, Visual Studio requires [debugging symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) and [indexing source code](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/source-indexing).

We provide a simple step-by-step example below.

Assume you have machines A, B and C. You build on machine B, you run on machine C and then you analyze failures on machine A. The errors are reported against source line and column numbers in your source code. The call stack is displayed with a set of symbols produced from that [same source code](#Source-and-symbols).

The following steps take you through a workflow that involves three (3) different machines.


Source server enables a client to retrieve the **exact version** of the source files that were used to build an application. Because the source code for a module can change between versions and over a course of years, it is important to look at the source code as it existed when the version of the module in question was built.

Source server retrieves the appropriate files from source control. To use source server, the application must have been [source indexed](https://docs.microsoft.com/en-us/windows/win32/debug/source-server-and-source-indexing)

- See [the steps indexing sources and publishing symbols](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/build/index-sources-publish-symbols?view=azure-devops)

- See [how to specify symbols and source code for the debugger IDE will to open your crash dump from the Address Sanitizer](https://docs.microsoft.com/en-us/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger?view=vs-2019)

When your .EXE encounters a runtime error, the Address Sanitizer runtime throws different exceptions. When run from the command line the Address Sanitizer runtime will with throw an exception and produce textual error information on the console.

When run under the Visual Studio debugger, the new debugger IDE displays that error diagnostic, super imposed on your source code. That's due to new meta-data written to the heap. The exceptions the runtime throw, are implemented with an exception record data structure. That record points to the meta-data in the heap and the new IDE can parse it. That same information can also be preserved in a simple memory dump to a binary file for later ingestion by the new debugger IDE.

Projects can enable the Address Sanitizer with a project setting, or a single additional compiler switch: **-fanitize=address**. The new flag is compatible with all levels of optimization but it is not compatible with three compilation modes: [edit-and-continue](https://docs.microsoft.com/en-us/visualstudio/debugger/edit-and-continue-visual-cpp?view=vs-2019), [incremental linking](..\..\build\reference\incremental-link-incrementally.md), and [/RTC](..\..\build\reference\rtc-run-time-error-checks.md). Apart from those three modes, all other configurations are supported when targeting x86 and x64.

The Address Sanitizer is integrated with the Visual Studio the project system, CMake system, and the IDE.

Using the flag -fsanitize=address, the driver (cl.exe) will link a new library with your executable. This library enables integration with the IDE and it can optionally create a new crash dump file. Setting an environment variable via `set ASAN_SAVE_DUMPS=”MyFileName.dmp”`, your program can automatically create a new type of crash dump file that will contain extra meta-data for efficient, [post-mortem debugging](#.\asan-offline-address-sanitizer-crash-dumps.md) of **precisely diagnosed bugs**. These files facilitate extended use of the Address Sanitizer for local machine testing as well as:

- On-premise distributed testing and

Simply [**install the Address Sanitizer functionality**](.\asan-installing.md).