Depurar exceções em aplicativos .NET usando o Depurador de Instantâneos

  • Artigo

Com o Depurador de Instantâneos, você pode coletar automaticamente um instantâneo de depuração quando ocorrer uma exceção em seu aplicativo .NET dinâmico. Os instantâneos de depuração coletados mostram o estado do código-fonte e as variáveis no momento em que a exceção foi gerada.

O Depurador de Instantâneos no Application Insights:

  • Monitora os logs gerados pelo sistema do aplicativo Web.
  • Coleta instantâneos das exceções mais geradas.
  • Fornece as informações necessárias para diagnosticar problemas na produção.

Saiba mais sobre os processos do Depurador de Instantâneos e do Carregador de Instantâneos.

Aplicativos e ambientes compatíveis

Esta seção lista os aplicativos e os ambientes com suporte.

Aplicativos

Coleta de instantâneo está disponível para:

Ambientes

Os ambientes a seguir são suportados:

Observação

Não há suporte para aplicativos cliente (por exemplo, WPF, Windows Forms ou UWP).

Pré-requisitos para usar o Depurador de Instantâneos

Pacotes e configurações

Permissões

Como funciona o Depurador de Instantâneos

O Depurador de Instantâneos é implementado como um Processador de telemetria do Application Insights. Quando o aplicativo é executado, o processador de telemetria do Depurador de Instantâneos é adicionado ao pipeline de logs gerados pelo sistema do aplicativo.

Importante

Os instantâneos podem conter dados pessoais ou outras informações confidenciais em valores de variável e parâmetro. Os dados de instantâneo são armazenados na mesma região que o recurso do Application Insights.

Processo do Depurador de Instantâneos

O processo do Depurador de Instantâneos começa e termina com o método TrackException. Um instantâneo de processo é um clone suspenso do processo em execução, para que os usuários experimentem pouca ou nenhuma interrupção.

  1. Seu aplicativo lança o TrackException.

  2. O Depurador de Instantâneos monitora as exceções conforme elas são geradas assinando o evento AppDomain.CurrentDomain.FirstChanceException.

  3. Um contador é incrementado para a ID do problema.

    • Quando o contador alcançar o valor ThresholdForSnapshotting, a ID do problema será adicionada a um plano de coleta.

    Observação

    O valor mínimo padrão de ThresholdForSnapshotting é 1. Com esse valor, seu aplicativo precisa disparar a mesma exceção duas vezes antes que um instantâneo seja criado.

  4. A ID do problema do evento de exceção é computada e comparada com as IDs de problema no plano de coleção.

  5. Se houver uma correspondência entre as IDs do problema, será criado um instantâneo do processo em execução.

    • O instantâneo será atribuído a um identificador exclusivo e a exceção será marcada com esse identificador.

    Observação

    A taxa de criação de instantâneos é limitada pela configuração SnapshotsPerTenMinutesLimit. Por padrão, o limite é um instantâneo a cada 10 minutos.

  6. Depois que o manipulador FirstChanceException é retornado, a exceção gerada é processada normalmente.

  7. A exceção atinge o método TrackException novamente e é relatada ao Application Insights, juntamente com o identificador do instantâneo.

Observação

Defina IsEnabledInDeveloperMode como true se desejar gerar instantâneos durante a depuração no Visual Studio.

Processo do Carregador de Instantâneos

Enquanto o processo do Depurador de Instantâneos continua a ser executado e atende o tráfego aos usuários com pouca interrupção, o instantâneo é entregue ao processo do Carregador de Instantâneos. O Carregador de Instantâneos:

  1. Cria um minidespejo.

  2. Carrega o minidespejo no Application Insights, juntamente com qualquer arquivo de símbolo relevante (.pdb).

Observação

Não é possível carregar mais de 50 instantâneos por dia.

Se você habilitou o Depurador de Instantâneos, mas não está vendo os instantâneos, confira o Guia de solução de problemas.

Limitações

