> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Compatibilidad de Address Sanitizer para XBOX
> Compatibilidad de Address Sanitizer para XBOX
Como la mayoría de los programas de C++, los juegos pueden sufrir una clase de errores que afectan a la corrección y la estabilidad del programa, motivo por el cual, a partir de Visual Studio 2022, el compilador de C/C++ de Microsoft (MSVC) y el IDE admiten la tecnología AddressSanitizer (ASan). Se trata de una tecnología de compilador y en tiempo de ejecución que expone muchos errores difíciles de encontrar con cero falsos positivos, por ejemplo:
* Discrepancias de alloc/dealloc y discrepancias de tipos new/delete
* Asignaciones demasiado grandes para el montón
* Desbordamiento de calloc y desbordamiento de alloca
* Doble liberación (double free) y uso después de liberar (use after free)
* Desbordamiento de variables globales
* Desbordamiento de búfer del montón
* Alineación no válida de valores alineados
* Superposición de parámetros de memcpy y strncat
* Desbordamiento y subdesbordamiento del búfer de la pila
* Uso de la pila después del retorno y uso después del ámbito
* Uso de memoria después de haberse marcado como envenenada
Puede encontrar más información sobre ASan en las páginas de Visual Studio: [AddressSanitizer](https://learn.microsoft.com/cpp/sanitizers/asan) (Microsoft Docs)
## Habilitación de ASan en el compilador
Address Sanitizer está integrado con el sistema de proyectos de Visual Studio, el sistema de compilación CMake y el IDE. Los proyectos pueden habilitar AddressSanitizer mediante una opción adicional del compilador, *`/fsanitize=address`*, o estableciendo una propiedad del proyecto en Visual Studio:
Esta opción es compatible con todos los niveles de optimización y configuraciones de x64. Sin embargo, es **incompatible** con `edit-and-continue`, `incremental linking` y `/RTC`, que deben deshabilitarse antes de compilar con ASan.
Al habilitar ASan, se requiere que se vincule una biblioteca adicional a su código. Esta referencia la agrega automáticamente el sistema de compilación. Esto también requiere que establezca "Additional Library Directories" en ***Linker > General*** para su proyecto. Asegúrese de que el valor
`$(VC_LibraryPath_VC_x64)` sea el último de la lista para evitar que se use para otras bibliotecas, como se muestra a continuación:
## Requisitos en tiempo de ejecución de ASan
Cuando un juego se compila con ASan habilitado, requiere que un archivo DLL adicional esté presente en tiempo de ejecución, que es lo que habilita la funcionalidad. De forma predeterminada, cuando ASan está habilitado en el compilador, copiará el archivo DLL en el directorio de salida de su proyecto y, después, debe implementarse en la consola junto al ejecutable.
Si es necesario, los archivos DLL pueden encontrarse manualmente en el directorio `$(VC_ExecutablePath_x64)` de Visual Studio. XBOX requiere uno de estos dos, según la versión de compilación:
| Nombre de archivo DLL | Tipo de compilación |
| -------------------------------------- | --------------------------- |
| `clang_rt.asan_dbg_dynamic-x86_64.dll` | Compilaciones de depuración |
| `clang_rt.asan_dynamic-x86_64.dll` | Compilaciones de versión |
## Compatibilidad del depurador en tiempo de ejecución
Al ejecutar un juego con ASan habilitado y un depurador conectado, si se encuentra un error, se interrumpirá en el depurador y se mostrará un informe detallado que le permitirá determinar dónde se produjo el error.
Pero si se está ejecutando sin un depurador conectado, por ejemplo en un marco de pruebas automatizadas, la información del error se muestra en la salida estándar y el juego se cerrará. Esto puede ser útil, pero es posible que necesite más información de estado para encontrar la causa raíz del bloqueo, y es ahí donde entra la compatibilidad con volcados de memoria (Crash Dump).
Si se está ejecutando sin un depurador conectado y necesita que los símbolos se resuelvan en ese momento, debe implementar el archivo `llvm-symbolizer.exe` junto al archivo EXE de su juego. Este archivo puede encontrarse en la misma ubicación que los archivos DLL en tiempo de ejecución de ASan indicados anteriormente.
## Compatibilidad con volcados de memoria en tiempo de ejecución
A partir de Visual Studio 16.9.8 o 16.10.2, ASan puede configurarse para guardar un archivo de volcado de memoria que contiene los metadatos asociados al error. El depurador de Visual Studio puede analizar los metadatos guardados en el archivo de volcado para proporcionar más contexto sobre el bloqueo. Puede configurar este guardado de volcados de memoria por compilación, almacenar estos artefactos binarios y, después, verlos en el IDE con la indexación de código fuente adecuada.
La documentación sobre volcados de memoria puede encontrarse aquí:
[Configuración de volcados de memoria](https://learn.microsoft.com/cpp/sanitizers/asan-offline-crash-dumps) (Microsoft Docs)
Pero el enfoque vinculado anteriormente requiere establecer una variable de entorno, lo que no se admite en XBOX, por lo que se implementó un método alternativo. Para agregar compatibilidad con volcados de memoria a su título de XBOX, simplemente puede definir una función de devolución de llamada que proporcione a ASan la información necesaria del nombre de archivo del volcado de memoria; a continuación se muestran tres ejemplos.
El nombre de archivo suele tener un sufijo ***.dmp*** para seguir las convenciones del IDE de Visual Studio
```c++ theme={null}
// 1. Use a hardcoded dump name
extern "C" const wchar_t* __vcasan_save_dumps()
{
return L"myCrashDump.dmp";
}
// 2. Programmatically build the dump name
extern "C" const wchar_t* __vcasan_save_dumps()
{
return TestFramework.buildName + TestFramework.buildInfo + TestFramework.dateTime;
}
// 3. You can conditionally choose NOT to collect a crash dump
extern "C" const wchar_t* __vcasan_save_dumps()
{
// Choose to create a crash dump based on a runtime flag
if ( gCollectCrashDumps )
{
return L"myCrashDump.dmp";
}
else
{
// Returning NULL stops ASan creating a crash dump
return NULL;
};
}
```
No hay requisitos específicos en cuanto al nombre devuelto por esta función, pero debe ser una ruta de archivo válida en el dispositivo de destino donde se ejecuta el código. Por ejemplo, escribir los volcados de memoria en la unidad D: de la consola significa que pueden encontrarse y recuperarse fácilmente durante el desarrollo.
También agregamos la capacidad de modificar el tipo de volcado de memoria que se genera. Hay casos en los que un simple volcado de "evaluación" (Triage) es suficiente para ver la pila de llamadas de dónde falló el proceso, pero para algunos problemas puede que necesite la memoria circundante en el momento en que se produjo el problema. Para ello, hemos proporcionado tres tipos de volcado de memoria configurables que son compatibles con la plataforma XBOX y coinciden con los tipos de volcado de memoria generados por la consola y xbWatson.
Al igual que con la función anterior, esta invalidación es **opcional** en XBOX, pero es muy recomendable si quiere usar volcados de memoria para recopilar información de ASan sin un depurador conectado. Si proporciona el nombre de archivo del volcado pero **no** una invalidación del tipo de volcado, no se podrá generar un volcado de memoria válido en XBOX.
Esta devolución de llamada devuelve un número para indicar el tipo de volcado requerido. Los tipos válidos se muestran en el ejemplo siguiente:
```c++ theme={null}
extern "C" const signed int __vcasan_override_dumptype()
{
// The current valid values are:
// 0 : Triage Dump
// 1 : Mini Dump
// 2 : Heap Dump
// Values outside this range are defaulted to 2 (Full Heap)
// This example uses Heap Dumps which give the most information
return 2;
}
```
## Código de ejemplo de ASan
Este código demuestra la facilidad con la que estas funciones pueden agregarse a una base de código existente y adaptarse según sea necesario:
```c++ theme={null}
#include
extern "C" const wchar_t* __vcasan_save_dumps()
{
// Specify dump filename
return L"myCrashDump.dmp";
}
extern "C" const signed int __vcasan_override_dumptype()
{
// Full heap dump requested
return 2;
}
static const int arraySize = 8;
static int asanArray[arraySize];
static int asanAccumulator = 0;
int main()
{
// ASan should use the callback functions that we have provided
for (int loop = 0; loop <= arraySize; loop++)
{
// We don't really care about accumulating the values
// We just want to access outside the array causing an ASan error
asanAccumulator += asanArray[loop];
}
// If we get here, we have failed as ASan should have caught the error above
printf("fail");
return 0;
}
```
Compile el código mediante esta línea de comandos:
```c++ theme={null}
cl /nologo /fsanitize=address /Zi ASanTest.cpp
```
Cuando se ejecute, este código producirá una excepción de ASan y generará un volcado de memoria según lo especificado por las funciones anteriores. Puede integrar estas funciones en su base de código existente y generar los volcados de memoria que elija cuando ASan esté habilitado.
## Problemas conocidos
* ASan de Visual Studio 2019 (16.11) no es compatible con Game OS.
* El archivo DLL de ASan no es compatible con Game OS y no se cargará con las versiones iniciales de 17.12 y 17.13. Esto está corregido a partir de 17.12.6 y 17.13.3.
* Una regresión en la compatibilidad de ASan con Game OS que provocaba un bloqueo al iniciar con Visual Studio 2022 se corrigió en 17.14.29 y, en Visual Studio 2026, en 18.4.1.
* Con el depurador, al ejecutar en XBOX, el siguiente mensaje de excepción se emitirá con una cadencia regular, pero puede ignorarse sin problemas.
```
Exception thrown at 0x00007FF8FCAAFCF6 (clang_rt.asan_dynamic-x86_64.dll) in game.exe: 0xE0736171: Access violation reading location 0x000017FF1F9E1250.
```
## Related topics
- [Visualstudio](/es/tools/tools-console/visualstudio/index.md)
- [Compatibilidad táctil y de streaming de XBOX Cloud Gaming](/es/build/core-features/common/game-streaming/index.md)
- [XR-131 Compatibilidad de modos de pantalla para Game DVR y capturas de pantalla](/es/publishing/certification/xr/xr-131.md)
- [Compatibilidad con versiones anteriores de XSAPI del XDK](/es/services/xbox-services/fundamentals/xbox-services-api/live-gs-backcompat-api.md)
- [Notas de compatibilidad del GDK con Visual Studio 2022](/es/tools/tools-console/visualstudio/vs-2022-support-notes.md)