App Center-Abstürze (UWP/WinUI)

Wichtig

Visual Studio App Center wird am 31. März 2025 eingestellt. Sie können Visual Studio App Center zwar weiterhin verwenden, bis es vollständig eingestellt ist, es gibt jedoch mehrere empfohlene Alternativen, zu denen Sie möglicherweise eine Migration in Erwägung ziehen.

Erfahren Sie mehr über Supportzeitpläne und Alternativen.

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

App Center-Abstürze generiert automatisch ein Absturzprotokoll, wenn Ihre App abstürzt. Das Protokoll wird zuerst in den Speicher des Geräts geschrieben, und wenn der Benutzer die App erneut startet, wird der Absturzbericht an App Center gesendet. Das Sammeln von Abstürze funktioniert sowohl für Beta-Apps als auch für an den Windows Store übermittelte Apps. Absturzprotokolle enthalten wertvolle Informationen für Sie, um die Abstürze zu beheben.

Das App Center SDK erfasst nur Abstürze, die durch nicht behandelte .NET-Ausnahmen verursacht werden. Es werden keine nativen Abstürze erfasst, z. B. bei Verwendung von C oder C++. Wenn Sie jedoch eine App mit C++-Abstürze haben, können Sie sie über die Uploadabsturz-API in App Center hochladen.

Folgen Sie dem Abschnitt Erste Schritte, wenn Sie das SDK noch nicht in Ihrer Anwendung eingerichtet haben.

Hinweis

Derzeit wird die Erkennung von Warnungen mit wenig Arbeitsspeicher auf der UWP/WinUI-Plattform nicht unterstützt.

Hinzufügen des Moduls "Abstürze"

Paket-Manager-Konsole

• Öffnen Sie die Konsole in Visual Studio. Wählen Sie hierzu Extras>NuGet-Paket-Manager-Paket-Manager-Konsole>aus.
• Geben Sie folgende Befehle ein:

Install-Package Microsoft.AppCenter.Crashes

Hinzufügen der using-Anweisungen

Fügen Sie die entsprechenden Namespaces hinzu, bevor Sie unsere APIs verwenden.

using Microsoft.AppCenter.Crashes;

Ändern der Start() Methode

Fügen Sie den folgenden Aufruf zum Konstruktor Ihrer Anwendung hinzu, oder bearbeiten Sie ihn, um das Absturzmodul einzuschließen:

AppCenter.Start("{Your App Secret}", typeof(Crashes));

Generieren eines Testabsturzes

App Center Crashes bietet Ihnen eine API zum Generieren eines Testabsturzes zum einfachen Testen des SDK. Diese API sucht nach Debug- und Releasekonfigurationen. Sie können es also nur beim Debuggen verwenden, da es für Release-Apps nicht funktioniert.

Crashes.GenerateTestCrash();

Weitere Informationen zu einem vorherigen Absturz

App Center Crashes verfügt über zwei APIs, die Ihnen weitere Informationen liefern, falls Ihre App abgestürzt ist.

Ist die App in der vorherigen Sitzung abgestürzt?

Nach dem Starten des SDK können Sie jederzeit überprüfen, ob die App beim vorherigen Start abgestürzt ist:

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

Dies ist nützlich, wenn Sie das Verhalten oder die Benutzeroberfläche Ihrer App nach einem Absturz anpassen möchten. Einige Entwickler zeigen eine zusätzliche Benutzeroberfläche an, um sich bei ihren Benutzern zu entschuldigen, oder möchten eine Möglichkeit haben, sich nach einem Absturz mit ihnen in Verbindung zu setzen.

Hinweis

Diese Methode darf erst nach dem Crashes Start verwendet werden. Sie wird immer vor dem Start zurückgegeben false .

Details zum letzten Absturz

Wenn Ihre App zuvor abgestürzt ist, können Sie Details zum letzten Absturz abrufen.

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Hinweis

Diese Methode darf erst nach dem Crashes Start verwendet werden. Sie wird immer vor dem Start zurückgegeben null .

Es gibt zahlreiche Anwendungsfälle für diese API. Am häufigsten sind Benutzer, die diese API aufrufen und ihren benutzerdefinierten Absturzdelegierten oder Listener implementieren.

Anpassen der Nutzung von App Center-Abstürze

App Center Crashes bietet Rückrufe für Entwickler, um zusätzliche Aktionen vor und beim Senden von Absturzprotokollen an App Center auszuführen.

Hinweis

Legen Sie den Rückruf vor dem Aufrufen AppCenter.Start()fest, da App Center unmittelbar nach dem Start mit der Verarbeitung von Abstürze beginnt.

Sollte der Absturz verarbeitet werden?

Legen Sie diesen Rückruf fest, wenn Sie entscheiden möchten, ob ein bestimmter Absturz verarbeitet werden muss oder nicht. Beispielsweise kann es zu einem Absturz auf Systemebene kommen, den Sie ignorieren möchten und den Sie nicht an App Center senden möchten.

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

Anfordern der Zustimmung des Benutzers zum Senden eines Absturzprotokolls

Wenn Ihnen der Datenschutz der Benutzer wichtig ist, sollten Sie eine Benutzerbestätigung erhalten, bevor Sie einen Absturzbericht an App Center senden. Das SDK macht einen Rückruf verfügbar, der App Center-Abstürze angibt, die Bestätigung des Benutzers abzuwarten, bevor Absturzberichte gesendet werden.

