Condividi tramite

Arresti anomali di App Center (Windows)

Importante

Visual Studio App Center è stato ritirato il 31 marzo 2025, ad eccezione delle funzionalità di Analisi e diagnostica, che continueranno a essere supportate fino al 30 giugno 2026. Ulteriori informazioni.

Il componente Crashes di App Center genererà automaticamente un log ogni volta che l'app si arresta in modo anomalo. Il log viene prima scritto nella memoria del dispositivo e quando l'utente avvia nuovamente l'app, il report degli errori verrà inviato ad App Center.

App Center SDK raccoglie solo arresti anomali causati da eccezioni .NET non gestite. Non raccoglie crash nativi, ad esempio quando si usa C o C++. Tuttavia, se si dispone di un'app con arresti anomali C++, è possibile caricarli in App Center tramite l'API di caricamento arresti anomali.

Seguire l'introduzione a WPF/WinForms se non è ancora stato configurato l'SDK nell'applicazione.

Eccezioni non gestite nelle applicazioni WinForms

Annotazioni

Questa sezione e le sezioni secondarie seguenti si applicano solo a WinForms. È possibile ignorare questa sezione se si sta integrando l'SDK in WPF.

Per impostazione predefinita, un'eccezione non gestita in un'applicazione WinForms non attiva un arresto anomalo (l'applicazione non viene chiusa) se il debugger non è collegato.

Windows visualizza invece una finestra di dialogo per l'utente che consente di continuare o chiudere l'esecuzione dell'app. Di conseguenza, App Center SDK non è in grado di acquisire automaticamente queste eccezioni (anche se l'utente fa clic sul pulsante Esci ).

I crash vengono raccolti in App Center solo se l'applicazione viene terminata automaticamente. App Center supporta un solo arresto anomalo per sessione.

Esistono due modi per segnalare eccezioni non gestite in WinForms. L'applicazione può essere configurata per arrestarsi in modo anomalo nelle eccezioni non gestite o continuare l'esecuzione, ma segnalare eccezioni non gestite come errori di runtime.

Configurare l'applicazione per l'uscita in caso di arresto anomalo

Questo è l'unico modo per segnalare l'eccezione non gestita come arresto anomalo in App Center. Forzare l'uscita dell'applicazione in caso di eccezioni non gestite.

A tale scopo, chiamare un metodo Windows prima di inizializzare l'SDK:

Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException);
AppCenter.Start(...);

Se questa opzione non è accettabile nell'applicazione, è possibile segnalare l'eccezione non gestita come errore di runtime (descritto di seguito).

Segnalare l'eccezione non gestita come errore di runtime

Se l'applicazione deve continuare a essere in esecuzione dopo un'eccezione non gestita, non è possibile segnalare l'eccezione come arresto anomalo in App Center, ma è possibile segnalarla come errore.

A tale scopo, è possibile usare l'esempio di codice seguente:

Application.ThreadException += (sender, args) =>
{
    Crashes.TrackError(args.Exception);
};
AppCenter.Start(...);

Annotazioni

Quando il debugger è collegato, le eccezioni non gestite causeranno l'arresto dell'applicazione (arresti anomali) meno che un gestore non sia collegato a Application.ThreadException.

Generare un crash di test

Crashes di App Center offre un'API per generare un crash di prova per facilitare il test dell'SDK. Questa API verifica le configurazioni di debug rispetto a quelle di rilascio. È quindi possibile usarlo solo durante il debug perché non funzionerà per le app di rilascio.

Crashes.GenerateTestCrash();

Trova ulteriori informazioni su un arresto anomalo precedente.

App Center Crashes ha due API che forniscono ulteriori informazioni nel caso in cui l'app vada in crash.

L'app si è arrestata in modo anomalo nella sessione precedente?

In qualsiasi momento dopo l'avvio dell'SDK, è possibile verificare se l'app si è arrestata in modo anomalo nell'avvio precedente:

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

Questo è utile nel caso in cui vuoi modificare il comportamento o l'interfaccia utente della tua app dopo un arresto anomalo. Alcuni sviluppatori scelgono di mostrare un'interfaccia utente supplementare per scusarsi con gli utenti o cercano un modo per entrare in contatto dopo che si è verificato un crash.

