> ## 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.
# Prise en charge d'Address Sanitizer pour XBOX
> Prise en charge d'Address Sanitizer pour XBOX
Comme la plupart des programmes C++, les jeux peuvent souffrir d'une catégorie de bogues qui affectent l'exactitude et la stabilité du programme. C'est pourquoi, à partir de Visual Studio 2022, le compilateur Microsoft C/C++ (MSVC) et l'IDE prennent en charge la technologie AddressSanitizer (ASan). Il s'agit d'une technologie de compilation et d'exécution qui révèle de nombreux bogues difficiles à détecter, sans aucun faux positif, par exemple :
* Incohérences entre allocation et désallocation, et incohérences de type entre new et delete
* Allocations trop volumineuses pour le tas
* Dépassements de calloc et d'alloca
* Double libération et utilisation après libération
* Dépassement de variable globale
* Dépassement de mémoire tampon du tas
* Alignement non valide de valeurs alignées
* Chevauchement de paramètres de memcpy et strncat
* Dépassement de mémoire tampon de la pile, par excès et par défaut
* Utilisation de la pile après le retour et après la sortie de la portée
* Utilisation de mémoire après son empoisonnement
Pour plus d'informations sur ASan, consultez les pages de Visual Studio : [AddressSanitizer](https://learn.microsoft.com/cpp/sanitizers/asan) (Microsoft Docs)
## Activer ASan dans le compilateur
Address Sanitizer est intégré au système de projet de Visual Studio, au système de build CMake et à l'IDE. Les projets peuvent activer AddressSanitizer à l'aide d'une option de compilateur supplémentaire, *`/fsanitize=address`*, ou en définissant une propriété de projet dans Visual Studio :
Cette option est compatible avec tous les niveaux d'optimisation et toutes les configurations x64. Elle est toutefois **incompatible** avec `edit-and-continue`, `incremental linking` et `/RTC`, qui doivent être désactivés avant de compiler avec ASan.
L'activation d'ASan nécessite l'édition de liens d'une bibliothèque supplémentaire avec votre code. Cette référence est ajoutée automatiquement par le système de build. Vous devez également définir « Additional Library Directories » sous ***Linker > General*** pour votre projet. Veillez à ce que la
valeur `$(VC_LibraryPath_VC_x64)` soit la dernière de la liste afin qu'elle ne soit pas utilisée pour d'autres bibliothèques, comme illustré ci-dessous :
## Exigences d'exécution d'ASan
Lorsqu'un jeu est généré avec ASan activé, une DLL supplémentaire doit être présente à l'exécution pour activer la fonctionnalité. Par défaut, lorsqu'ASan est activé dans le compilateur, la DLL est copiée dans le répertoire de sortie de votre projet et doit ensuite être déployée sur la console à côté de l'exécutable.
Si nécessaire, les DLL se trouvent manuellement dans le répertoire `$(VC_ExecutablePath_x64)` de Visual Studio. XBOX nécessite l'une des deux, selon la version de build :
| Nom de fichier de la DLL | Type de build |
| - | - |
| `clang_rt.asan_dbg_dynamic-x86_64.dll` | Builds Debug |
| `clang_rt.asan_dynamic-x86_64.dll` | Builds Release |
## Prise en charge du débogueur à l'exécution
Lorsque vous exécutez un jeu avec ASan activé et qu'un débogueur est attaché, toute erreur détectée provoque un arrêt dans le débogueur et l'affichage d'un rapport détaillé qui vous permet de déterminer où l'erreur s'est produite.
En revanche, si vous exécutez le jeu sans débogueur attaché, par exemple dans une infrastructure de test automatisé, les informations d'erreur sont affichées sur la sortie standard et le jeu se termine. Cela peut être utile, mais vous aurez peut-être besoin de davantage d'informations d'état pour trouver la cause racine du plantage ; c'est là qu'intervient la prise en charge des vidages sur incident.
Si vous exécutez le jeu sans débogueur attaché et que les symboles doivent être résolus à ce moment-là, vous devez déployer le fichier `llvm-symbolizer.exe` à côté de l'EXE de votre jeu. Ce fichier se trouve au même emplacement que les DLL d'exécution d'ASan répertoriées ci-dessus.
## Prise en charge des vidages sur incident à l'exécution
À partir de Visual Studio 16.9.8 ou 16.10.2, ASan peut être configuré pour enregistrer un fichier de vidage sur incident contenant les métadonnées associées à l'erreur. Le débogueur de Visual Studio peut analyser les métadonnées enregistrées dans le fichier de vidage pour fournir davantage de contexte sur le plantage. Vous pouvez configurer cet enregistrement des vidages sur incident build par build, stocker ces artefacts binaires, puis les afficher dans l'IDE avec une indexation correcte des sources.
La documentation sur les vidages sur incident est disponible ici :
[Configuring Crash Dumps](https://learn.microsoft.com/cpp/sanitizers/asan-offline-crash-dumps) (Microsoft Docs)
Toutefois, l'approche indiquée ci-dessus nécessite de définir une variable d'environnement, ce qui n'est pas pris en charge sur XBOX ; une autre méthode a donc été implémentée. Pour ajouter la prise en charge des vidages sur incident à votre titre XBOX, il vous suffit de définir une fonction de rappel qui fournit à ASan les informations nécessaires sur le nom du fichier de vidage. Trois exemples sont présentés ci-dessous.
Le nom de fichier comporte généralement le suffixe ***.dmp***, conformément aux conventions de l'IDE 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;
};
}
```
Il n'existe aucune exigence particulière concernant le nom renvoyé par cette fonction, mais il doit s'agir d'un chemin de fichier valide sur l'appareil cible où le code s'exécute. Par exemple, l'écriture des vidages sur incident sur le lecteur D: de la console permet de les trouver et de les récupérer facilement pendant le développement.
Nous avons également ajouté la possibilité de modifier le type de vidage sur incident produit. Dans certains cas, un simple vidage « Triage » suffit pour voir la pile d'appels de l'endroit où le processus a échoué, mais pour certains problèmes, vous aurez peut-être besoin de la mémoire environnante au moment où le problème s'est produit. À cet effet, nous fournissons trois types de vidages sur incident configurables, pris en charge par la plateforme XBOX et correspondant aux types de vidages produits par la console et par xbWatson.
Comme pour la fonction précédente, cette substitution est **facultative** sur XBOX, mais elle est fortement recommandée si vous souhaitez utiliser des vidages sur incident pour collecter des informations ASan sans débogueur attaché. Si vous fournissez le nom du fichier de vidage mais **pas** de substitution du type de vidage, la génération d'un vidage sur incident valide échouera sur XBOX.
Ce rappel renvoie un nombre qui indique le type de vidage requis. Les types valides sont indiqués dans l'exemple ci-dessous :
```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;
}
```
## Exemple de code ASan
Ce code montre avec quelle facilité ces fonctions peuvent être ajoutées à une base de code existante et adaptées selon les besoins :
```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;
}
```
Compilez le code avec la ligne de commande suivante :
```c++ theme={null}
cl /nologo /fsanitize=address /Zi ASanTest.cpp
```
Lors de son exécution, ce code lève une exception ASan et produit un vidage sur incident comme spécifié par les fonctions ci-dessus. Vous pouvez intégrer ces fonctions à votre base de code existante et générer les vidages sur incident de votre choix lorsqu'ASan est activé.
## Problèmes connus
* L'ASan de Visual Studio 2019 (16.11) n'est pas compatible avec Game OS.
* La DLL ASan n'est pas compatible avec Game OS et ne parvient pas à se charger avec les versions initiales de 17.12 et de 17.13. Ce problème est corrigé à partir des versions 17.12.6 et 17.13.3.
* Une régression de la prise en charge d'ASan pour Game OS, qui entraînait un plantage au démarrage avec Visual Studio 2022, a été corrigée dans la version 17.14.29, et dans la version 18.4.1 pour Visual Studio 2026.
* Dans le débogueur, lors de l'exécution sur XBOX, le message d'exception suivant est émis à intervalles réguliers, mais peut être ignoré sans risque.
```
Exception thrown at 0x00007FF8FCAAFCF6 (clang_rt.asan_dynamic-x86_64.dll) in game.exe: 0xE0736171: Access violation reading location 0x000017FF1F9E1250.
```
## Related topics
- [Prise en charge du tactile et du streaming pour XBOX Cloud Gaming](/fr/build/core-features/common/game-streaming/index.md)
- [XtfGetDefaultAddress](/fr/reference/tools/xtf/xtfconsolemanager/methods/xtfgetdefaultaddress-xtfconsolemanager-xbox-windows-m.md)
- [Visual Studio](/fr/tools/tools-console/visualstudio/index.md)
- [XtfGetSavedConsoleAddress](/fr/reference/tools/xtf/xtfapi/functions/xtfgetsavedconsoleaddress-xtfapi-xbox-windows-m.md)
- [Langues prises en charge](/fr/publishing/game-publishing/concepts/metadata-supported-languages.md)