Esta seção discute as limitações do Depurador de Instantâneos.

  • Retenção de dados

    Instantâneos aprimorados são armazenados por 15 dias. Essa política de retenção de dados padrão é definida para cada aplicativo. Se for necessário aumentar esse valor, você poderá solicitar o aumento abrindo um caso de suporte no portal do Azure. Para cada instância do Application Insights, um número máximo de 50 instantâneos é permitido por dia.

  • Publicar símbolos

    O Depurador de Instantâneos requer arquivos de símbolo no servidor de produção para:

    • Decodificar variáveis
    • Fornecer uma experiência de depuração no Visual Studio

    Por padrão, o Visual Studio 2017 versões 15.2+ publica símbolos para compilações de lançamento ao publicar no Serviço de Aplicativo.

    Nas versões anteriores, você deve adicionar a seguinte linha ao arquivo .pubxml de seu perfil de publicação para que os símbolos sejam publicados no modo de versão:

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    Para a Computação do Azure e outros tipos, verifique se os arquivos de símbolo são:

    • Na mesma pasta do aplicativo principal .dll (normalmente, wwwroot/bin) ou
    • Disponível no caminho atual.

    Para obter mais informações sobre as diferentes opções de símbolo disponíveis, consulte a documentação do Visual Studio. Para obter melhores resultados, recomendamos usar Completo, Portátil ou Inserido.

  • Builds otimizados

    Em alguns casos, as variáveis locais não podem ser exibidas em builds de versão devido a otimizações aplicadas pelo compilador JIT.

    No entanto, no Serviço de Aplicativo, o Depurador de Instantâneos pode cancelar a otimização dos métodos de lançamento que fazem parte de seu plano de coleta.

    Dica

    Instale a extensão de site do Application Insights em sua instância do Serviço de Aplicativo para obter suporte de cancelamento de otimização.

Próximas etapas

Habilite o Depurador de Instantâneos do Application Insights em seu aplicativo:

Notas sobre a versão do Microsoft.ApplicationInsights.SnapshotCollector

Este seção contém as notas sobre a versão do pacote NuGet Microsoft.ApplicationInsights.SnapshotCollector para aplicativos .NET, que é usado pelo Depurador de Instantâneos do Application Insights.

Saiba mais sobre o Depurador de Instantâneos do Application Insights para aplicativos .NET.

Para obter relatórios de bugs e comentários, abra um problema no GitHub.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Faça a transição para cadeias de conexão para aproveitar as novas funcionalidades.

1.4.6

Uma versão pontual para abordar uma regressão ao usar aplicativos .NET 8.

Correções de bug

  • As exceções lançadas a partir de métodos gerados dinamicamente (por exemplo, árvores de expressão compiladas) no .NET 8 não estão sendo rastreadas corretamente. Fixo.

1.4.5

Uma versão de ponto para resolver um bug relatado pelo usuário.

Correções de bug

  • Foi corrigido o AccessViolationException durante a leitura de alguns PDBs.

Alterações

  • Adicionado um ReadMe ao pacote NuGet.
  • Atualização msdia140.dll.

1.4.4

Uma versão de ponto para resolver um bug relatado pelo usuário.

Correções de bug

Alterações

  • Mensagens de falha de verificação do PDB reduzidas de Erro para Aviso.
  • Atualização msdia140.dll.
  • Evite fazer uma conexão de serviço se o depurador estiver desabilitado por meio das configurações de extensão do site.

1.4.3

Uma versão de ponto para resolver um bug relatado pelo usuário.

Correções de bug

1.4.2

Uma versão de ponto para resolver um bug relatado pelo usuário.

Correções de bug

Corrigido ArgumentException: os delegados devem ser do mesmo tipo.

1.4.1

Uma versão de ponto para reverter uma alteração interruptiva introduzida na versão 1.4.0.

Correções de bug

Corrigido Método não encontrado no WebJobs.

1.4.0

Abordou várias melhorias e adicionou suporte para a autenticação do Microsoft Entra para ingestão do Application Insights.

Alterações

  • Tamanho do pacote do Snapshot Collector reduzido em 60%, de 10,34 MB para 4,11 MB.
  • Netstandard2.0 direcionado apenas no Snapshot Collector.
  • Dependência do SDK do Application Insights aumentada para 2.15.0.
  • Adicionado de volta MinidumpWithThreadInfo ao gravar despejos.
  • Adicionado CompatibilityVersion para melhorar a sincronização entre o agente do Snapshot Collector e o Snapshot Uploader em alterações de última hora.
  • Algoritmo de nomenclatura de LogFile SnapshotUploader alterado para evitar E/S excessiva de arquivo no Serviço de Aplicativo.
  • Adicionados pid, role name e process start time aos metadados de blob carregados.
  • Uso de System.Diagnostics.Process no Snapshot Collector e no Snapshot Uploader.

Novos recursos

Adição da autenticação do Microsoft Entra para SnapshotCollector. Para saber mais sobre a autenticação do Microsoft Entra no Application Insights, consulte Autenticação do Microsoft Entra para Application Insights.

