Awarie usługi App Center (Windows)

Ważne

Program Visual Studio App Center ma zostać wycofany 31 marca 2025 r. Mimo że możesz nadal używać programu Visual Studio App Center do momentu jej pełnego wycofania, istnieje kilka zalecanych alternatyw, do których można rozważyć migrację.

Dowiedz się więcej o osiach czasu pomocy technicznej i alternatywach.

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

Awarie centrum aplikacji automatycznie wygenerują dziennik awarii za każdym razem, gdy aplikacja ulegnie awarii. Dziennik jest najpierw zapisywany w magazynie urządzenia, a gdy użytkownik ponownie uruchomi aplikację, raport o awarii zostanie wysłany do Centrum aplikacji.

Zestaw SDK centrum aplikacji zbiera tylko awarie spowodowane przez nieobsługiwane wyjątki platformy .NET. Nie zbiera ona natywnych awarii, np. w przypadku korzystania z języka C lub C++. Jeśli jednak masz aplikację z awariami języka C++, możesz przekazać je do Centrum aplikacji za pośrednictwem interfejsu API awarii przekazywania.

Postępuj zgodnie z Wprowadzenie WPF/WinForms, jeśli zestaw SDK nie został jeszcze skonfigurowany w aplikacji.

Nieobsługiwane wyjątki w aplikacjach WinForms

Uwaga

Ta sekcja i poniższe sekcje podrzędne dotyczą tylko funkcji WinForms. Możesz pominąć tę sekcję, jeśli integrujesz zestaw SDK w programie WPF.

Domyślnie nieobsługiwany wyjątek w aplikacji WinForms nie wyzwala awarii (aplikacja nie kończy się), jeśli debuger nie jest dołączony.

Zamiast tego system Windows wyświetla użytkownikowi okno dialogowe, które umożliwia kontynuowanie lub zamykanie wykonywania aplikacji. W związku z tym zestaw SDK centrum aplikacji nie może automatycznie przechwytywać tych wyjątków (nawet jeśli użytkownik kliknie przycisk Zakończ ).

Awarie są zbierane w centrum aplikacji tylko wtedy, gdy aplikacja zostanie automatycznie zakończona. Usługa App Center obsługuje tylko jedną awarię na sesję.

Istnieją dwa sposoby zgłaszania nieobsługiwanych wyjątków w programie WinForms. Aplikację można skonfigurować tak, aby ulegała awarii w nieobsługiwanych wyjątkach lub kontynuować działanie, ale zgłaszać nieobsługiwane wyjątki jako błędy środowiska uruchomieniowego.

Konfigurowanie aplikacji do zamykania po awarii

Jest to jedyny sposób zgłaszania nieobsługiwanego wyjątku jako awarii w usłudze App Center, aby aplikacja zakończyła działanie w nieobsługiwanych wyjątkach.

Aby to zrobić, wywołaj metodę systemu Windows przed zainicjowaniem zestawu SDK:

Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException);
AppCenter.Start(...);

Jeśli ta opcja nie jest akceptowalna w aplikacji, możesz zgłosić nieobsługiwany wyjątek jako błąd środowiska uruchomieniowego (opisany poniżej).

Zgłaszanie nieobsługiwanego wyjątku jako błędu środowiska uruchomieniowego

Jeśli aplikacja musi działać po nieobsługiwanym wyjątku, nie można zgłosić wyjątku jako awarii w Centrum aplikacji, ale zamiast tego możesz zgłosić go jako błąd.

W tym celu możesz użyć następującego przykładu kodu:

Application.ThreadException += (sender, args) =>
{
    Crashes.TrackError(args.Exception);
};
AppCenter.Start(...);

Uwaga

Po dołączeniu debugera nieobsługiwane wyjątki spowodują zamknięcie (awarie) aplikacji, chyba że program obsługi jest dołączony do Application.ThreadExceptionprogramu .

Generowanie awarii testowej

Usługa App Center Crash udostępnia interfejs API umożliwiający wygenerowanie awarii testowej w celu łatwego testowania zestawu SDK. Ten interfejs API sprawdza konfiguracje debugowania i wydania. Dlatego można go używać tylko podczas debugowania, ponieważ nie będzie działać w przypadku aplikacji wydania.

Crashes.GenerateTestCrash();

Uzyskaj więcej informacji o poprzedniej awarii

