App Center 當機 (MAUI 和 Xamarin)
重要
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
使用,它一律會在 start 之前傳回 false
。
注意
在某些情況下,記憶體不足的裝置無法傳送事件。
在啟動 SDK 之後,您可以隨時檢查應用程式是否在上一次啟動時當機:
bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();
如果您想要在發生當機之後調整應用程式的行為或 UI,這會很有用。 有些開發人員選擇向用戶顯示其他UI,或想要在發生當機之後連絡。
注意
這個方法只能在啟動之後 Crashes
使用,它一律會在 start 之前傳回 false
。
如果您的應用程式先前損毀,您可以取得上次損毀的詳細數據。
ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();
注意
這個方法只能在啟動之後 Crashes
使用,它一律會在 start 之前傳回 null
。
此 API 有許多使用案例,最常見的是呼叫此 API 並實作其自定義 當機委派或接聽程序的人員。
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在啟動後快速當機,您想要調整應用程式的行為,以確保可以提交當機記錄。 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
) 一致。
狀態會保存在應用程式啟動的裝置記憶體中。
注意
只有在啟動之後 Crashes
,才能使用這個方法。
您也可以檢查 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);
}