Сбои Центра приложений (MAUI и Xamarin)

Важно!

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

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

• Android
• iOS
• MAUI/Xamarin
• UWP
• WPF/WinForms
• React Native
• macOS
• tvOS
• Unity
• Cordova

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

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

Кроме того, журналы сбоев в iOS требуют символики, проверка из документации по диагностике Центра приложений, в которых объясняется, как предоставить символы для приложения.

Примечание

В iOS и Mac пакет SDK не сохраняет журнал сбоев при подключении отладчика. Убедитесь, что отладчик не подключен при сбое приложения iOS и macOS. В Android можно завершить работу при присоединении отладчика, но необходимо продолжить выполнение после взлома необработанного исключения.

Создание тестового сбоя

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

Crashes.GenerateTestCrash();

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

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

Приложение получило предупреждение о нехватке памяти в предыдущем сеансе?

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

bool hadMemoryWarning = await Crashes.HasReceivedMemoryWarningInLastSessionAsync();

Примечание

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

Примечание

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

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

В любой момент после запуска пакета 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. 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).

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

Примечание

Этот метод следует использовать только после Crashes запуска.

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

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

bool isEnabled = await Crashes.IsEnabledAsync();

Примечание

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

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

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