Eseguire il debug di eccezioni nelle applicazioni .NET usando snapshot debugger

  • Articolo

Con Snapshot Debugger è possibile raccogliere automaticamente uno snapshot di debug quando si verifica un'eccezione nell'applicazione .NET attiva. Gli snapshot di debug raccolti mostrano lo stato del codice sorgente e delle variabili al momento in cui è stata generata l'eccezione.

Snapshot Debugger in Application Insights:

  • Monitora i log generati dal sistema dall'app Web.
  • Raccoglie gli snapshot sulle eccezioni che generano in primo piano.
  • Fornisce informazioni necessarie per diagnosticare i problemi nell'ambiente di produzione.

Altre informazioni sui processi Snapshot Debugger e Snapshot Uploader.

Applicazioni e ambienti supportati

Questa sezione elenca le applicazioni e gli ambienti supportati.

Applicazioni

La raccolta di snapshot è disponibile per:

Ambienti

Sono supportati i seguenti ambienti:

Nota

Le applicazioni client ,ad esempio WPF, Windows Form o UWP, non sono supportate.

Prerequisiti per l'uso di Snapshot Debugger

Pacchetti e configurazioni

Autorizzazioni

  • Verificare di essere stati aggiunti al ruolo Snapshot Debugger di Application Insights per lo snapshot di Application Insights di destinazione.

Come funziona Snapshot Debugger

Snapshot Debugger viene implementato come processore di telemetria di Application Insights. Quando l'applicazione viene eseguita, il processore di telemetria snapshot debugger viene aggiunto alla pipeline dei log generati dal sistema dell'applicazione.

Importante

Gli snapshot possono contenere dati personali o altre informazioni riservate nei valori delle variabili e dei parametri. I dati snapshot vengono archiviati nella stessa area della risorsa di Application Insights.

Processo del debugger di snapshot

Il processo snapshot debugger viene avviato e termina con il TrackException metodo . Uno snapshot del processo è un clone sospeso del processo in esecuzione, in modo che gli utenti non verifichino interruzioni minime.

  1. L'applicazione genera l'eccezione TrackException.

  2. Snapshot Debugger monitora le eccezioni man mano che vengono generate sottoscrivendo l'evento AppDomain.CurrentDomain.FirstChanceException .

  3. Un contatore viene incrementato per l'ID problema.

    • Quando il contatore raggiunge il ThresholdForSnapshotting valore, l'ID problema viene aggiunto a un piano di raccolta.

    Nota

    Il ThresholdForSnapshotting valore minimo predefinito è 1. Con questo valore, l'app deve attivare la stessa eccezione due volte prima che venga creato uno snapshot.

  4. L'ID problema dell'evento di eccezione viene calcolato e confrontato con gli ID problema nel piano di raccolta.

  5. Se esiste una corrispondenza tra GLI ID problema, viene creato uno snapshot del processo in esecuzione.

    • Allo snapshot viene assegnato un identificatore univoco e l'eccezione viene contrassegnata con tale identificatore.

    Nota

    La frequenza di creazione dello snapshot è limitata dall'impostazione SnapshotsPerTenMinutesLimit. Per impostazione predefinita, il limite è uno snapshot ogni 10 minuti.

  6. Al termine della restituzione del FirstChanceException gestore, l'eccezione generata viene elaborata come di consueto.

  7. L'eccezione raggiunge di nuovo il TrackException metodo e viene segnalata ad Application Insights, insieme all'identificatore dello snapshot.

Nota

Impostare IsEnabledInDeveloperMode su true se si desidera generare snapshot durante il debug in Visual Studio.

Processo di caricamento snapshot

Mentre il processo snapshot debugger continua a essere eseguito e gestisce il traffico agli utenti con poca interruzione, lo snapshot viene passato al processo di caricamento snapshot. Lo snapshot uploader:

  1. Crea un minidump.

  2. Carica il minidump in Application Insights, insieme a tutti i file di simboli pertinenti (con estensione pdb).

Nota

Non è possibile caricare più di 50 snapshot al giorno.

