培训
App Center (UWP/WinUI) 崩溃
重要
Visual Studio App Center 计划于 2025 年 3 月 31 日停用。 虽然可以继续使用 Visual Studio App Center,直到它完全停用,但你可以考虑迁移到几个建议的替代方法。
每次应用崩溃时,App Center 崩溃都会自动生成崩溃日志。 日志首先写入设备的存储,当用户再次启动应用时,故障报告将发送到 App Center。 收集崩溃适用于 beta 应用和提交到 Windows 应用商店的应用。 故障日志包含有助于修复崩溃的重要信息。
App Center SDK 仅收集由未经处理的 .NET 异常导致的崩溃。 它不会收集本机崩溃,例如使用 C 或 C++ 时。 但是,如果你有一个 C++ 崩溃的应用,可以通过 上传崩溃 API 将其上传到 App Center。
如果尚未在应用程序中设置 SDK,请按照入门部分进行操作。
备注
目前,我们不支持在 UWP/WinUI 平台上检测内存不足警告。
- 在 Visual Studio 中打开控制台。 为此,请选择 “工具”>“NuGet 包管理器>”“包管理器控制台”。
- 键入以下命令:
Install-Package Microsoft.AppCenter.Crashes
在使用我们的 API 之前,请添加适当的命名空间。
using Microsoft.AppCenter.Crashes;
添加或编辑对应用程序的 构造函数 的以下调用,以包含崩溃模块:
AppCenter.Start("{Your App Secret}", typeof(Crashes));
App Center 崩溃提供了一个 API,用于生成测试崩溃,以便轻松测试 SDK。 此 API 检查调试配置与发布配置。 因此,只能在调试时使用它,因为它不适用于发布应用。
Crashes.GenerateTestCrash();
App Center 崩溃有两个 API,可在应用崩溃时为你提供详细信息。
启动 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 发送时执行其他操作。
备注
在调用 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. 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;
};
如果在上述回调中返回 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 崩溃提供了三种不同的回调,你可以在应用中使用这些回调来接收所发生情况的通知:
Crashes.SendingErrorReport += (sender, e) =>
{
// Your code, e.g. to present a custom UI.
};
如果我们在终结点上遇到网络问题或中断,并且你重新启动应用, SendingErrorReport
则会在进程重启后再次触发。
Crashes.SentErrorReport += (sender, e) =>
{
// Your code, e.g. to hide the custom UI.
};
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 崩溃。 如果禁用它,SDK 不会对应用执行任何故障报告。
Crashes.SetEnabledAsync(false);
若要再次启用 App Center 崩溃,请使用同一 API,但将 作为参数传递 true
。
Crashes.SetEnabledAsync(true);
无需等待此调用, (其他 API 调用(如 IsEnabledAsync
) 一致)。
在应用程序启动时,状态将保留在设备的存储中。
还可以检查是否启用 App Center 崩溃:
bool isEnabled = await Crashes.IsEnabledAsync();
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);
}