Condividi tramite

Arresti di App Center (MAUI e Xamarin)

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. La raccolta di arresti anomali funziona sia per le app beta che per quelle attive, ad esempio quelle inviate all'App Store. I log degli arresti anomali contengono informazioni utili per risolvere l'arresto anomalo del sistema.

Se non è ancora stato configurato l'SDK nell'applicazione, seguire la sezione Introduzione .

Inoltre, i log di arresto anomalo in iOS richiedono la simbolicazione, consulta la documentazione di Diagnostics di App Center che spiega come fornire simboli per l'app.

Annotazioni

In iOS e Mac l'SDK non salverà alcun log di arresto anomalo se è stato collegato un debugger. Assicurati che il debugger non sia collegato quando fai crashare l'app iOS e macOS. Su Android, può verificarsi un arresto anomalo mentre il debugger è collegato, ma è necessario continuare l'esecuzione dopo l'interruzione nell'eccezione non gestita.

Generare un arresto anomalo del 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 ha ricevuto un avviso di memoria insufficiente nella sessione precedente?

In qualsiasi momento dopo l'avvio dell'SDK, è possibile verificare se l'app ha ricevuto un avviso di memoria nella sessione precedente:

bool hadMemoryWarning = await Crashes.HasReceivedMemoryWarningInLastSessionAsync();

Annotazioni

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

Annotazioni

In alcuni casi, un dispositivo con memoria insufficiente non può inviare eventi.

L'arresto anomalo dell'app 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

App Center Crashes fornisce callback per gli sviluppatori per eseguire azioni aggiuntive prima di inviare e durante l'invio dei log di crash 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);

Ad esempio, è possibile fare riferimento all'esempio di dialogo personalizzato.

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.

Annotazioni

Questo metodo deve essere utilizzato solo dopo l'avvio di Crashes.

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();

Annotazioni

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

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);
}