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

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

Это важно

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

Центр приложений Crashes автоматически создаёт журнал сбоев при каждом сбое вашего приложения. Журнал сначала записывается в хранилище устройства, и когда пользователь снова запускает приложение, отчет о сбоях будет отправлен в Центр приложений.

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

Если вы еще не настроили SDK-пакет в вашем приложении, следуйте руководству WPF/WinForms Getting Started.

Необработанные исключения в приложениях 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 не подключен обработчик.

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

App Center Crashes предоставляет API для генерации тестового сбоя, что упрощает тестирование пакета SDK. Этот API проверяет конфигурации отладки и выпуска. Его можно использовать только для отладки, так как оно не будет работать в релизных приложениях.

Crashes.GenerateTestCrash();

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

App Center Crashes предоставляет два API, которые дают вам больше информации в случае сбоя вашего приложения.

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

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

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

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

Замечание

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

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

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

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Замечание

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

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

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

Сервис сбоев App Center предоставляет обратные вызовы для разработчиков, позволяющие выполнять дополнительные действия перед отправкой журналов сбоев в App Center.

Замечание

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

Следует ли обрабатывать аварию?

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

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

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

Если вы решили сделать это, вы несете ответственность за получение подтверждения пользователя, например с помощью диалогового окна с одним из следующих параметров: Always Send, Send и Don't send. На основе входных данных вы сообщите App Center Crashes, что делать, и аварийное завершение работы будет обрабатываться соответствующим образом.

Замечание

Пакет 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, поскольку это имя зарезервировано для минидампов. Вот пример того, как прикрепить текст и изображение к отчету о сбое:

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

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

Вы можете включать и отключать App Center Crashes в процессе работы. Если отключить его, пакет 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);
}
  • Last updated on