Annotazioni

Questo metodo deve essere usato solo dopo che Crashes è stato avviato; restituirà sempre false prima dell'avvio.

Dettagli sull'ultimo arresto anomalo

Se l'app è andata in crash in precedenza, è possibile ricevere dettagli sull'ultimo crash.

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Annotazioni

Questo metodo deve essere usato solo dopo che Crashes è stato avviato; restituirà sempre null prima dell'avvio.

Esistono numerosi casi d'uso per questa API, quello più comune è costituito dalle persone che chiamano questa API e implementano il delegato o il listener di arresti anomali personalizzati.

Personalizzare l'utilizzo dei crash di App Center

Il componente App Center Crashes fornisce callback agli sviluppatori per eseguire azioni aggiuntive prima di inviare i registri di errore ad App Center.

Annotazioni

Impostare il callback prima di chiamare AppCenter.Start(), poiché App Center avvia l'elaborazione degli arresti anomali immediatamente dopo l'avvio.

Deve essere elaborato l'incidente?

Impostare questo callback se si vuole decidere se è necessario elaborare o meno un determinato crash. Ad esempio, potrebbe verificarsi un arresto anomalo a livello di sistema che si vuole ignorare e che non si vuole inviare ad App Center.

Crashes.ShouldProcessErrorReport = (ErrorReport report) =>
{
    // Check the report in here and return true or false depending on the ErrorReport.
    return true;
};

Se la privacy degli utenti è importante per te, potresti voler ottenere conferma dagli utenti prima di inviare un report di errore ad App Center. L'SDK espone un callback che chiede ad App Center Crashes di attendere la conferma dell'utente prima di inviare report di arresto anomalo.

Se si sceglie di farlo, si è responsabili di ottenere la conferma dell'utente, ad esempio tramite una finestra di dialogo con una delle opzioni seguenti: Invia sempre, Invia e Non inviare. In base all'input, si indicherà ad App Center Crashes cosa fare e gestirà l'arresto anomalo di conseguenza.

Annotazioni

L'SDK non visualizza una finestra di dialogo per questa operazione. L'app deve fornire la propria interfaccia utente per richiedere il consenso dell'utente.

Annotazioni

L'app non dovrebbe chiamare NotifyUserConfirmation esplicitamente se non implementa una finestra di dialogo di conferma dell'utente; il modulo Crashes gestirà in modo implicito l'invio dei log.

Il seguente callback illustra come configurare l'SDK affinché attenda la conferma dell'utente prima di inviare le segnalazioni di errori.

Crashes.ShouldAwaitUserConfirmation = () =>
{
    // Build your own UI to ask for user consent here. SDK doesn't provide one by default.

    // Return true if you built a UI for user consent and are waiting for user input on that custom UI, otherwise false.
    return true;
};

Se si torna true nel callback precedente, l'app deve ottenere (attraverso il proprio codice) l'autorizzazione utente e comunicare all'SDK con l'esito usando l'API seguente.

// Depending on the user's choice, call Crashes.NotifyUserConfirmation() with the right value.
Crashes.NotifyUserConfirmation(UserConfirmation.DontSend);
Crashes.NotifyUserConfirmation(UserConfirmation.Send);
Crashes.NotifyUserConfirmation(UserConfirmation.AlwaysSend);

Ricevi informazioni sullo stato di invio di un log di arresto anomalo

A volte, vuoi conoscere lo stato del crash dell'app. Un caso d'uso comune è che puoi mostrare un'interfaccia utente che informa gli utenti che l'app sta inviando un report di arresto anomalo oppure, nel caso in cui l'app si arresti in modo anomalo rapidamente dopo l'avvio, puoi modificare il comportamento dell'app per assicurarti che i log degli arresti anomali vengano inviati. Il modulo Crashes di App Center offre tre callback diversi che è possibile usare nell'app per sapere cosa sta accadendo.

Il callback seguente verrà richiamato prima che l'SDK invii un log di arresto anomalo del sistema

Crashes.SendingErrorReport += (sender, e) =>
{
    // Your code, e.g. to present a custom UI.
};

In caso di problemi di rete o un'interruzione dell'endpoint, e se riavvii l'app, SendingErrorReport viene attivato di nuovo dopo il riavvio del processo.