Se è stato abilitato snapshot debugger ma non vengono visualizzati gli snapshot, vedere la guida alla risoluzione dei problemi.

Limiti

In questa sezione vengono illustrate le limitazioni per snapshot debugger.

  • Conservazione dei dati

    Gli snapshot di debug vengono archiviati per 15 giorni. I criteri di conservazione dei dati predefiniti vengono impostati per ogni applicazione. Se è necessario aumentare questo valore, è possibile richiedere un aumento aprendo un caso di supporto nel portale di Azure. Per ogni istanza di Application Insights, è consentito un numero massimo di 50 snapshot al giorno.

  • Pubblicare simboli

    Snapshot Debugger richiede file di simboli nel server di produzione per:

    • Decodificare le variabili
    • Offrire un'esperienza di debug in Visual Studio

    Per impostazione predefinita, Visual Studio 2017 versione 15.2+ pubblica i simboli per le build di rilascio quando viene pubblicato in servizio app.

    Nelle versioni precedenti è necessario aggiungere la riga seguente al file del profilo di pubblicazione .pubxml in modo che i simboli vengano pubblicati in modalità di rilascio:

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    Per Calcolo di Azure e altri tipi, assicurarsi che i file di simboli siano i seguenti:

    • Nella stessa cartella dell'applicazione .dll principale (in genere, wwwroot/bin) o
    • Disponibile nel percorso corrente.

    Per altre informazioni sulle diverse opzioni di simboli disponibili, vedere la documentazione di Visual Studio. Per ottenere risultati ottimali, è consigliabile usare Full, Portable o Embedded.

  • Compilazioni ottimizzate

    In alcuni casi, le variabili locali non possono essere visualizzate nelle build di versione a causa delle ottimizzazioni applicate dal compilatore JIT.

    Tuttavia, in servizio app, snapshot debugger può deoptimizzare i metodi che fanno parte del piano di raccolta.

    Suggerimento

    Installare l'estensione del sito di Application Insights nell'istanza di servizio app per ottenere supporto per la deoptimizzazione.

Passaggi successivi

Abilitare il debugger snapshot di Application Insights per l'applicazione:

Note sulla versione per Microsoft.ApplicationInsights.SnapshotCollector

Questa sezione contiene le note sulla versione per il Microsoft.ApplicationInsights.SnapshotCollector pacchetto NuGet per le applicazioni .NET, che viene usato dal debugger di snapshot di Application Insights.

Altre informazioni sul debugger snapshot di Application Insights per le applicazioni .NET.

Per i report sui bug e il feedback, aprire un problema in GitHub.

Nota

Il 31 marzo 2025, il supporto per l'inserimento delle chiavi di strumentazione terminerà. L'inserimento di chiavi di strumentazione continuerà a funzionare, ma non forniamo più aggiornamenti o supporto per la funzionalità. Passare alle stringa di connessione per sfruttare le nuove funzionalità.

1.4.6

Rilascio punto per risolvere una regressione quando si usano applicazioni .NET 8.

Correzioni di bug

  • Le eccezioni generate dai metodi generati dinamicamente (ad esempio, alberi delle espressioni compilate) in .NET 8 non vengono rilevate correttamente. Fisso.

1.4.5

Versione punto per risolvere un bug segnalato dall'utente.

Correzioni di bug

  • Correzione di AccessViolationException durante la lettura di alcuni PDB.

Modifiche

  • Aggiunta di un file ReadMe al pacchetto NuGet.
  • Aggiornamento msdia140.dll.

1.4.4

Rilascio punto per risolvere i bug segnalati dall'utente.

Correzioni di bug

Modifiche

  • Messaggi di errore di analisi PDB inferiori da Errore a Avviso.
  • Aggiornamento msdia140.dll.
  • Evitare di stabilire una connessione al servizio se il debugger è disabilitato tramite le impostazioni dell'estensione del sito.

1.4.3

Rilascio punto per risolvere i bug segnalati dall'utente.

Correzioni di bug

1.4.2

