Exceções de depuração em aplicativos .NET usando o Depurador de Instantâneo

  • Artigo

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

O depurador de instantâneo no Application Insights:

  • Monitoriza os registos gerados pelo sistema a partir da sua aplicação Web.
  • Coleta instantâneos em suas exceções de lançamento superior.
  • 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.

Aplicações e ambientes suportados

Esta seção lista os aplicativos e ambientes suportados.

Aplicações

A coleta de instantâneos está disponível para:

Ambientes

Os seguintes ambientes são suportados:

Nota

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

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

Pacotes e configurações

Permissões

Como funciona o Depurador de Instantâneo

O Depurador de Instantâneo é implementado como um processador de telemetria do Application Insights. Quando o aplicativo é executado, o processador de telemetria do Depurador de Instantâneo é 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 variáveis e de parâmetros. Os dados de instantâneo são armazenados na mesma região que o recurso do Application Insights.

Processo do depurador de instantâneo

O processo do Depurador de Instantâneo começa e termina com o TrackException método. Um instantâneo do 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 TrackExceptionarquivo .

  2. O Depurador de Instantâneo monitora as exceções à medida que elas são lançadas ao assinar o AppDomain.CurrentDomain.FirstChanceException evento.

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

    • Quando o contador atinge o ThresholdForSnapshotting valor, a ID do problema é adicionada a um plano de coleta.

    Nota

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

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

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

    • O instantâneo recebe um identificador exclusivo e a exceção é carimbada com esse identificador.

    Nota

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

  6. Depois que o FirstChanceException manipulador retorna, a exceção lançada é processada normalmente.

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

Nota

Defina IsEnabledInDeveloperMode como true se você deseja gerar instantâneos enquanto depura no Visual Studio.

Processo do Snapshot Uploader

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

  1. Cria um minidump.

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

Nota

Não podem ser carregados mais de 50 instantâneos por dia.

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