1.3.7.5

Uma versão pontual para fazer o backport de uma correção do 1.4.0-pre.

Correções de bug

Corrigido ObjectDisposedException no desligamento.

1.3.7.4

Uma versão pontual para resolver um problema descoberto em testes de cenário de anexação sem código do Serviço de Aplicativo.

Alterações

O destino netcoreapp3.0 agora depende de Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (anteriormente >= 2.1.2).

1.3.7.3

Uma versão pontual para resolver alguns problemas de alto impacto.

Correções de bug

  • Corrigida a descoberta de PDB na pasta wwwroot/bin, que estava quebrada quando alteramos o algoritmo de pesquisa de símbolos na versão 1.3.6.
  • Corrigido ruído ExtractWasCalledMultipleTimesException na telemetria.

1.3.7

Alterações

O destino netcoreapp2.0 do SnapshotCollector depende de Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (novamente). Essa alteração reverte o comportamento anterior à versão 1.3.5. Tentamos atualizar isso na versão 1.3.6, mas a atualização interrompeu alguns cenários do Serviço de Aplicativo.

Novos recursos

O Snapshot Collector lê e analisa o ConnectionString da variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING ou da TelemetryConfiguration. Basicamente, isso é usado para definir o ponto de extremidade para conexão com o serviço de Instantâneo. Para obter mais informações, confira a Documentação de cadeias de conexão.

Correções de bug

Alterado para uso HttpClient em todos os destinos, exceto net45 porque WebRequest estava falhando em alguns ambientes devido a um SecurityProtocol incompatível (requer TLS 1.2).

1.3.6

Alterações

  • SnapshotCollector agora depende de Microsoft.ApplicationInsights>= 2.5.1 para todas as estruturas de destino. Esse requisito pode ser uma alteração interruptiva se seu aplicativo depender de uma versão mais antiga do SDK Microsoft.ApplicationInsights.
  • Removido o suporte para TLS 1.0 e 1.1 no Snapshot Uploader.
  • O período padrão de exames de PDB agora é 24 horas em vez de 15 minutos. Configurável por meio de PdbRescanInterval em SnapshotCollectorConfiguration.
  • O exame de PDB pesquisa somente pastas de nível superior, em vez de recursivas. Essa pode ser uma alteração interruptiva se os símbolos estiverem em subpastas da pasta binária.

Novos recursos

  • Rotação de log no SnapshotUploader para evitar o preenchimento da pasta de logs com arquivos antigos.
  • Suporte à desotimização (por meio do ReJIT em anexo) para aplicativos .NET Core 3.0.
  • Símbolos adicionados ao pacote NuGet.
  • Defina mais metadados ao carregar minidespejos.
  • Adicionada uma propriedade Initialized a SnapshotCollectorTelemetryProcessor. Trata-se de um CancellationToken, que será cancelado quando o Snapshot Collector estiver inicializado e conectado ao ponto de extremidade de serviço.
  • Captura de instantâneos para exceções em métodos gerados dinamicamente. Um exemplo são as árvores de expressão compiladas geradas pelas consultas do Entity Framework.

Correções de bug

  • AmbiguousMatchException carregando o Snapshot Collector devido ao Status Monitor.
  • O método de extensão GetSnapshotCollector agora pesquisa todos os TelemetrySinks.
  • O Carregador de Instantâneos não é iniciado em plataformas sem suporte.
  • Manuseie InvalidOperationException ao cancelar a otimização de métodos dinâmicos (por exemplo, o Entity Framework).

1.3.5

  • Adicionado suporte para nuvens soberanas (versões mais antigas não funcionam em nuvens soberanas).
  • A adição do Snapshot Collector facilitou o uso de AddSnapshotCollector(). Para obter mais informações, confira Habilitar o Depurador de Instantâneos para aplicativos .NET no Serviço de Aplicativo do Azure.
  • Use a configuração FISMA MD5 para verificar blocos de blob. Essa configuração evita o algoritmo de criptografia .NET MD5 padrão, que fica indisponível quando o sistema operacional está definido para o modo compatível com FIPS.
  • Ignora os quadros do .NET Framework ao desotimizar as chamadas de função. Controle esse comportamento com a definição de configuração DeoptimizeIgnoredModules.
  • Adicionada a definição de configuração DeoptimizeMethodCount, que permite o cancelamento de otimização de mais de uma chamada de função.

