> ## 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. # Suporte ao Address Sanitizer para XBOX > Suporte ao Address Sanitizer para XBOX Como a maioria dos programas C++, os jogos podem sofrer com uma classe de bugs que afetam a correção e a estabilidade do programa. Por isso, a partir do Visual Studio 2022, o compilador Microsoft C/C++ (MSVC) e o IDE dão suporte à tecnologia AddressSanitizer (ASan). Trata-se de uma tecnologia de compilador e de tempo de execução que expõe muitos bugs difíceis de encontrar, sem falsos positivos, por exemplo: * Incompatibilidades de alloc/dealloc e de tipo em new/delete * Alocações grandes demais para o heap * Estouro de calloc e estouro de alloca * Liberação dupla e uso após liberação * Estouro de variável global * Estouro de buffer do heap * Alinhamento inválido de valores alinhados * Sobreposição de parâmetros de memcpy e strncat * Estouro e estouro negativo de buffer da pilha * Uso da pilha após o retorno e uso após o escopo * Uso de memória depois de envenenada Mais informações sobre o ASan podem ser encontradas nas páginas do Visual Studio: [AddressSanitizer](https://learn.microsoft.com/cpp/sanitizers/asan) (Microsoft Docs) ## Habilitar o ASan no compilador O Address Sanitizer é integrado ao sistema de projetos do Visual Studio, ao sistema de build CMake e ao IDE. Os projetos podem habilitar o AddressSanitizer usando uma opção extra do compilador, *`/fsanitize=address`*, ou definindo uma propriedade de projeto no Visual Studio: ![Opções do compilador para ASan no Visual Studio](https://mintcdn.com/microsoft-4404708b/ktEik-YaZoen6Rhy/images/gdk/tools/Address_Sanitizer_Project_Props.png?fit=max\&auto=format\&n=ktEik-YaZoen6Rhy\&q=85\&s=1717f26cc38c6cfdc96e683cb32752c0) > [!NOTE] > > Essa opção é compatível com todos os níveis de otimização e configurações de x64. No entanto, ela é **incompatível** com `edit-and-continue`, `incremental linking` e `/RTC`, que precisam ser desabilitados antes de compilar com o ASan. Ao habilitar o ASan, é necessário vincular uma biblioteca adicional ao seu código. Essa referência é adicionada automaticamente pelo sistema de build. Isso também exige que você defina um "Additional Library Directories" em ***Linker > General*** para o seu projeto. Verifique se o valor `$(VC_LibraryPath_VC_x64)` é o último da lista para evitar que ele seja usado para outras bibliotecas, conforme mostrado abaixo: ![Opções do vinculador para ASan no Visual Studio](https://mintcdn.com/microsoft-4404708b/ktEik-YaZoen6Rhy/images/gdk/tools/Address_Sanitizer_Linker_Options.png?fit=max\&auto=format\&n=ktEik-YaZoen6Rhy\&q=85\&s=8f81ff7561ee160e16164518191f789b) ## Requisitos de tempo de execução do ASan Quando um jogo é compilado com o ASan habilitado, ele requer que uma DLL adicional esteja presente em tempo de execução para habilitar a funcionalidade. Por padrão, quando o ASan é habilitado no compilador, ele copia a DLL para o diretório de saída do seu projeto, e ela deve então ser implantada no console ao lado do executável. Se necessário, as DLLs podem ser encontradas manualmente no diretório `$(VC_ExecutablePath_x64)` do Visual Studio. O XBOX requer uma destas duas, dependendo da versão do build: | Nome do arquivo da DLL | Tipo de build | | - | - | | `clang_rt.asan_dbg_dynamic-x86_64.dll` | Builds de depuração | | `clang_rt.asan_dynamic-x86_64.dll` | Builds de versão | ## Suporte ao depurador em tempo de execução Ao executar um jogo com o ASan habilitado e um depurador anexado, se um erro for encontrado, a execução será interrompida no depurador e um relatório detalhado será exibido, permitindo determinar onde o erro ocorreu. Mas, se você estiver executando sem um depurador anexado, em uma estrutura de testes automatizados, por exemplo, as informações do erro serão exibidas na saída padrão e o jogo será encerrado. Isso pode ser útil, mas talvez você precise de mais informações de estado para encontrar a causa raiz da falha, e é aí que entra o suporte a despejos de falha. > [!NOTE] > > Se você estiver executando sem um depurador anexado e precisar que os símbolos sejam resolvidos nesse momento, será necessário implantar o arquivo `llvm-symbolizer.exe` junto com o EXE do seu jogo. Esse arquivo pode ser encontrado no mesmo local que as DLLs de tempo de execução do ASan listadas acima. ## Suporte a despejos de falha em tempo de execução A partir do Visual Studio 16.9.8 ou 16.10.2, o ASan pode ser configurado para salvar um arquivo de despejo de falha que contém os metadados associados ao erro. O depurador do Visual Studio pode analisar os metadados salvos no arquivo de despejo para fornecer mais contexto sobre a falha. Você pode configurar o salvamento desses despejos de falha por build, armazenar esses artefatos binários e depois exibi-los no IDE com a indexação de código-fonte adequada. A documentação sobre despejos de falha pode ser encontrada aqui: [Configuring Crash Dumps](https://learn.microsoft.com/cpp/sanitizers/asan-offline-crash-dumps) (Microsoft Docs) Mas a abordagem vinculada acima requer a definição de uma variável de ambiente, o que não tem suporte no XBOX, por isso foi implementado um método alternativo. Para adicionar suporte a despejos de falha ao seu título XBOX, basta definir um retorno de chamada de função que forneça ao ASan as informações de nome de arquivo do despejo de falha necessárias. Três exemplos são mostrados abaixo. > [!NOTE] > > O nome do arquivo geralmente tem o sufixo ***.dmp*** para seguir as convenções do IDE do 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; }; } ``` Não há requisitos específicos quanto ao nome retornado por essa função, mas ele precisa ser um caminho de arquivo válido no dispositivo de destino em que o código está sendo executado. Por exemplo, gravar os despejos de falha na unidade D: do console significa que eles podem ser encontrados e recuperados facilmente durante o desenvolvimento. Também adicionamos a possibilidade de alterar o tipo de despejo de falha produzido. Há casos em que um despejo simples de "Triage" é suficiente para ver a pilha de chamadas do ponto em que o processo falhou, mas, para alguns problemas, você pode precisar da memória ao redor no momento em que o problema ocorreu. Para isso, fornecemos três tipos configuráveis de despejo de falha que têm suporte na plataforma XBOX e correspondem aos tipos de despejo de falha produzidos pelo console e pelo xbWatson. > [!NOTE] > > Assim como a função anterior, essa substituição é **opcional** no XBOX, mas é altamente recomendada se você quiser usar despejos de falha para coletar informações do ASan sem um depurador anexado. Se você fornecer o nome do arquivo de despejo, mas **não** uma substituição do tipo de despejo, a geração de um despejo de falha válido no XBOX falhará. Esse retorno de chamada retorna um número para indicar o tipo de despejo necessário. Os tipos válidos são mostrados no exemplo abaixo: ```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; } ``` ## Exemplo de código do ASan Este código demonstra como essas funções podem ser facilmente adicionadas a uma base de código existente e adaptadas conforme necessário: ```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 o código por meio desta linha de comando: ```c++ theme={null} cl /nologo /fsanitize=address /Zi ASanTest.cpp ``` Quando executado, esse código lançará uma exceção do ASan e produzirá um despejo de falha conforme especificado pelas funções acima. Você pode integrar essas funções à sua base de código existente e gerar os despejos de falha que preferir quando o ASan estiver habilitado. ## Problemas conhecidos * O ASan do Visual Studio 2019 (16.11) não é compatível com o Game OS. * A DLL do ASan não é compatível com o Game OS e não será carregada nas versões iniciais do 17.12 e do 17.13. Isso foi corrigido a partir do 17.12.6 e do 17.13.3. * Uma regressão no suporte do ASan ao Game OS, que resultava em uma falha na inicialização com o Visual Studio 2022, foi corrigida no 17.14.29 e, no Visual Studio 2026, no 18.4.1. * No depurador, ao executar no XBOX, a seguinte mensagem de exceção será emitida em intervalos regulares, mas pode ser ignorada com segurança. ``` Exception thrown at 0x00007FF8FCAAFCF6 (clang_rt.asan_dynamic-x86_64.dll) in game.exe: 0xE0736171: Access violation reading location 0x000017FF1F9E1250. ``` ## Related topics - [Introdução ao Godot para desenvolvimento para XBOX](/pt-BR/build/gdk-and-engines/godot.md) - [Suporte ao teclado virtual](/pt-BR/build/core-features/common/input/overviews/virtualkeyboardsupport.md) - [Visualstudio](/pt-BR/tools/tools-console/visualstudio/index.md) - [Ferramenta Investigação de travamentos para XBOX (HIX)](/pt-BR/tools/tools-console/hix/index.md) - [Introdução ao Unity para desenvolvimento para PC (conteúdo)](/pt-BR/build/gdk-and-engines/unity/unity.md)