Limitações

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

  • Retenção de dados

    Os instantâneos de depuração são armazenados por 15 dias. A política de retenção de dados padrão é definida por aplicativo. Se precisar aumentar esse valor, você pode solicitar um aumento abrindo um caso de suporte no portal do Azure. Para cada instância do Application Insights, um número máximo de 50 snapshots é permitido por dia.

  • Publicar símbolos

    O Depurador de instantâneo 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 versão quando publica no Serviço de Aplicativo.

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

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    Para o Azure Compute e outros tipos, certifique-se de que os arquivos de símbolo são:

    • Na mesma pasta do aplicativo .dll principal (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 que você use Completo, Portátil ou Incorporado.

  • Compilações otimizadas

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

    No entanto, no Serviço de Aplicativo, o Depurador de Instantâneo pode desotimizar métodos de lançamento que fazem parte de seu plano de coleta.

    Gorjeta

    Instale a extensão Site do Application Insights em sua instância do Serviço de Aplicativo para obter suporte à desotimização.

Próximos passos

Habilite o depurador de instantâneo do Application Insights para seu aplicativo:

Notas de versão do Microsoft.ApplicationInsights.SnapshotCollector

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

Saiba mais sobre o Application Insights Snapshot Debugger para aplicativos .NET.

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

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.

1.4.6

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

Correções de erros

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

1.4.5

Uma liberação pontual para resolver um bug relatado pelo usuário.

Correções de erros

  • AccessViolationException corrigido ao ler alguns PDBs.

Alterações

  • Adicionado um Leiame ao pacote NuGet.
  • Atualizado msdia140.dll.

1.4.4

Uma liberação pontual para resolver bugs relatados pelo usuário.

Correções de erros

Alterações

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

1.4.3

Uma liberação pontual para resolver bugs relatados pelo usuário.

Correções de erros

1.4.2

Uma liberação pontual para resolver um bug relatado pelo usuário.

Correções de erros

Fixed ArgumentException: Os delegados devem ser do mesmo tipo.

1.4.1

Uma liberação pontual para reverter uma alteração de quebra introduzida na versão 1.4.0.

Correções de erros

Método fixo não encontrado em WebJobs.

1.4.0

Foram abordadas várias melhorias e adicionado suporte para autenticação do Microsoft Entra para ingestão do Application Insights.

Alterações

  • Redução do tamanho do pacote do Snapshot Collector em 60%, de 10,34 MB para 4,11 MB.
  • Netstandard2.0 direcionado somente no Snapshot Collector.
  • Aumentou a dependência do SDK do Application Insights para 2.15.0.
  • Adicionado de volta MinidumpWithThreadInfo ao escrever dumps.
  • Adicionado CompatibilityVersion para melhorar a sincronização entre o agente do Snapshot Collector e o Snapshot Uploader em alterações de quebra.
  • Algoritmo de nomenclatura LogFile alterado SnapshotUploader para evitar E/S de arquivo excessiva no Serviço de Aplicativo.
  • Adicionado pid, role namee process start time aos metadados de blob carregados.
  • Usado System.Diagnostics.Process no Snapshot Collector e no Snapshot Uploader.

Novas funcionalidades

Adicionada a autenticação do Microsoft Entra ao 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 liberação pontual para backport de uma correção da versão 1.4.0-pre.

Correções de erros

Corrigido ObjectDisposedException no desligamento.

1.3.7.4

Uma liberação pontual para resolver um problema descoberto no teste do cenário de anexação sem código do Serviço de Aplicativo.

Alterações

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

1.3.7.3

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

Correções de erros

  • Corrigida a descoberta de PDB na pasta wwwroot/bin, que foi quebrada quando alteramos o algoritmo de pesquisa de símbolos na versão 1.3.6.
  • Fixo barulhento ExtractWasCalledMultipleTimesException em telemetria.

1.3.7

Alterações

A netcoreapp2.0 meta de SnapshotCollector depende de Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (novamente). Essa alteração reverte o comportamento para como era antes da 1.3.5. Tentamos atualizá-lo na versão 1.3.6, mas ele quebrou alguns cenários do Serviço de Aplicativo.

Novas funcionalidades

O Snapshot Collector lê e analisa a ConnectionString variável de ambiente do APPLICATIONINSIGHTS_CONNECTION_STRING ou o TelemetryConfiguration. Principalmente, ele é usado para definir o ponto de extremidade para se conectar ao serviço de instantâneo. Para obter mais informações, consulte a documentação Cadeias de conexão.

Correções de erros

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

1.3.6

Alterações

  • SnapshotCollector agora depende de = 2.5.1 para todas as estruturas de Microsoft.ApplicationInsights>destino. Esse requisito pode ser uma alteração significativa se seu aplicativo depender de uma versão mais antiga do SDK do Microsoft.ApplicationInsights.
  • Removido o suporte para TLS 1.0 e 1.1 no Snapshot Uploader.
  • O período de verificações do PDB agora é de 24 horas em vez de 15 minutos. Configurável via PdbRescanInterval on SnapshotCollectorConfiguration.
  • A verificação do PDB pesquisa apenas pastas de nível superior, em vez de recursiva. Essa alteração pode ser uma alteração de quebra se seus símbolos estiverem em subpastas da pasta binária.

Novas funcionalidades

  • Rotação de logs para SnapshotUploader evitar encher a pasta de logs com arquivos antigos.
  • Suporte à desotimização (via ReJIT em anexo) para aplicativos .NET Core 3.0.
  • Símbolos adicionados ao pacote NuGet.
  • Defina mais metadados ao carregar minidumps.
  • Adicionada uma Initialized propriedade a SnapshotCollectorTelemetryProcessor. É um CancellationTokenarquivo , que é cancelado quando o Snapshot Collector é inicializado e conectado ao ponto de extremidade do serviço.
  • Os instantâneos agora podem ser capturados para exceções em métodos gerados dinamicamente. Um exemplo são as árvores de expressão compiladas geradas por consultas do Entity Framework.

Correções de erros

  • AmbiguousMatchException carregando o Snapshot Collector devido ao Status Monitor.
  • GetSnapshotCollector O método de extensão agora pesquisa todos os TelemetrySinksarquivos .
  • Não inicie o Snapshot Uploader em plataformas não suportadas.
  • Manipule InvalidOperationException quando estiver desotimizando métodos dinâmicos (por exemplo, Entity Framework).

1.3.5

  • Adicionado suporte para nuvens soberanas (versões mais antigas não funcionam em nuvens soberanas).
  • Adicionar o Snapshot Collector foi facilitado usando AddSnapshotCollector()o . Para obter mais informações, consulte Habilitar o depurador de instantâneo 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 não está disponível quando o sistema operacional está definido para o modo compatível com FIPS.
  • Ignore quadros do .NET Framework ao desotimizar chamadas de função. Controle esse comportamento com a definição de DeoptimizeIgnoredModules configuração.
  • Adicionada a definição de configuração que permite a DeoptimizeMethodCount desotimização de mais de uma chamada de função.

1.3.4

  • Teclas de instrumentação estruturadas permitidas.
  • Maior robustez do Snapshot Uploader. Continue a inicialização mesmo que os logs antigos do carregador não possam ser movidos.
  • Reativado o relatório de mais telemetria quando o SnapshotUploader.exe é encerrado imediatamente (foi desativado na versão 1.3.3).
  • Telemetria interna simplificada.
  • Recurso experimental: Planos de coleta do Snappoint: Adicionar snapshotOnFirstOccurence. Para obter mais informações, consulte este artigo do GitHub.

1.3.3

Corrigido o bug que fazia com que o SnapshotUploader.exe parasse de responder e não carregasse instantâneos para aplicativos .NET Core.

1.3.2

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

1.3.1

  • Removido o suporte para a coleta de instantâneos com a API RtlCloneUserProcess e suporte apenas à API PssCaptureSnapshots.
  • Aumentou de um para três o limite padrão de quantos instantâneos podem ser capturados em 10 minutos.
  • Permita que o SnapshotUploader.exe negocie TLS 1.1 e 1.2.
  • Relatado mais telemetria quando SnapshotUploader registra um aviso ou um erro.
  • Pare de tirar instantâneos quando o serviço de back-end relatar que a cota diária foi atingida (50 instantâneos por dia).
  • Adicionado check-in extra em SnapshotUploader.exe para não permitir que duas instâncias sejam executadas ao mesmo tempo.

1.3.0

Alterações

  • Para aplicativos destinados 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 mudança não será um problema para a maioria dos aplicativos. Informe-nos se essa alteração impede que você use o Snapshot Collector mais recente.
  • Use atrasos exponenciais de back-off no Snapshot Uploader ao tentar novamente carregamentos com falha.
  • Utilizar ServerTelemetryChannel (se disponível) para uma comunicação mais fiável da telemetria.
  • Use SdkInternalOperationsMonitor na conexão inicial com o serviço Depurador de Instantâneo para que o controle de dependência o ignore.
  • Telemetria melhorada em torno da ligação inicial ao Depurador de Instantâneos.
  • Relatar mais telemetria para:
    • Versão do Serviço de Aplicativo.
    • Instâncias de computação do Azure.
    • Contentores.
    • Aplicativo Azure Functions.

Correções de erros

  • Quando o intervalo de redefinição do contador de problemas estiver definido como 24 dias, interprete-o como 24 horas.
  • Corrigido um bug em que o Snapshot Uploader parava de processar novos snapshots se houvesse uma exceção ao descartar um snapshot.

1.2.3

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

1.2.2

Alterações

  • Os arquivos necessários para SnapshotUploader(64).exe agora estão incorporados como recursos na DLL principal. Isso significa que a pasta não é mais criada, o que simplifica a compilação e a implantação e reduz a SnapshotCollectorFiles desordem no Gerenciador de Soluções. Tenha cuidado ao atualizar para rever as alterações no seu .csproj ficheiro. O Microsoft.ApplicationInsights.SnapshotCollector.targets arquivo não é mais necessário.
  • A telemetria é registrada no recurso do Application Insights, mesmo que ProvideAnonymousTelemetry esteja definida como false. Essa alteração é para que possamos implementar um recurso de verificação de integridade no portal do Azure. ProvideAnonymousTelemetry afeta apenas a telemetria enviada à Microsoft para suporte e aperfeiçoamento do produto.
  • Quando TempFolder ou ShadowCopyFolder forem redirecionados para variáveis de ambiente, mantenha o coletor ocioso até que essas variáveis de ambiente sejam definidas.
  • Para aplicativos que se conectam à Internet por meio de um servidor proxy, o Snapshot Collector agora deteta automaticamente todas as configurações de proxy e as passa para o SnapshotUploader.exe.
  • Diminua a SnapshotUploader prioridade do processo (sempre que possível). Esta prioridade pode ser substituída através da IsLowPrioirtySnapshotUploader opção.
  • Adicionado um GetSnapshotCollector método de extensão para cenários em TelemetryConfiguration que você deseja configurar o Snapshot Collector programaticamente.
  • Defina a versão do SDK do Application Insights (em vez da versão do aplicativo) na telemetria voltada para o cliente.
  • Envie o primeiro evento de batimento cardíaco após dois minutos.

Correções de erros

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

1.2.1

Alterações

  • Os arquivos de comentário do documento XML agora estão incluídos no pacote NuGet.
  • Adicionado um ExcludeFromSnapshotting método de extensão para cenários em System.Exception que você sabe que tem uma exceção barulhenta e deseja evitar a criação de instantâneos para ela.
  • Adicionada uma IsEnabledWhenProfiling propriedade de configuração que assume como padrão true. Esta é uma alteração em relação às versões anteriores em que a criação de instantâneos era temporariamente desativada 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 erros

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

1.2.0

A maior mudança nesta versão (daí a mudança para um novo número de versão secundária) é uma reescrita do pipeline de criação e manipulação de snapshots. Em versões anteriores, essa funcionalidade era implementada em código nativo (ProductionBreakpoints.dll* e SnapshotHolder.exe*). A nova implementação é toda gerenciada com P/Invokes.

Para esta primeira versão usando o novo pipeline, não nos afastamos muito do comportamento original. A nova implementação permite uma melhor comunicação de erros e prepara-nos para futuras melhorias.

Outras alterações nesta versão

  • MinidumpUploader.exe foi renomeado para SnapshotUploader.exe (ou SnapshotUploader64.exe).
  • Telemetria de temporização adicionada para solicitações DeOptimize/ReOptimize.
  • Adicionada compactação gzip para uploads minidump.
  • Corrigido um problema em que os PDBs estavam bloqueados impedindo a atualização do site.
  • Registre o nome da pasta original (SnapshotCollectorFiles) ao copiar sombra.
  • Limites de memória ajustados para processos de 64 bits para evitar reinicializações do site devido ao OOM.
  • Corrigido um problema em que os instantâneos ainda eram coletados mesmo após a desativação.
  • Registre eventos de pulsação no recurso de IA do cliente.
  • Velocidade de snapshot melhorada removendo "Source" do ID do problema.

1.1.2

Alterações

  • Telemetria de uso aumentada.
  • Detete e relate a versão e o sistema operacional .NET.
  • Detete e relate 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 número de TrackException chamadas) na telemetria Heartbeat.

Correções de erros

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

1.1.0

Alterações

  • Adicionada proteção de memória do host. Esse recurso reduz o impacto na memória da máquina host.
  • Melhorou a experiência de visualização de instantâneos do portal do Azure.