1.3.4

  • Chaves de instrumentação estruturadas permitidas.
  • Maior robustez do Snapshot Uploader. Continue a inicialização mesmo se os logs antigos do carregador não puderem ser movidos.
  • Reabilita o relatório de telemetria adicional quando SnapshotUploader.exe sai imediatamente (foi desabilitado em 1.3.3).
  • Telemetria interna simplificada.
  • Recurso experimental: planos de coleta do Snappoint. Adicione snapshotOnFirstOccurence. Para obter mais informações, confira este artigo do GitHub.

1.3.3

Corrigido o bug que estava fazendo o SnapshotUploader.exe parar de responder e não carregar instantâneos de aplicativos do .NET Core.

1.3.2

  • Recurso experimental: planos de coleta do Snappoint. Para obter mais informações, confira este artigo do GitHub.
  • O SnapshotUploader.exe sai quando o runtime descarrega o AppDomain do qual SnapshotCollector é carregado, em vez de aguardar a saída do processo. Essa ação aprimora a confiabilidade do coletor hospedado no IIS.
  • Configuração adicionada para permitir que várias instâncias SnapshotCollector que usam a mesma chave de instrumentação compartilhem o mesmo processo SnapshotUploader: ShareUploaderProcess (o padrão é true).
  • Mais telemetria relatada quando SnapshotUploader.exe é encerrado imediatamente.
  • Reduzido o número de arquivos de suporte necessários para o SnapshotUploader.exe gravar no disco.

1.3.1

  • Suporte removido para coletar instantâneos com a API do RtlCloneUserProcess e dá suporte apenas à API do PssCaptureSnapshots.
  • Aumentado o limite padrão da quantidade de instantâneos que podem ser capturados em 10 minutos de um para três.
  • Permite que o SnapshotUploader.exe negocie o TLS 1.1 e 1.2.
  • Mais telemetria relatada quando SnapshotUploader registra um aviso ou um erro.
  • Para de fazer instantâneos quando o serviço de back-end relata que a cota diária foi atingida (50 instantâneos por dia).
  • Adicionada verificação extra em SnapshotUploader.exe para não permitir que duas instâncias sejam executadas ao mesmo tempo.

1.3.0

Alterações

  • Para os aplicativos direcionados ao .NET Framework, o Snapshot Collector agora depende do Microsoft.ApplicationInsights versão 2.3.0 ou posterior. Costumava ser 2.2.0 ou posterior. Acreditamos que essa alteração não será um problema para a maioria dos aplicativos. Informe-nos se essa alteração o impedir de usar o Snapshot Collector mais recente.
  • Uso de atrasos de retirada exponencial no Carregador de Instantâneos ao repetir carregamentos com falha.
  • Use ServerTelemetryChannel (se disponível) para relatórios de telemetria mais confiáveis.
  • Use SdkInternalOperationsMonitor na conexão inicial com o serviço de Depurador de Instantâneos para que o acompanhamento de dependência o ignore.
  • Telemetria aprimorada em torno da conexão inicial com o Depurador de Instantâneos.
  • Relatar mais telemetria para:
    • Versão do Serviço de Aplicativo.
    • Instâncias de Computação do Azure.
    • Contêineres.
    • Aplicativo Azure Functions.

Correções de bug

  • Quando o intervalo de redefinição do contador de problemas for definido como 24 dias, vai ser interpretado como 24 horas.
  • Corrigido o bug que fazia o Carregador de Instantâneos interromper o processamento de novos instantâneos caso houvesse uma exceção ao descartar um instantâneo.

1.2.3

Corrigido a assinatura de nome forte com binários do Snapshot Uploader.

1.2.2

Alterações

  • Os arquivos necessários para o SnapshotUploader(64).exe agora estão inseridos como recursos na DLL principal. Isso significa que a pasta SnapshotCollectorFiles não foi mais criada, o que simplifica a criação e a implantação e reduz a confusão no Gerenciador de Soluções. Cuidado ao atualizar para revisar as alterações em seu arquivo .csproj. O arquivo Microsoft.ApplicationInsights.SnapshotCollector.targets não é mais necessário.
  • A telemetria será registrada no recurso do Application Insights mesmo se ProvideAnonymousTelemetry estiver definido como false. Essa alteração serve para implementar um recurso de verificação de integridade no portal do Azure. O ProvideAnonymousTelemetry afeta apenas a telemetria enviada à Microsoft para suporte e aperfeiçoamento do produto.
  • Quando o TempFolder ou ShadowCopyFolder forem redirecionados para as variáveis de ambiente, mantenha o coletor ocioso até que essas variáveis sejam definidas.
  • Para aplicativos que se conectam à Internet por meio de um servidor proxy, o Snapshot Collector agora detecta automaticamente quaisquer configurações de proxy e as passa para SnapshotUploader.exe.
  • Diminua a prioridade do processo SnapshotUploader (quando possível). Essa prioridade pode ser substituída por meio da opção IsLowPrioirtySnapshotUploader.
  • Adicionado um método de extensão GetSnapshotCollector em TelemetryConfiguration para cenários em que você deseja configurar o Snapshot Collector de maneira programática.
  • Definição da versão do SDK do Application Insights (em vez da versão do aplicativo) na telemetria voltada para o cliente.
  • Envio do primeiro evento de pulsação após dois minutos.

