Pular para o conteúdo principal
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 (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
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

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:

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.
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 (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.
O nome do arquivo geralmente tem o sufixo .dmp para seguir as convenções do IDE do Visual Studio
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.
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:

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:
Compile o código por meio desta linha de comando:
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.
Última modificação em 8 de outubro de 2026