Arresti anomali di App Center (Windows)

Importante

Visual Studio App Center è previsto per il ritiro il 31 marzo 2025. Anche se è possibile continuare a usare Visual Studio App Center fino a quando non viene completamente ritirato, esistono diverse alternative consigliate che è possibile considerare la migrazione a.

Altre informazioni sulle sequenze temporali di supporto e sulle alternative.

• Android
• iOS
• MAUI/Xamarin
• UWP
• WPF/WinForms
• React Native
• macOS
• tvOS
• Unity
• Cordova

Gli arresti anomali di App Center genereranno automaticamente un log di arresto anomalo ogni volta che l'app si arresta in modo anomalo. Il log viene prima scritto nella risorsa di archiviazione del dispositivo e quando l'utente avvia di nuovo l'app, il report di arresto anomalo verrà inviato a App Center.

App Center SDK raccoglie solo arresti anomali causati da eccezioni .NET non gestite. Non raccoglie arresti anomali 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 la Introduzione WPF/WinForms se non è ancora stato configurato l'SDK nell'applicazione.

Eccezioni non gestite nelle applicazioni WinForms

Nota

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 mostra invece una finestra di dialogo all'utente per continuare o uscire dall'esecuzione dell'app. Di conseguenza, App Center SDK non è in grado di acquisire automaticamente queste eccezioni (anche se l'utente fa clic sul pulsante Quit ).

Gli arresti anomali vengono raccolti in App Center solo se causa l'uscita automatica dell'applicazione. 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 l'arresto anomalo delle eccezioni non gestite o continuare a eseguire ma segnalare eccezioni non gestite come errori di runtime.

Configurare l'applicazione per uscire dall'arresto anomalo

Questo è l'unico modo per segnalare l'eccezione non gestita come arresto anomalo in App Center, rendere l'applicazione uscire dalle 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 eseguire dopo un'eccezione non gestita, non è possibile segnalare l'eccezione come arresto anomalo in App Center, ma è invece possibile segnalarla come errore.

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

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

Nota

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

Generare un arresto anomalo del test

Gli arresti anomali di App Center offrono un'API per generare un arresto anomalo del test per un semplice test dell'SDK. Questa API controlla le configurazioni di debug e versione. È quindi possibile usarlo solo quando si esegue il debug perché non funzionerà per le app per la versione.

Crashes.GenerateTestCrash();

Ottenere altre informazioni su un arresto anomalo precedente

Gli arresti anomali di App Center hanno due API che forniscono altre informazioni in caso di arresto anomalo dell'app.

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 si vuole modificare il comportamento o l'interfaccia utente dell'app dopo un arresto anomalo. Alcuni sviluppatori scelgono di visualizzare un'interfaccia utente aggiuntiva per scusarsi con gli utenti o si vuole che un modo per entrare in contatto dopo un arresto anomalo si è verificato un arresto anomalo.

Nota

Questo metodo deve essere usato solo dopo Crashes l'avvio, verrà sempre restituito false prima dell'avvio.

Dettagli sull'ultimo arresto anomalo

Se l'app si è bloccata in precedenza, è possibile ottenere informazioni dettagliate sull'ultimo arresto anomalo.

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Nota

Questo metodo deve essere usato solo dopo Crashes l'avvio, verrà sempre restituito null prima dell'avvio.

Esistono numerosi casi d'uso per questa API, quello più comune è la gente che chiama questa API e implementa il delegato o il listener personalizzati degli arresti anomali.

Personalizzare l'utilizzo degli arresti anomali di App Center

Gli arresti anomali di App Center offrono callback per gli sviluppatori per eseguire azioni aggiuntive prima e quando si inviano log di arresto anomalo a App Center.

Nota

Impostare il callback prima di chiamare AppCenter.Start(), poiché App Center avvia l'elaborazione si arresta in modo anomalo immediatamente dopo l'avvio.

L'arresto anomalo deve essere elaborato?

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

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

Chiedere il consenso dell'utente per inviare un log di arresto anomalo

Se la privacy degli utenti è importante per te, potresti voler ottenere la conferma dell'utente prima di inviare un report di arresto anomalo all'App Center. L'SDK espone un callback che indica agli arresti anomali di App Center di attendere la conferma dell'utente prima di inviare eventuali report di arresto anomalo.

Se si sceglie di farlo, si è responsabili dell'acquisizione della conferma dell'utente, ad esempio tramite una richiesta di dialogo con una delle opzioni seguenti: Always Send, Send e Don't send. In base all'input, si indicherà agli arresti anomali di App Center cosa fare e l'arresto anomalo verrà quindi gestito di conseguenza.

Nota

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.

Nota

L'app non deve chiamare NotifyUserConfirmation in modo esplicito se non implementa una finestra di dialogo di conferma utente. Il modulo Arresti anomali gestirà l'invio implicito dei log.

Il callback seguente illustra come indicare all'SDK di attendere la conferma dell'utente prima di inviare arresti anomali:

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

Nel caso in cui venga restituito true il callback precedente, l'app deve ottenere (usando il proprio codice) l'autorizzazione dell'utente e il messaggio dell'SDK con il risultato 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);

Ottenere informazioni sullo stato di invio per un log di arresto anomalo

A volte, si vuole conoscere lo stato dell'arresto anomalo dell'app. Un caso d'uso comune è che è possibile visualizzare l'interfaccia utente che indica agli utenti che l'app invia un report di arresto anomalo o, nel caso in cui l'app si arresta in modo anomalo rapidamente dopo l'avvio, si vuole modificare il comportamento dell'app per assicurarsi che i log di arresto anomalo possano essere inviati. Gli arresti anomali di App Center offrono tre callback diversi che è possibile usare nell'app per ricevere una notifica delle operazioni seguenti:

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

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

In caso di problemi di rete o interruzione nell'endpoint e riavvio dell'app, SendingErrorReport viene attivata nuovamente dopo il riavvio del processo.

Il callback seguente verrà richiamato dopo che l'SDK ha inviato correttamente un log di arresto anomalo

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

Il callback seguente verrà richiamato se l'SDK non è riuscito a inviare un log di arresto anomalo

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

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

Questo callback non viene attivato se si tratta di un problema di rete. In questo caso, l'SDK continua a ripetere i tentativi (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. L'SDK li invierà insieme all'arresto anomalo in modo da poterli visualizzare nel portale di App Center. Il callback seguente verrà richiamato subito prima di inviare l'arresto anomalo archiviato dall'avvio dell'applicazione precedente. Non verrà richiamato quando si verifica l'arresto anomalo. Assicurarsi che il file allegato non sia denominato minidump.dmp come tale nome è riservato per i file minidump. Ecco un esempio di come collegare il 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")
    };
};

Nota

Il limite di dimensioni è attualmente 7 MB. Se si tenta di inviare un allegato più grande, verrà generato un errore.

Abilitare o disabilitare arresti anomali di App Center in fase di esecuzione

È possibile abilitare e disabilitare arresti anomali di App Center in fase di esecuzione. Se la si disabilita, l'SDK non eseguirà alcuna segnalazione di arresto anomalo per l'app.

Crashes.SetEnabledAsync(false);

Per abilitare di nuovo gli arresti anomali di App Center, 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 tra i lanci dell'applicazione.

Controllare se Gli arresti anomali di App Center sono abilitati

È anche possibile verificare se Gli arresti anomali 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); 
}

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