Chybové ukončení App Center (UPW/WinUI)

Důležité

Visual Studio App Center je naplánované k vyřazení na 31. března 2025. I když můžete Visual Studio App Center dál používat, dokud ho úplně nevyřadíte, existuje několik doporučených alternativ, na které můžete migraci zvážit.

Přečtěte si další informace o časových osách a alternativách podpory.

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

Chybové ukončení app center automaticky vygeneruje protokol chybových ukončení pokaždé, když dojde k chybě aplikace. Protokol se nejprve zapíše do úložiště zařízení, a když uživatel aplikaci znovu spustí, zpráva o chybách se odešle do App Center. Shromažďování chybových ukončení funguje jak u beta aplikací, tak u aplikací odeslaných do Windows Storu. Protokoly chyb obsahují cenné informace, které vám pomůžou chyby opravit.

Sada App Center SDK shromažďuje pouze chyby způsobené neošetřenými výjimkami .NET. Neshromažďuje nativní chybové ukončení, například při použití jazyka C nebo C++. Pokud ale máte aplikaci s chybovým ukončením jazyka C++, můžete je nahrát do App Center prostřednictvím rozhraní API pro chybové ukončení nahrávání.

Pokud jste v aplikaci ještě nenastavili sadu SDK, postupujte podle Začínáme části.

Poznámka

V současné době nepodporujeme detekci upozornění na nedostatek paměti na platformě UPW/WinUI.

Přidání modulu crashes

Konzola Správce balíčků

• Otevřete konzolu v sadě Visual Studio. Uděláte to tak, že zvolíte Nástroje Konzola>Správce>balíčků NuGet.
• Zadejte následující příkazy:

Install-Package Microsoft.AppCenter.Crashes

Přidání příkazů using

Před použitím našich rozhraní API přidejte příslušné obory názvů.

using Microsoft.AppCenter.Crashes;

Start() Úprava metody

Přidejte nebo upravte následující volání konstruktoru vaší aplikace tak, aby zahrnovalo modul chybových ukončení:

AppCenter.Start("{Your App Secret}", typeof(Crashes));

Vygenerování chybového ukončení testu

Chybové ukončení app center poskytuje rozhraní API pro vygenerování testovací chyby pro snadné testování sady SDK. Toto rozhraní API kontroluje konfigurace ladění a verze. Můžete ho tedy použít jenom při ladění, protože nebude fungovat pro aplikace vydané verze.

Crashes.GenerateTestCrash();

Získání dalších informací o předchozím chybovém ukončení

Aplikace App Center crashes má dvě rozhraní API, která poskytují další informace pro případ, že dojde k chybě aplikace.

Došlo k chybě aplikace v předchozí relaci?

Kdykoli po spuštění sady SDK můžete zkontrolovat, jestli se aplikace při předchozím spuštění chybově ukončila:

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

To se hodí v případě, že chcete upravit chování nebo uživatelské rozhraní aplikace po chybovém ukončení. Někteří vývojáři se rozhodnou zobrazit další uživatelské rozhraní, aby se mohli omluvit svým uživatelům, nebo chtějí získat způsob, jak se spojit po chybovém ukončení.

Poznámka

Tato metoda musí být použita pouze po Crashes spuštění; vždy se vrátí false před spuštěním.

Podrobnosti o posledním chybovém ukončení

Pokud dříve došlo k chybovému ukončení vaší aplikace, můžete získat podrobnosti o posledním chybovém ukončení.

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Poznámka

Tato metoda musí být použita pouze po Crashes spuštění; vždy se vrátí null před spuštěním.

Pro toto rozhraní API existuje mnoho případů použití. Nejběžnějším z nich jsou lidé, kteří toto rozhraní API volají a implementují vlastního delegáta nebo naslouchacího procesu chybových ukončení.

Přizpůsobení používání chyb app center

Chybové ukončení App Center poskytuje vývojářům zpětná volání, aby mohli provádět další akce před a při odesílání protokolů chyb do App Center.

Poznámka

Před volánímAppCenter.Start()nastavte zpětné volání, protože App Center zahájí zpracování, dojde k chybovému ukončení hned po spuštění.

Mělo by se chybové ukončení zpracovat?

Toto zpětné volání nastavte, pokud se chcete rozhodnout, jestli je potřeba zpracovat konkrétní chybové ukončení. Může například dojít k chybovému ukončení na úrovni systému, které byste chtěli ignorovat a které nechcete odesílat do App Center.

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

Požádat uživatele o souhlas s odesláním protokolu chybových ukončení

Pokud je pro vás ochrana osobních údajů uživatelů důležitá, můžete před odesláním zprávy o chybách do App Center získat potvrzení uživatele. Sada SDK zveřejňuje zpětné volání, které informuje o chybovém ukončení app center, aby před odesláním případných zpráv o chybách čekalo na potvrzení uživatele.