Versione punto per risolvere un bug segnalato dall'utente.

Correzioni di bug

Fixed ArgumentException: i delegati devono essere dello stesso tipo.

1.4.1

Versione punto per ripristinare una modifica di rilievo introdotta nella versione 1.4.0.

Correzioni di bug

Metodo risolto non trovato nei processi Web.

1.4.0

Sono stati risolti più miglioramenti e è stato aggiunto il supporto per l'autenticazione di Microsoft Entra per l'inserimento di Application Insights.

Modifiche

  • Riduzione delle dimensioni del pacchetto dell'agente di raccolta snapshot del 60% da 10,34 MB a 4,11 MB.
  • Netstandard2.0 di destinazione solo nell'agente di raccolta snapshot.
  • Dipendenza dell'SDK di Application Insights alla versione 2.15.0.
  • Aggiunto di nuovo MinidumpWithThreadInfo durante la scrittura di dump.
  • Aggiunta CompatibilityVersion per migliorare la sincronizzazione tra l'agente di raccolta snapshot e lo snapshot Uploader in caso di modifiche di rilievo.
  • Modificato SnapshotUploader l'algoritmo di denominazione LogFile per evitare un numero eccessivo di I/O di file in servizio app.
  • Aggiunta piddi , role namee process start time ai metadati del BLOB caricati.
  • Usato System.Diagnostics.Process nell'agente di raccolta snapshot e nello snapshot uploader.

Nuove funzionalità

Aggiunta dell'autenticazione di Microsoft Entra a SnapshotCollector. Per altre informazioni sull'autenticazione di Microsoft Entra in Application Insights, vedere Autenticazione di Microsoft Entra per Application Insights.

1.3.7.5

Una versione punto per eseguire il backport di una correzione dalla versione 1.4.0-pre.

Correzioni di bug

Correzione di ObjectDisposedException all'arresto.

1.3.7.4

Rilascio punto per risolvere un problema individuato durante il test dello scenario di collegamento senza codice servizio app.

Modifiche

La netcoreapp3.0 destinazione dipende ora da Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (in precedenza >= 2.1.2).

1.3.7.3

Una versione punto per risolvere un paio di problemi ad alto impatto.

Correzioni di bug

  • Correzione dell'individuazione PDB nella cartella wwwroot/bin , che è stata interrotta quando è stato modificato l'algoritmo di ricerca dei simboli nella versione 1.3.6.
  • Correzione del disturbo ExtractWasCalledMultipleTimesException nei dati di telemetria.

1.3.7

Modifiche

La netcoreapp2.0 destinazione di SnapshotCollector dipende da Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (di nuovo). Questa modifica ripristina il comportamento di come era precedente alla versione 1.3.5. Si è tentato di aggiornarlo nella versione 1.3.6, ma si sono interrotti alcuni scenari di servizio app.

Nuove funzionalità

Snapshot Collector legge e analizza dalla ConnectionString variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING o da TelemetryConfiguration. Viene usato principalmente per impostare l'endpoint per la connessione al servizio Snapshot. Per altre informazioni, vedere la documentazione delle stringhe di Connessione ion.

Correzioni di bug

Passa all'uso HttpClient di per tutte le destinazioni, ad eccezione net45 del fatto che WebRequest si è verificato un errore in alcuni ambienti a causa di un errore incompatibile SecurityProtocol (richiede TLS 1.2).

1.3.6

Modifiche

  • SnapshotCollector ora dipende da Microsoft.ApplicationInsights>= 2.5.1 per tutti i framework di destinazione. Questo requisito potrebbe essere una modifica che causa un'interruzione se l'applicazione dipende da una versione precedente di Microsoft.ApplicationInsights SDK.
  • Rimozione del supporto per TLS 1.0 e 1.1 in Snapshot Uploader.
  • Il periodo di analisi PDB ora usa 24 ore invece di 15 minuti. Configurabile tramite PdbRescanInterval in SnapshotCollectorConfiguration.
  • L'analisi PDB cerca solo le cartelle di primo livello, anziché ricorsive. Questa modifica potrebbe essere un'interruzione se i simboli si trovano in sottocartelle della cartella binaria.

