App Center (UWP/WinUI) 損毀

重要

Visual Studio App Center 已排定於 2025 年 3 月 31 日淘汰。 雖然您可以繼續使用 Visual Studio App Center，直到完全淘汰為止，但有數個建議的替代方案可以考慮移轉至。

深入瞭解支持時程表和替代方案。

• Android
• iOS
• MAUI/Xamarin
• UWP
• WPF/WinForms
• React Native \(英文\)
• macOS
• tvOS
• Unity
• Cordova

App Center 當機會在每次應用程式當機時自動產生當機記錄。 記錄會先寫入裝置的記憶體，當使用者再次啟動應用程式時，當機報告會傳送至 App Center。 收集當機適用於 Beta 應用程式和提交至 Windows 市集的 App。 當機記錄包含寶貴的資訊，可協助您修正當機。

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

如果您尚未在應用程式中設定 SDK，請遵循 使用者入門 一節。

注意

目前我們不支援在UWP/WinUI平臺上偵測記憶體不足警告。

新增損毀模組

套件管理器主控台

• 在 Visual Studio 中開啟控制台。 若要這樣做，請選擇 [工具>][NuGet 套件管理員>套件管理員控制台]。
• 輸入下列命令：

Install-Package Microsoft.AppCenter.Crashes

新增using語句

使用我們的 API 之前，請先新增適當的命名空間。

using Microsoft.AppCenter.Crashes;

Start()修改方法

新增或編輯對應用程式建 構 函式的下列呼叫，以包含當機模組：

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在啟動後快速當機，您想要調整應用程式的行為，以確保可以提交當機記錄。 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);
}