Pokud jste to zvolili, zodpovídáte za získání potvrzení uživatele, například prostřednictvím dialogového okna s jednou z následujících možností: Vždy posílat, Posílat a Neodesílat. Na základě zadání řeknete, co dělat, když dojde k chybám App Center, a chyba se pak zpracuje odpovídajícím způsobem.

Poznámka

V sadě SDK se nezobrazuje dialogové okno, aplikace musí poskytnout vlastní uživatelské rozhraní, které může požádat o souhlas uživatele.

Poznámka

Aplikace by neměla volat NotifyUserConfirmation explicitně, pokud neimplementuje potvrzovací dialog uživatele. Modul Chybové ukončení bude zpracovávat posílá protokoly implicitně za vás.

Následující zpětné volání ukazuje, jak říct sadě SDK, aby před odesláním chybových ukončení čekala na potvrzení uživatelem:

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

V případě, že se vrátíte true ve zpětném volání výše, vaše aplikace musí získat (pomocí vlastního kódu) oprávnění uživatele a odeslat sadě SDK zprávu s výsledkem pomocí následujícího rozhraní 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);

Získání informací o stavu odesílání pro protokol chybových ukončení

Někdy chcete zjistit stav chybového ukončení aplikace. Běžným případem použití je, že můžete chtít zobrazit uživatelské rozhraní s oznámením uživatelům, že vaše aplikace odesílá zprávu o chybách, nebo v případě rychlého chybového ukončení aplikace po spuštění upravit chování aplikace, aby bylo možné odesílat protokoly chybových ukončení. Chybové ukončení App Center nabízí tři různá zpětná volání, která můžete v aplikaci použít k oznámení o tom, co se děje:

Před odesláním protokolu chyb sdk se vyvolá následující zpětné volání.

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

V případě problémů se sítí nebo výpadkem koncového bodu a vy restartujete aplikaci, SendingErrorReport se po restartování procesu aktivuje znovu.

Následující zpětné volání se vyvolá poté, co sada SDK úspěšně odeslala protokol chybových ukončení.

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

Následující zpětné volání se vyvolá, pokud se sadě SDK nepodařilo odeslat protokol chybových ukončení.

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

Příjem FailedToSendErrorReport znamená, že došlo k neopravitelné chybě, například k kódu 4xx . Například 401 znamená, že je špatně appSecret .

Toto zpětné volání se neaktivuje, pokud se jedná o problém se sítí. V tomto případě sada SDK pokračuje v opakování (a také pozastavuje opakování, když je síťové připojení mimo provoz).

Přidání příloh ke zprávě o chybách

Do zprávy o chybách můžete přidat binární a textové přílohy. Sada SDK je odešle spolu s chybovým ukončením, abyste je viděli na portálu App Center. Následující zpětné volání se vyvolá těsně před odesláním uloženého chybového ukončení z předchozích spuštění aplikace. Nebude vyvolána, když dojde k chybě. Ujistěte se, že soubor přílohy nemá název minidump.dmp , protože tento název je vyhrazený pro soubory s minidumpem. Tady je příklad připojení textu a obrázku k chybovému ukončení:

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

Poznámka

Limit velikosti je aktuálně 7 MB. Pokus o odeslání větší přílohy způsobí chybu.

Povolení nebo zakázání chyb app center za běhu

Za běhu můžete povolit a zakázat chybové ukončení App Center. Pokud ho zakážete, sada SDK nebude pro aplikaci hlásit žádné chybové ukončení.

Crashes.SetEnabledAsync(false);

Pokud chcete znovu povolit chybové ukončení app center, použijte stejné rozhraní API, ale předejte true ho jako parametr.

Crashes.SetEnabledAsync(true);

Toto volání nemusíte čekat, aby ostatní volání rozhraní API (například IsEnabledAsync) byla konzistentní.

Stav se během spouštění aplikací zachová v úložišti zařízení.

Kontrola, jestli je povolená chyba app center

Můžete také zkontrolovat, jestli je povolená chyba App Center:

bool isEnabled = await Crashes.IsEnabledAsync();

Zpracovávané chyby

App Center také umožňuje sledovat chyby pomocí zpracovaných výjimek. Použijte k tomu metodu TrackError :

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

Aplikace může volitelně připojit vlastnosti ke zpracovávané zprávě o chybách a poskytnout tak další kontext. Předejte vlastnosti jako slovník dvojic klíč/hodnota (pouze řetězce), jak je znázorněno v následujícím příkladu.

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

Do sestavy zpracovávané chyby můžete také volitelně přidat binární a textové přílohy. Předejte přílohy jako pole ErrorAttachmentLog objektů, jak je znázorněno v následujícím příkladu.

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