Nuove funzionalità

  • Rotazione dei log in SnapshotUploader per evitare di riempire la cartella dei log con i file precedenti.
  • Supporto della deoptimizzazione (tramite ReJIT sul collegamento) per le applicazioni .NET Core 3.0.
  • Aggiunta di simboli al pacchetto NuGet.
  • Impostare più metadati quando si caricano minidump.
  • Aggiunta di una Initialized proprietà a SnapshotCollectorTelemetryProcessor. Si tratta di un CancellationTokenoggetto che viene annullato quando l'agente di raccolta snapshot viene inizializzato e connesso all'endpoint del servizio.
  • Gli snapshot possono ora essere acquisiti per le eccezioni nei metodi generati dinamicamente. Un esempio è costituito dagli alberi delle espressioni compilati generati dalle query di Entity Framework.

Correzioni di bug

  • AmbiguousMatchException caricamento dell'agente di raccolta snapshot a causa di Status Monitor.
  • GetSnapshotCollector Il metodo di estensione ora esegue la ricerca in tutti i TelemetrySinks.
  • Non avviare lo snapshot uploader su piattaforme non supportate.
  • Gestire InvalidOperationException quando si deoptimino i metodi dinamici, ad esempio Entity Framework.

1.3.5

  • Aggiunta del supporto per i cloud sovrani (le versioni precedenti non funzionano nei cloud sovrani).
  • Aggiunta dell'agente di raccolta snapshot semplificata tramite AddSnapshotCollector(). Per altre informazioni, vedere Abilitare Snapshot Debugger per le app .NET nel servizio app Azure.
  • Usare l'impostazione FISMA MD5 per verificare i blocchi BLOB. Questa impostazione evita l'algoritmo di crittografia .NET MD5 predefinito, che non è disponibile quando il sistema operativo è impostato sulla modalità conforme a FIPS.
  • Ignorare i frame di .NET Framework durante la deoptimizzazione delle chiamate di funzione. Controllare questo comportamento con l'impostazione di DeoptimizeIgnoredModules configurazione.
  • Aggiunta dell'impostazione DeoptimizeMethodCount di configurazione che consente la deoptimizzazione di più chiamate di funzione.

1.3.4

  • Chiavi di strumentazione strutturate consentite.
  • Maggiore affidabilità dell'utilità di caricamento snapshot. Continuare l'avvio anche se non è possibile spostare i log del caricatore precedente.
  • È stata ricreata la segnalazione di più dati di telemetria quando SnapshotUploader.exe viene chiusa immediatamente (è stata disabilitata nella versione 1.3.3).
  • Telemetria interna semplificata.
  • Funzionalità sperimentale: Piani di raccolta snappoint: Aggiungere snapshotOnFirstOccurence. Per altre informazioni, vedere questo articolo su GitHub.

1.3.3

Correzione di un bug che causava SnapshotUploader.exe interrompere la risposta e non caricare snapshot per le app .NET Core.

1.3.2

  • Funzionalità sperimentale: piani di raccolta snappoint. Per altre informazioni, vedere questo articolo su GitHub.
  • SnapshotUploader.exe viene chiuso quando il runtime scarica l'oggetto AppDomain da cui SnapshotCollector viene caricato, anziché attendere l'uscita del processo. Questa azione migliora l'affidabilità dell'agente di raccolta quando è ospitata in IIS.
  • Aggiunta della configurazione per consentire a più SnapshotCollector istanze che usano la stessa chiave di strumentazione di condividere lo stesso SnapshotUploader processo: ShareUploaderProcess (per impostazione predefinita è true).
  • Sono stati segnalati altri dati di telemetria quando SnapshotUploader.exe viene chiuso immediatamente.
  • Riduzione del numero di file di supporto SnapshotUploader.exe necessario scrivere su disco.