Dopo che l'SDK avrà inviato correttamente un rapporto di errore, verrà attivato il callback seguente.

Crashes.SentErrorReport += (sender, e) =>
{
    // Your code, e.g. to hide the custom UI.
};

Il seguente callback verrà richiamato se l'SDK ha fallito nel tentativo di inviare un registro di crash.

Crashes.FailedToSendErrorReport += (sender, e) =>
{
    // Your code goes here.
};

La ricezione FailedToSendErrorReport indica che si è verificato un errore non recuperabile, ad esempio un codice 4xx . Ad esempio, 401 indica che l'errore appSecret è sbagliato.

Questo callback non viene attivato se si tratta di un problema di rete. In questo caso, l'SDK continua a riprovare (e sospende anche i tentativi mentre la connessione di rete è inattiva).

Aggiungere allegati a un report di arresto anomalo

È possibile aggiungere allegati binari e di testo a un report di arresto anomalo del sistema. L'SDK li invierà insieme all'arresto anomalo in modo che sia possibile visualizzarli nel portale di App Center. Il callback seguente verrà richiamato immediatamente prima di inviare l'arresto anomalo archiviato dall'avvio precedente dell'applicazione. Non verrà richiamato quando si verifica il crash. Assicurarsi che il file allegato non sia denominato minidump.dmp poiché quel nome è riservato ai file minidump. Ecco un esempio di come allegare testo e un'immagine a un arresto anomalo:

Crashes.GetErrorAttachments = (ErrorReport report) =>
{
    // Your code goes here.
    return new ErrorAttachmentLog[]
    {
        ErrorAttachmentLog.AttachmentWithText("Hello world!", "hello.txt"),
        ErrorAttachmentLog.AttachmentWithBinary(Encoding.UTF8.GetBytes("Fake image"), "fake_image.jpeg", "image/jpeg")
    };
};

Annotazioni

Il limite di dimensioni è attualmente di 7 MB. Il tentativo di inviare un allegato più grande attiverà un errore.

Abilitare o disabilitare i crash di App Center durante l'esecuzione

È possibile abilitare e disabilitare i crash di App Center in fase di esecuzione. Se lo disabiliti, l'SDK non effettuerà segnalazioni di arresti anomali per l'app.

Crashes.SetEnabledAsync(false);

Per abilitare di nuovo App Center Crashes, usare la stessa API ma passare true come parametro.

Crashes.SetEnabledAsync(true);

Non è necessario attendere questa chiamata per rendere coerenti altre chiamate API ( ad esempio IsEnabledAsync).

Lo stato viene salvato in modo permanente nella risorsa di archiviazione del dispositivo all'avvio dell'applicazione.

Verifica se Crashes di App Center è abilitato

È inoltre possibile verificare se i crash di App Center sono abilitati o meno:

bool isEnabled = await Crashes.IsEnabledAsync();

Errori gestiti

App Center consente anche di tenere traccia degli errori usando le eccezioni gestite. A tale scopo, usare il TrackError metodo :

try {
    // your code goes here.
} catch (Exception exception) {
    Crashes.TrackError(exception);
}

Un'app può facoltativamente allegare proprietà a un report degli errori gestito per fornire ulteriore contesto. Passare le proprietà come dizionario di coppie chiave/valore (solo stringhe) come illustrato nell'esempio seguente.

try {
    // your code goes here.
} catch (Exception exception) {
    var properties = new Dictionary<string, string>
    {
        { "Category", "Music" },
        { "Wifi", "On"}
    };
    Crashes.TrackError(exception, properties); 
}

Facoltativamente, è anche possibile aggiungere allegati binari e di testo a un report degli errori gestito. Passare gli allegati come matrice di ErrorAttachmentLog oggetti come illustrato nell'esempio seguente.

try {
    // your code goes here.
} catch (Exception exception) {
    var attachments = new ErrorAttachmentLog[]
    {
        ErrorAttachmentLog.AttachmentWithText("Hello world!", "hello.txt"),
        ErrorAttachmentLog.AttachmentWithBinary(Encoding.UTF8.GetBytes("Fake image"), "fake_image.jpeg", "image/jpeg")
    };
    Crashes.TrackError(exception, attachments: attachments);
}