(Windows) 的 App Center 損毀

App Center 損毀會在每次應用程式損毀時自動產生損毀記錄檔。 記錄檔會先寫入裝置的儲存體,當使用者再次啟動應用程式時,會將損毀報告傳送至 App Center。

App Center SDK 只會收集因未處理的 .NET 例外狀況所造成的損毀。 它不會收集原生損毀,例如使用 C 或 c + +。 但是,如果您的應用程式有 c + + 損毀,您可以透過 上傳損毀 API 將它們上傳至 app Center。

如果您還沒有在應用程式中設定 SDK,請遵循 WPF/WinForms 開始使用

WinForms 應用程式的未處理例外狀況

注意

本節和後續小節只適用于 WinForms。 如果您要在 WPF 上整合 SDK,可以略過這一節。

根據預設,WinForms 應用程式中未處理的例外狀況不會觸發損毀 (如果未附加偵錯工具,應用程式不會結束) 。

相反地,Windows 會向使用者顯示一個對話方塊,以繼續或結束應用程式執行。 因此,即使使用者按一下 [結束 ] 按鈕) ,App Center SDK 仍無法自動捕捉這些例外狀況 (。

只有在應用程式會導致應用程式自動結束時,才會在 App Center 上收集損毀。 App Center 每個會話只支援一個損毀。

有兩種方式可報告 WinForms 中未處理的例外狀況。 應用程式可設定為在未處理的例外狀況時損毀,或繼續執行,但將未處理的例外狀況回報為執行階段錯誤。

將應用程式設定為在損毀時結束

這是將未處理的例外狀況報告為 App Center 損 的唯一方法,讓應用程式在未處理的例外狀況上結束。

若要這樣做,請在初始化 SDK 之前呼叫 Windows 方法:

Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException);
AppCenter.Start(...);

如果您的應用程式不接受此選項,您可以將未處理的例外狀況報告為執行階段錯誤 (描述如下) 。

將未處理的例外狀況報告為執行階段錯誤

如果您的應用程式必須在未處理的例外狀況之後繼續執行,您就無法將例外狀況報告為 App Center 中的損 ,但您可以改為將它報告為 錯誤

若要這樣做,您可以使用下列程式碼範例:

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

注意

附加偵錯工具時,未處理的例外狀況會導致應用程式結束 (損毀) 除非 將處理常式附加至 Application.ThreadException

產生測試損毀

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. 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) 一致。

狀態會保存在應用程式啟動之間的裝置儲存區中。

檢查是否已啟用 App Center 損毀

您也可以檢查是否已啟用 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);
}