1.3.1

  • Rimosso il supporto per la raccolta di snapshot con l'API RtlCloneUserProcess e supporta solo l'API PssCaptureSnapshots.
  • È stato aumentato il limite predefinito per il numero di snapshot che è possibile acquisire in 10 minuti da uno a tre.
  • Consentire SnapshotUploader.exe di negoziare TLS 1.1 e 1.2.
  • Sono stati segnalati altri dati di telemetria quando SnapshotUploader si registra un avviso o un errore.
  • Interrompere l'acquisizione di snapshot quando il servizio back-end segnala che è stata raggiunta la quota giornaliera (50 snapshot al giorno).
  • Aggiunta di un controllo aggiuntivo SnapshotUploader.exe per non consentire l'esecuzione di due istanze contemporaneamente.

1.3.0

Modifiche

  • Per le applicazioni destinate a .NET Framework, l'agente di raccolta snapshot dipende ora da Microsoft.ApplicationInsights versione 2.3.0 o successiva. Era 2.2.0 o versione successiva. Riteniamo che questa modifica non sia un problema per la maggior parte delle applicazioni. Segnalare se questa modifica impedisce l'uso dell'agente di raccolta snapshot più recente.
  • Usare ritardi di back-off esponenziali nel caricamento snapshot quando si ritentano caricamenti non riusciti.
  • Usare ServerTelemetryChannel (se disponibile) per la creazione di report di telemetria più affidabili.
  • Usare SdkInternalOperationsMonitor nella connessione iniziale al servizio Snapshot Debugger in modo che il rilevamento delle dipendenze lo ignori.
  • Sono stati migliorati i dati di telemetria relativi alla connessione iniziale a Snapshot Debugger.
  • Segnalare altri dati di telemetria per:
    • servizio app versione.
    • Istanze di calcolo di Azure.
    • Contenitori.
    • Funzioni di Azure'app.

Correzioni di bug

  • Quando l'intervallo di reimpostazione del contatore del problema è impostato su 24 giorni, interpretarlo come 24 ore.
  • Correzione di un bug per cui il caricamento snapshot interrompeva l'elaborazione di nuovi snapshot se si verificava un'eccezione durante l'eliminazione di uno snapshot.

1.2.3

Correzione della firma con nome sicuro con i file binari di Snapshot Uploader.

1.2.2