Correções de bug

  • Corrigido NullReferenceException quando as exceções tiverem dicionários de dados nulos ou imutáveis.
  • No carregador, tente a correspondência de PDB algumas vezes se for obtida uma violação de compartilhamento.
  • Corrige a telemetria duplicada quando mais de um thread chama o pipeline de telemetria na inicialização.

1.2.1

Alterações

  • Os arquivos de comentário da documentação XML agora estão incluídos no pacote NuGet.
  • Adicionado o método de extensão ExcludeFromSnapshotting no System.Exception para cenários onde há uma exceção ruidosa e deseja-se evitar a criação de instantâneos para ela.
  • Adicionada uma propriedade de configuração IsEnabledWhenProfiling cujo padrão é true. Essa é uma alteração de versões anteriores em que a criação de instantâneo seria temporariamente desabilitada se o Application Insights Profiler estivesse executando uma coleção detalhada. O comportamento antigo pode ser recuperado definindo essa propriedade como false.

Correções de bug

  • Assine SnapshotUploader64.exe corretamente.
  • Protege contra a inicialização dupla do processador de telemetria.
  • Impede o registro em log duplo de telemetria em aplicativos com vários pipelines.
  • Corrigido um bug do tempo de expiração de um plano de coleta que poderia impedir a criação de instantâneos após 24 horas.

1.2.0

A maior alteração nessa versão (por isso, a mudança para um novo número de versão secundária) é uma regeneração do pipeline de criação e manipulação de instantâneos. Em versões anteriores, essa funcionalidade foi implementada em código nativo (ProductionBreakpoints.dll* e SnapshotHolder.exe*). A nova implementação é inteira de código gerenciado com P/Invokes.

Essa primeira versão usando o novo pipeline não é muito diferente do comportamento original. A nova implementação permite um melhor de erros melhor e prepara para aprimoramentos futuros.

Outras alterações nessa versão

  • O MinidumpUploader.exe foi renomeado como SnapshotUploader.exe (ou SnapshotUploader64.exe).
  • A telemetria de tempo foi adicionada para as solicitações de desotimização/reotimização.
  • A compactação Gzip foi adicionada para os carregamentos de minidespejo.
  • Foi corrigido um problema que fazia com que os PDBs fossem bloqueados impedindo a atualização do site.
  • Foi feito o registro do nome da pasta original (SnapshotCollectorFiles) ao copiar a sombra.
  • Foram ajustados os limites de memória para processos de 64 bits para evitar reinicializações de site devido a OOM.
  • Corrigido um problema que fazia com que os instantâneos continuassem sendo coletados mesmo após a desabilitação.
  • Foi feito o registro de eventos de pulsação no recurso de IA do cliente.
  • Velocidade de snapshot aprimorada removendo "Source" do ID do problema.

1.1.2

Alterações

  • Telemetria de uso aumentada.
  • Detecção e relatório do sistema operacional e versão do .NET.
  • Detectar e relatar mais ambientes do Azure (Serviços de Nuvem do Azure, Azure Service Fabric).
  • Registre e relate métricas de exceção (número de exceções de primeira chance e o número de chamadas TrackException) na telemetria de pulsação.

Correções de bug

  • Tratamento correto do SqlException em que a exceção interna (Win32Exception) não é lançada.
  • Espaços à direita cortados em pastas de símbolos, o que causava uma análise incorreta dos argumentos de linha de comando para o arquivo MinidumpUploader.
  • Impediu a repetição infinita de conexões com falha para o ponto de extremidade do agente do Depurador de Instantâneos.

1.1.0

Alterações

  • Adicionada a proteção de memória do host. Esse recurso reduz o impacto na memória do computador host.
  • Melhorada a experiência de visualização do instantâneo do portal do Azure.