Сбои Центра приложений (Windows)
Важно!
Прекращение поддержки Центра приложений Visual Studio запланировано на 31 марта 2025 г. Хотя вы можете продолжать использовать Центр приложений Visual Studio до полного прекращения его использования, существует несколько рекомендуемых вариантов, на которые можно перейти.
Узнайте больше о сроках поддержки и альтернативных вариантах.
При сбоях Центра приложений автоматически создается журнал сбоев при каждом сбое приложения. Сначала журнал записывается в хранилище устройства, и когда пользователь снова запустит приложение, отчет о сбое будет отправлен в Центр приложений.
Пакет SDK центра приложений собирает только сбои, вызванные необработанными исключениями .NET. Он не собирает собственные сбои, например при использовании C или C++. Однако если у вас есть приложение со сбоями C++, вы можете отправить их в Центр приложений с помощью API аварийного завершения отправки.
Следуйте инструкциям в начало работы WPF/WinForms, если вы еще не настроили пакет SDK в приложении.
Необработанных исключений в приложениях WinForms
Примечание
Этот раздел и следующие подразделы относятся только к WinForms. Этот раздел можно пропустить, если вы интегрируете пакет SDK в WPF.
По умолчанию необработанное исключение в приложении WinForms не вызывает сбой (приложение не завершает работу), если отладчик не подключен.
Вместо этого Windows показывает пользователю диалоговое окно с возможностью продолжить или завершить выполнение приложения. Следовательно, пакет SDK центра приложений не может автоматически записывать эти исключения (даже если пользователь нажимает кнопку Выйти ).
Сбои собираются в Центре приложений только в том случае, если это приводит к автоматическому завершению работы приложения. Центр приложений поддерживает только один сбой в сеансе.
Существует два способа сообщить о необработанных исключениях в WinForms. Приложение можно настроить для аварийного завершения работы при необработанных исключениях или продолжить выполнение, но сообщать о необработанных исключениях как об ошибках среды выполнения.
Настройка завершения работы приложения при сбое
Это единственный способ сообщить о необработанных исключениях как о сбое в Центре приложений и сделать приложение выходом из необработанных исключений.
Для этого вызовите метод Windows перед инициализацией пакета SDK:
Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException);
AppCenter.Start(...);
Если этот параметр не приемлем в приложении, вы можете сообщить об необработанном исключении как об ошибке среды выполнения (описано ниже).
Отчет об необработанных исключениях как об ошибке среды выполнения
Если приложение должно продолжать работать после необработанного исключения, вы не сможете сообщить об этом исключении как о сбое в Центре приложений, но вместо этого можно сообщить об ошибке.
Для этого можно использовать следующий пример кода:
Application.ThreadException += (sender, args) =>
{
Crashes.TrackError(args.Exception);
};
AppCenter.Start(...);
Примечание
При подключении отладчика необработанное исключение приведет к завершению работы приложения (аварийному завершению), если обработчик не подключен к Application.ThreadException.
Создание аварийного завершения теста
Сбои Центра приложений предоставляют 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. 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);
}