Modifiche

  • I file necessari per SnapshotUploader(64).exe sono ora incorporati come risorse nella DLL principale. Ciò significa che la SnapshotCollectorFiles cartella non viene più creata, che semplifica la compilazione e la distribuzione e riduce il disordine in Esplora soluzioni. Prestare attenzione quando si esegue l'aggiornamento per esaminare le modifiche nel .csproj file. Il Microsoft.ApplicationInsights.SnapshotCollector.targets file non è più necessario.
  • La telemetria viene registrata nella risorsa di Application Insights anche se ProvideAnonymousTelemetry è impostata su false. Questa modifica consente di implementare una funzionalità di controllo integrità nel portale di Azure. ProvideAnonymousTelemetry influisce solo sui dati di telemetria inviati a Microsoft per il supporto e il miglioramento del prodotto.
  • Quando TempFolder o ShadowCopyFolder vengono reindirizzati alle variabili di ambiente, mantenere inattiva l'agente di raccolta fino a quando tali variabili di ambiente non vengono impostate.
  • Per le applicazioni che si connettono a Internet tramite un server proxy, Snapshot Collector ora rileva automaticamente tutte le impostazioni proxy e le passa a SnapshotUploader.exe.
  • Abbassare la priorità del SnapshotUploader processo (laddove possibile). Questa priorità può essere sostituita tramite l'opzione IsLowPrioirtySnapshotUploader .
  • È stato aggiunto un GetSnapshotCollector metodo di estensione per TelemetryConfiguration gli scenari in cui si vuole configurare l'agente di raccolta snapshot a livello di codice.
  • Impostare la versione di Application Insights SDK (anziché la versione dell'applicazione) nei dati di telemetria rivolti ai clienti.
  • Inviare il primo evento heartbeat dopo due minuti.

Correzioni di bug

  • Correzione NullReferenceException quando le eccezioni hanno dizionari dati null o non modificabili.
  • Nel caricatore ritentare la corrispondenza PDB alcune volte se si verifica una violazione di condivisione.
  • Correggere i dati di telemetria duplicati quando più thread chiamano nella pipeline di telemetria all'avvio.

1.2.1

Modifiche

  • I file di commento della documentazione XML sono ora inclusi nel pacchetto NuGet.
  • È stato aggiunto un ExcludeFromSnapshotting metodo di estensione per System.Exception gli scenari in cui si è certi di avere un'eccezione rumorosa ed evitare di creare snapshot.
  • Aggiunta di una IsEnabledWhenProfiling proprietà di configurazione che per impostazione predefinita è true. Si tratta di una modifica rispetto alle versioni precedenti in cui la creazione di snapshot è stata temporaneamente disabilitata se Application Insights Profiler stava eseguendo una raccolta dettagliata. Il comportamento precedente può essere recuperato impostando questa proprietà su false.

Correzioni di bug

  • Firmare SnapshotUploader64.exe correttamente.
  • Protezione contro l'inizializzazione doppia del processore di telemetria.
  • Impedire la doppia registrazione dei dati di telemetria nelle app con più pipeline.
  • Correzione di un bug con la scadenza di un piano di raccolta, che potrebbe impedire snapshot dopo 24 ore.

1.2.0

La modifica più importante in questa versione (quindi il passaggio a un nuovo numero di versione secondaria) è una riscrittura della pipeline di creazione e gestione degli snapshot. Nelle versioni precedenti questa funzionalità è stata implementata nel codice nativo (ProductionBreakpoints.dll* e SnapshotHolder.exe*). La nuova implementazione è tutto il codice gestito con P/Invokes.

Per questa prima versione usando la nuova pipeline, non è stato possibile allontanarsi dal comportamento originale. La nuova implementazione consente una segnalazione degli errori migliore e ci configura per miglioramenti futuri.

Altre modifiche in questa versione

  • MinidumpUploader.exe è stato rinominato in SnapshotUploader.exe (o SnapshotUploader64.exe).
  • Aggiunta dei dati di telemetria di intervallo alle richieste DeOptimize/ReOptimize.
  • Aggiunta della compressione gzip per i caricamenti minidump.
  • È stato risolto un problema a causa del quale i PDB erano bloccati impedendo l'aggiornamento del sito.
  • Registrare il nome della cartella originale (SnapshotCollectorFiles) durante la copia shadow.
  • Modificare i limiti di memoria per i processi a 64 bit per impedire il riavvio del sito a causa dell'OOM.
  • È stato risolto un problema per cui gli snapshot venivano ancora raccolti anche dopo la disabilitazione.
  • Registrare gli eventi heartbeat nella risorsa di intelligenza artificiale del cliente.
  • Miglioramento della velocità degli snapshot rimuovendo "Source" dall'ID problema.

1.1.2

Modifiche

  • Dati di telemetria di utilizzo aumentata.
  • Rilevare e segnalare la versione e il sistema operativo di .NET.
  • Rilevare e segnalare altri ambienti di Azure (Azure Servizi cloud, Azure Service Fabric).
  • Registrare e segnalare le metriche delle eccezioni (numero di eccezioni first-chance e numero di TrackException chiamate) nella telemetria heartbeat.

Correzioni di bug

  • Gestione corretta della posizione in SqlException cui l'eccezione interna (Win32Exception) non viene generata.
  • Ritagliati gli spazi finali nelle cartelle dei simboli, che hanno causato un'analisi non corretta degli argomenti della riga di comando in MinidumpUploader.
  • È stato impedito un nuovo tentativo infinito di connessioni non riuscite all'endpoint dell'agente snapshot debugger.

1.1.0

Modifiche

  • Aggiunta della protezione della memoria host. Questa funzionalità riduce l'impatto sulla memoria del computer host.
  • Miglioramento dell'esperienza di visualizzazione snapshot portale di Azure.