Diagnóstico e instrumentação

O AOT nativo compartilha alguns, mas não todos, os recursos de diagnóstico e instrumentação com o runtime completo do .NET. Aplicativos compatíveis com trim não devem ter diferenças comportamentais, portanto, as investigações geralmente se aplicam a ambos os tempos de execução. Dessa forma, às vezes é apropriado diagnosticar e depurar problemas no runtime completo do .NET, pois ele tem uma seleção avançada de utilitários de diagnóstico disponíveis. No entanto, algumas informações só podem ser coletadas após a publicação, portanto, o AOT nativo também fornece ferramentas de diagnóstico pós-publicação.

Suporte de diagnóstico AOT nativo

A tabela a seguir resume os recursos de diagnóstico com suporte para implantações de AOT nativos:

Observabilidade e telemetria

A partir do .NET 8, o runtime do AOT nativo oferece suporte a EventPipe, que é a camada base usada por muitas bibliotecas de log e rastreamento. Você pode fazer interface com o EventPipe diretamente por meio de APIs como EventSource.WriteEvent ou usar bibliotecas compiladas na parte superior, como OpenTelemetry. O suporte ao EventPipe também permite que ferramentas de diagnóstico do .NET, como dotnet-trace, dotnet-counters e dotnet-monitor , funcionem perfeitamente com AOT nativo ou aplicativos de runtime .NET completos. O EventPipe é um componente opcional no AOT nativo. Para incluir o suporte ao EventPipe, defina a propriedade MSBuild EventSourceSupport como true.

<PropertyGroup>
    <EventSourceSupport>true</EventSourceSupport>
</PropertyGroup>

O AOT nativo dá suporte parcial para alguns provedores de eventos conhecidos. Nem todos os eventos de runtime têm suporte no AOT nativo.

Diagnóstico em tempo de desenvolvimento

Ferramentas da CLI do .NET (dotnet SDK) e Visual Studio oferecem comandos separados para build e publish. build (ou Start no Visual Studio) usa o runtime completo do .NET. Somente publish cria um aplicativo AOT nativo. Publicar seu aplicativo como AOT nativo produz um aplicativo que foi compilado antecipadamente (AOT) para código nativo. Conforme mencionado anteriormente, nem todas as ferramentas de diagnóstico funcionam perfeitamente com aplicativos AOT nativos publicados no .NET 8. No entanto, todas as ferramentas de diagnóstico do .NET estão disponíveis para desenvolvedores durante o estágio de criação do aplicativo. Recomendamos desenvolver, depurar e testar os aplicativos normalmente e publicar o aplicativo funcional com AOT nativo como uma das últimas etapas.

Depuração nativa

Quando você executa seu aplicativo durante o desenvolvimento, como dentro do Visual Studio, ou com dotnet run, dotnet build, ou dotnet test, ele é executado no runtime completo do .NET por padrão. No entanto, se PublishAot estiver presente no arquivo de projeto, o comportamento deverá ser o mesmo entre o runtime completo do .NET e o AOT nativo. Essa característica permite que você use o mecanismo de depuração gerenciado padrão do Visual Studio para desenvolvimento e teste.

Após a publicação, os aplicativos AOT nativos são verdadeiros binários nativos. O depurador gerenciado não funcionará neles. No entanto, o compilador AOT nativo gera arquivos executáveis totalmente nativos que os depuradores nativos podem depurar em sua plataforma de escolha (por exemplo, WinDbg ou Visual Studio no Windows e gdb ou lldb em sistemas semelhantes ao Unix).

O compilador de AOT nativo gera informações sobre números de linha, tipos, locais e parâmetros. O depurador nativo permite inspecionar rastreamento de pilha e variáveis, entrando ou saindo de linhas de origem ou definindo pontos de interrupção de linha.

Para depurar exceções gerenciadas, defina um ponto de interrupção no método RhThrowEx, que é chamado sempre que uma exceção gerenciada é gerada. A exceção é armazenada no primeiro registro de argumento, que está rcx no x64 e x0 no Arm64. Se o depurador der suporte à exibição de objetos C++, você poderá converter o registro em S_P_CoreLib_System_Exception* para ver mais informações sobre a exceção.

A coleta de um arquivo de despejo de um aplicativo AOT nativo envolve algumas etapas manuais no .NET 8.

Notas específicas do Visual Studio

Você pode iniciar um executável compilado por AOT nativo no depurador do Visual Studio abrindo-o no IDE do Visual Studio. Você precisa abrir o executável em si no Visual Studio.

Para definir um ponto de interrupção que é interrompido sempre que uma exceção é gerada, escolha a opção Pontos de interrupção no menu Depurar > Windows. Na nova janela, selecione >. Especifique RhThrowEx como o Nome da Função e deixe a opção Idioma em Todos os Idiomas (não selecione C#).

Para ver qual exceção foi lançada, inicie a depuração (Depurar > Iniciar Depuração ou F5) e, quando o RhThrowEx ponto de interrupção for atingido, abra a janela de Inspeção (Depurar > Windows > Watch) e adicione a seguinte expressão como uma das inspeções:

Esse mecanismo utiliza o fato de que, no momento em que RhThrowEx é chamado, o registro de CPU mencionado na tabela contém a exceção lançada. Você também pode colar a expressão na Janela Imediata do Visual Studio; a sintaxe é a mesma que para relógios.

Importância do arquivo de símbolo

Ao publicar, o compilador AOT nativo produz um executável e um arquivo de símbolo. A depuração nativa e as atividades relacionadas, como a criação de perfil, exigem acesso ao arquivo de símbolo nativo. Se esse arquivo não estiver presente, você poderá ter resultados degradados ou interrompidos.

Para obter informações sobre o nome e o local do arquivo de símbolo, consulte Informações de depuração nativas.

Criação de perfil da CPU

Ferramentas específicas da plataforma, como PerfView e Perf, podem ser usadas para coletar amostras de CPU de um aplicativo AOT nativo.

Análise de heap

No momento, não há suporte para análise de heap gerenciado no AOT nativo. Ferramentas de análise de heap como dotnet-gcdump, PerfView e ferramentas de análise de heap do Visual Studio não funcionam no AOT nativo no .NET 8.

Confira também

• Suporte nativo ao diagnóstico AOT no iOS e Mac Catalyst