Поделиться через


Сбои Центра приложений (UWP/WinUI)

Важно!

Прекращение поддержки Центра приложений Visual Studio запланировано на 31 марта 2025 г. Хотя вы можете продолжать использовать Центр приложений Visual Studio до полного прекращения его использования, существует несколько рекомендуемых вариантов, на которые можно перейти.

Узнайте больше о сроках поддержки и альтернативных вариантах.

При сбоях Центра приложений автоматически создается журнал сбоев при каждом сбое приложения. Сначала журнал записывается в хранилище устройства, и когда пользователь снова запустит приложение, отчет о сбое будет отправлен в Центр приложений. Сбор сбоев работает как для бета-версий приложений, так и для приложений, отправленных в Магазин Windows. Журналы сбоев содержат ценные сведения, которые помогут устранить сбои.

Пакет SDK центра приложений собирает только сбои, вызванные необработанными исключениями .NET. Он не собирает собственные сбои, например при использовании C или C++. Однако если у вас есть приложение со сбоями C++, вы можете отправить их в Центр приложений с помощью API аварийного завершения отправки.

Если вы еще не настроили пакет 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));

Создание аварийного завершения теста

Сбои Центра приложений предоставляют API для создания тестового сбоя для простого тестирования пакета SDK. Этот API проверяет конфигурации отладки и выпуска. Поэтому его можно использовать только при отладке, так как он не будет работать для приложений выпуска.

Crashes.GenerateTestCrash();

Дополнительные сведения о предыдущем сбое

При сбоях Центра приложений есть два API, которые предоставляют дополнительные сведения на случай сбоя приложения.

Произошел сбой приложения в предыдущем сеансе?

В любой момент после запуска пакета SDK можно проверка, если приложение аварийно завершалось при предыдущем запуске:

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

Это удобно в случае, если вы хотите настроить поведение или пользовательский интерфейс приложения после сбоя. Некоторые разработчики предпочитают показывать дополнительный пользовательский интерфейс, чтобы извиниться перед пользователями, или хотят, чтобы связаться с ними после сбоя.

Примечание

Этот метод следует использовать только после Crashes запуска. Он всегда возвращается false перед запуском.

Сведения о последнем сбое

Если приложение ранее завершалось сбоем, вы можете получить сведения о последнем сбое.

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Примечание

Этот метод следует использовать только после Crashes запуска. Он всегда возвращается null перед запуском.

Существует множество вариантов использования этого API. Наиболее распространенные из них — люди, которые вызывают этот API и реализуют свой пользовательский делегат или прослушиватель сбоев.

Настройка использования сбоев Центра приложений

Сбои Центра приложений предоставляют разработчикам обратные вызовы для выполнения дополнительных действий до и при отправке журналов сбоев в Центр приложений.

Примечание

Задайте обратный вызов перед вызовом AppCenter.Start(), так как центр приложений начинает обработку сразу после запуска.

Следует ли обработать сбой?

Задайте этот обратный вызов, если вы хотите решить, нужно ли обрабатывать определенный сбой. Например, может произойти сбой на уровне системы, который вы хотите игнорировать и не хотите отправлять в Центр приложений.

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

Если для вас важна конфиденциальность пользователей, вы можете получить подтверждение пользователя перед отправкой отчета о сбоях в Центр приложений. Пакет SDK предоставляет обратный вызов, который сообщает о сбоях Центра приложений о том, что перед отправкой отчетов о сбоях пользователь ожидает подтверждения.

Если вы решили сделать это, вы несете ответственность за получение подтверждения пользователя, например через диалоговое окно с одним из следующих вариантов: Всегда отправлять, Отправлять и Не отправлять. В зависимости от входных данных вы укаживаете, что нужно сделать, и сбой будет обрабатываться соответствующим образом.

Примечание

Пакет SDK не отображает диалоговое окно для этого, приложение должно предоставить собственный пользовательский интерфейс для запроса согласия пользователя.

Примечание

Приложение не должно вызывать 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 в обратном вызове выше, приложение должно получить (с помощью собственного кода) разрешение пользователя и предоставить пакет SDK с результатом с помощью следующего API.

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

Получение сведений о состоянии отправки для журнала сбоев

Иногда требуется узнать состояние сбоя приложения. Распространенный вариант использования заключается в том, что может потребоваться показать пользовательский интерфейс, который сообщает пользователям, что приложение отправляет отчет о сбоях, или, если приложение быстро аварийно завершает работу после запуска, необходимо настроить поведение приложения, чтобы убедиться, что журналы сбоев можно отправить. При сбоях Центра приложений предусмотрены три разных обратных вызова, которые можно использовать в приложении для получения уведомлений о происходящем:

Следующий обратный вызов будет вызван до того, как пакет 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 отправит их вместе со сбоем, чтобы их можно было увидеть на портале Центра приложений. Следующий обратный вызов будет вызван непосредственно перед отправкой сохраненного сбоя из предыдущих запусков приложения. Он не будет вызываться при сбое. Убедитесь, что файлу вложения не присвоено имя minidump.dmp , так как это имя зарезервировано для файлов minidump. Ниже приведен пример вложения текста и изображения в сбой:

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 МБ. Попытка отправить вложение большего размера вызовет ошибку.

Включение или отключение сбоев Центра приложений во время выполнения

Вы можете включить и отключить сбои Центра приложений во время выполнения. Если вы отключите его, пакет SDK не будет сообщать о сбоях для приложения.

Crashes.SetEnabledAsync(false);

Чтобы снова включить сбои Центра приложений, используйте тот же API, но передайте true в качестве параметра.

Crashes.SetEnabledAsync(true);

Вам не нужно ждать этого вызова, чтобы другие вызовы API (например, IsEnabledAsync) были согласованы.

Состояние сохраняется в хранилище устройства при запусках приложений.

Проверьте, включен ли сбой центра приложений

Вы также можете проверка, включены ли сбои Центра приложений:

bool isEnabled = await Crashes.IsEnabledAsync();

Обработано ошибок

Центр приложений также позволяет отслеживать ошибки с помощью обрабатываемых исключений. Для этого используйте 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);
}