Usługa App Center Crash ma dwa interfejsy API, które zapewniają więcej informacji na wypadek awarii aplikacji.

Czy aplikacja uległa awarii w poprzedniej sesji?

W dowolnym momencie po uruchomieniu zestawu SDK możesz sprawdzić, czy aplikacja uległa awarii w poprzednim uruchomieniu:

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

Jest to przydatne w przypadku, gdy chcesz dostosować zachowanie lub interfejs użytkownika aplikacji po wystąpieniu awarii. Niektórzy deweloperzy zdecydują się pokazać dodatkowy interfejs użytkownika, aby przeprosić swoich użytkowników lub chcieć skontaktować się po wystąpieniu awarii.

Uwaga

Ta metoda musi być używana tylko po Crashes rozpoczęciu. Będzie ona zawsze zwracana false przed rozpoczęciem.

Szczegóły dotyczące ostatniej awarii

Jeśli aplikacja uległa awarii wcześniej, możesz uzyskać szczegółowe informacje o ostatniej awarii.

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Uwaga

Ta metoda musi być używana tylko po Crashes rozpoczęciu. Będzie ona zawsze zwracana null przed rozpoczęciem.

Istnieje wiele przypadków użycia dla tego interfejsu API. Najczęściej są to osoby, które nazywają ten interfejs API i implementują niestandardowy delegat lub odbiornik awarii.

Dostosowywanie użycia awarii centrum aplikacji

Usługa App Center Crash udostępnia wywołania zwrotne dla deweloperów w celu wykonywania dodatkowych akcji przed i podczas wysyłania dzienników awarii do centrum aplikacji.

Uwaga

Ustaw wywołanie zwrotne przed wywołaniem AppCenter.Start()metody , ponieważ usługa App Center rozpoczyna przetwarzanie awarii natychmiast po uruchomieniu.

Czy awaria powinna zostać przetworzona?

Ustaw to wywołanie zwrotne, jeśli chcesz zdecydować, czy należy przetworzyć konkretną awarię, czy nie. Na przykład może wystąpić awaria na poziomie systemu, którą chcesz zignorować i że nie chcesz wysyłać do centrum aplikacji.

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

Poproś użytkownika o zgodę na wysłanie dziennika awarii

Jeśli prywatność użytkownika jest dla Ciebie ważna, możesz uzyskać potwierdzenie użytkownika przed wysłaniem raportu o awarii do Centrum aplikacji. Zestaw SDK uwidacznia wywołanie zwrotne, które informuje usługę App Center Crash o oczekiwaniu na potwierdzenie użytkownika przed wysłaniem raportów o awarii.

Jeśli zdecydujesz się to zrobić, odpowiadasz za uzyskanie potwierdzenia użytkownika, np. za pośrednictwem monitu dialogowego z jedną z następujących opcji: Zawsze wysyłaj, Wysyłaj i nie wysyłaj. Na podstawie danych wejściowych poinformujesz centrum aplikacji o awarii, co należy zrobić, a awaria zostanie odpowiednio obsłużona.

Uwaga

Zestaw SDK nie wyświetla okna dialogowego. Aplikacja musi podać własny interfejs użytkownika, aby poprosić o zgodę użytkownika.

Uwaga

Aplikacja nie powinna wywoływać NotifyUserConfirmation jawnie, jeśli nie implementuje okna dialogowego potwierdzenia użytkownika. Moduł Crash obsłuży wysyłanie dzienników niejawnie.

Poniższe wywołanie zwrotne pokazuje, jak poinformować zestaw SDK o oczekiwaniu na potwierdzenie użytkownika przed wysłaniem awarii:

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;
};

Jeśli wrócisz true w powyższym wywołaniu zwrotnym, aplikacja musi uzyskać (przy użyciu własnego kodu) uprawnienie użytkownika i wysłać wiadomość do zestawu SDK z wynikiem przy użyciu następującego interfejsu 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);

Uzyskiwanie informacji o stanie wysyłania dziennika awarii

Czasami chcesz znać stan awarii aplikacji. Typowy przypadek użycia polega na tym, że możesz pokazać interfejs użytkownika, który informuje użytkowników, że aplikacja przesyła raport o awarii lub w przypadku, gdy aplikacja ulega awarii szybko po uruchomieniu, chcesz dostosować zachowanie aplikacji, aby upewnić się, że dzienniki awarii można przesłać. Awarie usługi App Center udostępnia trzy różne wywołania zwrotne, których można użyć w aplikacji, aby otrzymywać powiadomienia o tym, co się dzieje:

Następujące wywołanie zwrotne zostanie wywołane przed wysłaniem dziennika awarii przez zestaw SDK

Crashes.SendingErrorReport += (sender, e) =>
{
    // Your code, e.g. to present a custom UI.
};

W przypadku wystąpienia problemów z siecią lub awarii punktu końcowego i ponowne uruchomienie aplikacji SendingErrorReport zostanie ponownie wyzwolone po ponownym uruchomieniu procesu.

Następujące wywołanie zwrotne zostanie wywołane po pomyślnym wysłaniu dziennika awarii zestawu SDK

Crashes.SentErrorReport += (sender, e) =>
{
    // Your code, e.g. to hide the custom UI.
};

Następujące wywołanie zwrotne zostanie wywołane, jeśli zestaw SDK nie może wysłać dziennika awarii

Crashes.FailedToSendErrorReport += (sender, e) =>
{
    // Your code goes here.
};

Odbieranie FailedToSendErrorReport oznacza, że wystąpił błąd niemożliwy do odzyskania, taki jak kod 4xx . Na przykład 401 oznacza, że wartość jest nieprawidłowa appSecret .

To wywołanie zwrotne nie jest wyzwalane, jeśli jest to problem z siecią. W takim przypadku zestaw SDK ponawia próbę (a także wstrzymuje ponawianie próby, gdy połączenie sieciowe nie działa).

Dodawanie załączników do raportu o awarii

Możesz dodać załączniki binarne i tekstowe do raportu o awarii. Zestaw SDK wyśle je wraz z awarią, aby można było je zobaczyć w portalu centrum aplikacji. Następujące wywołanie zwrotne zostanie wywołane bezpośrednio przed wysłaniem przechowywanej awarii z poprzednich uruchomień aplikacji. Nie będzie wywoływana, gdy wystąpi awaria. Upewnij się, że plik załącznika nie ma nazwy, minidump.dmp ponieważ nazwa jest zarezerwowana dla plików minidump. Oto przykład dołączania tekstu i obrazu do awarii:

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")
    };
};

Uwaga

Limit rozmiaru wynosi obecnie 7 MB. Próba wysłania większego załącznika spowoduje wystąpienie błędu.

Włączanie lub wyłączanie awarii usługi App Center w czasie wykonywania

Możesz włączyć i wyłączyć awarie usługi App Center w czasie wykonywania. Jeśli ją wyłączysz, zestaw SDK nie będzie wykonywać żadnych raportów dotyczących awarii dla aplikacji.

Crashes.SetEnabledAsync(false);

Aby ponownie włączyć usługę App Center Crash, użyj tego samego interfejsu API, ale przekaż true go jako parametr.

Crashes.SetEnabledAsync(true);

Nie musisz czekać na to wywołanie, aby inne wywołania interfejsu API (takie jak IsEnabledAsync) były spójne.

Stan jest utrwalany w magazynie urządzenia w przypadku uruchamiania aplikacji.

Sprawdzanie, czy usługa App Center ulega awarii jest włączona

Możesz również sprawdzić, czy usługa App Center Ulega awarii jest włączona, czy nie:

bool isEnabled = await Crashes.IsEnabledAsync();

Obsługiwane błędy

Usługa App Center umożliwia również śledzenie błędów przy użyciu obsługiwanych wyjątków. W tym celu użyj TrackError metody :

try {
    // your code goes here.
} catch (Exception exception) {
    Crashes.TrackError(exception);
}

Aplikacja może opcjonalnie dołączać właściwości do obsłużonego raportu o błędach w celu zapewnienia dalszego kontekstu. Przekaż właściwości jako słownik par klucz/wartość (tylko ciągi), jak pokazano w poniższym przykładzie.

try {
    // your code goes here.
} catch (Exception exception) {
    var properties = new Dictionary<string, string>
    {
        { "Category", "Music" },
        { "Wifi", "On"}
    };
    Crashes.TrackError(exception, properties); 
}

Opcjonalnie możesz również dodać załączniki binarne i tekstowe do obsłużonego raportu o błędach. Przekaż załączniki jako tablicę ErrorAttachmentLog obiektów, jak pokazano w poniższym przykładzie.

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