App Center 崩溃 (MAUI 和 Xamarin)

项目
03/17/2024

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。虽然可以继续使用 Visual Studio App Center，直到它完全停用，但你可以考虑迁移到几个建议的替代方法。

每次应用崩溃时，App Center 崩溃都会自动生成崩溃日志。日志首先写入设备的存储，当用户再次启动应用时，故障报告将发送到 App Center。收集崩溃适用于 beta 和实时应用，即提交到App Store的应用。崩溃日志包含有价值的信息，可帮助你修复故障。

如果尚未在应用程序中设置 SDK，请按照入门部分进行操作。

此外，iOS 上的崩溃日志需要符号化，检查 App Center 诊断文档，其中介绍了如何为应用提供符号。

注意

在 iOS 和 Mac 上，如果附加了调试器，SDK 不会保存任何崩溃日志。请确保在 iOS 和 macOS 应用崩溃时未附加调试器。在 Android 上，连接调试器时可能会崩溃，但在遇到未经处理的异常后需要继续执行。

生成测试崩溃

App Center 崩溃提供了一个 API，用于生成测试崩溃，以便轻松测试 SDK。此 API 检查调试配置与发布配置。因此，只能在调试时使用它，因为它不适用于发布应用。

Crashes.GenerateTestCrash();

获取有关以前崩溃的详细信息

App Center 崩溃有两个 API，可在应用崩溃时提供详细信息。

应用在上一个会话中是否收到内存不足警告？

启动 SDK 后，可以随时检查应用是否在上一个会话中收到内存警告：

bool hadMemoryWarning = await Crashes.HasReceivedMemoryWarningInLastSessionAsync();

注意

此方法只能在启动后 Crashes 使用，它始终在启动前返回 false 。

注意

在某些情况下，内存不足的设备无法发送事件。

应用是否在上一个会话中崩溃？

启动 SDK 后，可以随时检查应用在上一次启动时崩溃：

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

如果想要在发生崩溃后调整应用的行为或 UI，这非常有用。一些开发人员选择显示其他 UI 以向用户道歉，或者希望通过某种方式在崩溃发生后取得联系。

注意

此方法只能在启动后 Crashes 使用，它始终在启动前返回 false 。

有关上次崩溃的详细信息

如果你的应用以前崩溃，你可以获取有关上次崩溃的详细信息。

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

注意

此方法只能在启动后 Crashes 使用，它始终在启动前返回 null 。

此 API 有许多用例，最常见的用例是调用此 API 并实现其自定义崩溃委托或侦听器的人员。

自定义 App Center 崩溃的用法

App Center 崩溃为开发人员提供回调，以便在将崩溃日志发送到 App Center 之前和将崩溃日志发送到 App Center 时执行其他操作。

注意

在调用 AppCenter.Start()之前设置回调，因为 App Center 在启动后立即开始处理崩溃。

是否应处理崩溃？

如果要确定是否需要处理特定故障，请设置此回调。例如，你可能希望忽略系统级别崩溃，并且不希望发送到 App Center。

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

如果用户隐私对你很重要，你可能希望在将崩溃报告发送到 App Center 之前获得用户确认。 SDK 公开一个回调，告知 App Center 崩溃在发送任何故障报告之前等待用户确认。

如果选择这样做，则你负责获取用户的确认，例如，通过对话框提示并使用以下选项之一： 始终发送、发送和 不发送。根据输入，你将告诉 App Center 崩溃要执行的操作，然后会相应地处理崩溃。

注意

SDK 不显示此对话框，应用必须提供自己的 UI 以请求用户同意。

注意

如果应用未实现用户确认对话框，则不应显式调用 NotifyUserConfirmation ;崩溃模块将隐式处理发送日志。

以下回调演示如何告诉 SDK 在发送崩溃之前等待用户确认：

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

如果你在上述回调中返回 true ，则应用必须使用自己的代码) 用户权限获取 (，并使用以下 API 向 SDK 发送结果消息。

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

例如，可以参考我们的自定义对话示例。

获取有关崩溃日志的发送状态的信息

有时，你想知道应用崩溃的状态。一个常见的用例是，你可能想要显示 UI 来告知用户你的应用正在提交崩溃报告，或者，如果你的应用在启动后快速崩溃，你需要调整应用的行为，以确保可以提交崩溃日志。 App Center 崩溃提供了三个不同的回调，你可以在应用中使用这些回调来通知所发生的情况：

在 SDK 发送崩溃日志之前，将调用以下回调

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

如果终结点出现网络问题或中断，并且重启应用， SendingErrorReport 则会在进程重启后再次触发。

SDK 成功发送崩溃日志后，将调用以下回调

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

如果 SDK 未能发送故障日志，将调用以下回调

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

接收 FailedToSendErrorReport 表示发生了不可恢复的错误，例如 4xx 代码。例如， 401 表示 appSecret 错误。

如果这是网络问题，则不会触发此回调。在这种情况下，SDK 会继续重试 (，并在网络连接关闭) 时暂停重试。

向崩溃报告添加附件

可以将二进制附件和文本附件添加到崩溃报告。 SDK 会连同崩溃一起发送它们，以便你可以在 App Center 门户中看到它们。在从以前的应用程序启动时发送存储的故障之前，将立即调用以下回调。发生崩溃时，不会调用它。确保 附件文件未 命名 minidump.dmp ，因为该名称是为小型转储文件保留的。下面是如何将文本和图像附加到崩溃的示例：

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

注意

大小限制当前为 7 MB。尝试发送较大的附件将触发错误。

在运行时启用或禁用 App Center 崩溃

可以在运行时启用和禁用 App Center 崩溃。如果禁用它，SDK 不会为应用执行任何崩溃报告。

Crashes.SetEnabledAsync(false);

若要再次启用 App Center 崩溃，请使用同一 API，但作为参数传递 true 。

Crashes.SetEnabledAsync(true);

无需等待此调用， (其他 API 调用（例如 IsEnabledAsync) 一致）。

状态在应用程序启动时保留在设备的存储中。

注意

只有在启动后 Crashes 才能使用此方法。

检查是否启用了 App Center 崩溃

还可以检查是否启用 App Center 崩溃：

bool isEnabled = await Crashes.IsEnabledAsync();

注意

此方法只能在启动后 Crashes 使用，它始终在启动前返回 false 。

已处理错误

App Center 还允许使用已处理的异常来跟踪错误。为此，请使用 TrackError 方法：

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

应用可以选择性地将属性附加到已处理的错误报告，以提供进一步的上下文。将属性作为键/值对的字典传递， (字符串仅) ，如以下示例所示。

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

还可以选择将二进制和文本附件添加到已处理的错误报告。将附件作为对象的数组 ErrorAttachmentLog 传递，如以下示例所示。

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

App Center 崩溃 (MAUI 和 Xamarin)

生成测试崩溃

获取有关以前崩溃的详细信息

应用在上一个会话中是否收到内存不足警告？

应用是否在上一个会话中崩溃？

有关上次崩溃的详细信息

自定义 App Center 崩溃的用法

是否应处理崩溃？

请求用户同意发送崩溃日志

获取有关崩溃日志的发送状态的信息

在 SDK 发送崩溃日志之前，将调用以下回调

SDK 成功发送崩溃日志后，将调用以下回调

如果 SDK 未能发送故障日志，将调用以下回调

向崩溃报告添加附件

在运行时启用或禁用 App Center 崩溃

检查是否启用了 App Center 崩溃

已处理错误

其他资源