Wenn Sie sich dafür entschieden haben, sind Sie dafür verantwortlich, die Bestätigung des Benutzers zu erhalten, z. B. über eine Dialogaufforderung mit einer der folgenden Optionen: Immer senden, senden und Nicht senden. Basierend auf der Eingabe teilen Sie App Center Abstürze mit, was zu tun ist, und der Absturz wird dann entsprechend behandelt.

Hinweis

Das SDK zeigt dafür kein Dialogfeld an. Die App muss eine eigene Benutzeroberfläche bereitstellen, um die Zustimmung des Benutzers einzuholen.

Hinweis

Die App sollte nicht explizit aufrufen NotifyUserConfirmation , wenn sie kein Benutzerbestätigungsdialogfeld implementiert. Das Modul Crashes verarbeitet implizit das Senden von Protokollen für Sie.

Der folgende Rückruf zeigt, wie sie das SDK anweisen, auf die Benutzerbestätigung zu warten, bevor Abstürze gesendet werden:

Crashes.ShouldAwaitUserConfirmation = () =>
{
    // Build your own UI to ask for user consent here. The 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;
};

Falls Sie im obigen Rückruf zurückgeben true , muss Ihre App die Benutzerberechtigung (mit Ihrem eigenen Code) erhalten und dem SDK eine Nachricht mit dem Ergebnis mithilfe der folgenden API senden.

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

Abrufen von Informationen zum sendenden status für ein Absturzprotokoll

Manchmal möchten Sie die status Ihres App-Absturzes kennen. Ein häufiger Anwendungsfall ist, dass Sie möglicherweise eine Benutzeroberfläche anzeigen möchten, die den Benutzern mitteilt, dass Ihre App einen Absturzbericht übermittelt, oder, falls Ihre App nach dem Start schnell abstürzt, möchten Sie das Verhalten der App anpassen, um sicherzustellen, dass die Absturzprotokolle übermittelt werden können. App Center Abstürze bietet drei verschiedene Rückrufe, die Sie in Ihrer App verwenden können, um über die Vorgänge benachrichtigt zu werden:

Der folgende Rückruf wird aufgerufen, bevor das SDK ein Absturzprotokoll sendet.

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

Falls Netzwerkprobleme oder ein Ausfall auf dem Endpunkt auftreten und Sie die App neu starten, SendingErrorReport wird nach dem Neustart des Prozesses erneut ausgelöst.

Der folgende Rückruf wird aufgerufen, nachdem das SDK erfolgreich ein Absturzprotokoll gesendet hat

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

Der folgende Rückruf wird aufgerufen, wenn das SDK ein Absturzprotokoll nicht senden konnte

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

Der FailedToSendErrorReport Empfang bedeutet einen nicht wiederherstellbaren Fehler, z. B. ein 4xx-Code . Beispielsweise bedeutet 401, dass falsch appSecret ist.

Dieser Rückruf wird nicht ausgelöst, wenn es sich um ein Netzwerkproblem handelt. In diesem Fall versucht das SDK immer wieder (und hält auch Wiederholungen an, während die Netzwerkverbindung unterbrochen ist).

Hinzufügen von Anlagen zu einem Absturzbericht

Sie können Binär- und Textanlagen zu einem Absturzbericht hinzufügen. Das SDK sendet sie zusammen mit dem Absturz, sodass Sie sie im App Center-Portal sehen können. Der folgende Rückruf wird direkt vor dem Senden des gespeicherten Absturzes von früheren Anwendungsstarts aufgerufen. Es wird nicht aufgerufen, wenn der Absturz auftritt. Stellen Sie sicher, dass die Anlagedatei nicht benannt minidump.dmp ist, da dieser Name für Minidump-Dateien reserviert ist. Hier sehen Sie ein Beispiel für das Anfügen von Text und einem Bild an einen Absturz:

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

Hinweis

Das Größenlimit beträgt derzeit 7 MB. Der Versuch, eine größere Anlage zu senden, löst einen Fehler aus.

Aktivieren oder Deaktivieren von App Center-Abstürze zur Laufzeit

Sie können App Center-Abstürze zur Laufzeit aktivieren und deaktivieren. Wenn Sie es deaktivieren, wird vom SDK keine Absturzberichte für die App ausgeführt.

Crashes.SetEnabledAsync(false);

Um App Center-Abstürze erneut zu aktivieren, verwenden Sie dieselbe API, übergeben true sie aber als Parameter.

Crashes.SetEnabledAsync(true);

Sie müssen diesen Aufruf nicht abwarten, um andere API-Aufrufe (z IsEnabledAsync. B. ) konsistent auszuführen.

Der Zustand wird im Speicher des Geräts bei allen Anwendungsstarts beibehalten.

Überprüfen, ob App Center-Abstürze aktiviert ist

Sie können auch überprüfen, ob App Center-Abstürze aktiviert ist oder nicht:

bool isEnabled = await Crashes.IsEnabledAsync();

Behandelte Fehler

Mit App Center können Sie auch Fehler mithilfe von behandelten Ausnahmen nachverfolgen. Verwenden Sie dazu die - TrackError Methode:

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

Eine App kann optional Eigenschaften an einen behandelten Fehlerbericht anfügen, um weiteren Kontext bereitzustellen. Übergeben Sie die Eigenschaften als Wörterbuch von Schlüssel-Wert-Paaren (nur Zeichenfolgen), wie im folgenden Beispiel gezeigt.

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

Sie können auch optional Binär- und Textanlagen zu einem behandelten Fehlerbericht hinzufügen. Übergeben Sie die Anlagen als Array von ErrorAttachmentLog Objekten, wie im folgenden Beispiel gezeigt.

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