Falhas do App Center (Windows)

As falhas do App Center gerarão automaticamente um registro de falhas sempre que seu aplicativo falhar. O log é gravado primeiro no armazenamento do dispositivo e, quando o usuário iniciar o aplicativo novamente, o relatório de falhas será enviado para o App Center.

O SDK do App Center coleta apenas falhas causadas por exceções .NET não tratadas. Ele não coleta falhas nativas, por exemplo, ao usar C ou C++. No entanto, se tiver uma aplicação com crashes em C++, pode carregá-los para o App Center através da API de carregamento de falhas.

Siga o WPF/WinForms Getting Started se você ainda não configurou o SDK em seu aplicativo.

Exceções não tratadas em aplicativos WinForms

Por padrão, uma exceção não tratada em um aplicativo WinForms não provoca uma falha (o aplicativo não encerra) se o depurador não estiver ligado.

Em vez disso, o Windows mostra uma caixa de diálogo para o usuário a opção de continuar ou sair da execução do aplicativo. Consequentemente, o SDK do App Center não consegue capturar automaticamente essas exceções (mesmo que o usuário clique no botão Sair ).

As falhas são coletadas no App Center somente se isso fizer com que o aplicativo saia automaticamente. O App Center suporta apenas uma falha por sessão.

Há duas maneiras de relatar exceções não tratadas no WinForms. O aplicativo pode ser configurado para falhar em exceções não tratadas ou continuar em execução, mas relatar exceções não tratadas como erros de tempo de execução.

Configurar o aplicativo para sair em caso de falha

Esta é a única maneira de relatar a exceção não tratada como uma falha no App Center, para que a aplicação saia em caso de exceções não tratadas.

Para fazer isso, chame um método do Windows antes de inicializar o SDK:

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

Se essa opção não for aceitável em seu aplicativo, você poderá relatar a exceção não tratada como um erro de tempo de execução (descrito abaixo).

Relatar a exceção não tratada como um erro de tempo de execução

Se o seu aplicativo precisar continuar em execução após uma exceção não tratada, você não poderá relatar a exceção como uma falha no App Center, mas poderá relatá-la como um erro.

Para fazer isso, você pode usar o seguinte exemplo de código:

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

Gerar uma falha de teste

O App Center Crashes fornece uma API para gerar uma falha de teste para facilitar o teste do SDK. Esta API verifica se há configurações de depuração vs versão. Portanto, você só pode usá-lo durante a depuração, pois não funcionará para aplicativos de lançamento.

Crashes.GenerateTestCrash();

Obter mais informações sobre uma falha anterior

O App Center Crashes tem duas APIs que fornecem mais informações caso seu aplicativo tenha falhado.

O aplicativo travou na sessão anterior?

A qualquer momento depois de iniciar o SDK, você pode verificar se o aplicativo falhou na inicialização anterior:

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

Isso é útil caso você queira ajustar o comportamento ou a interface do usuário do seu aplicativo após a ocorrência de uma falha. Alguns desenvolvedores optam por mostrar uma interface do usuário adicional para pedir desculpas aos usuários ou querem uma maneira de entrar em contato após a ocorrência de uma falha.

Detalhes sobre o último acidente

Se o seu aplicativo travou anteriormente, você pode obter detalhes sobre a última falha.

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Existem inúmeros casos de uso para essa API, o mais comum são pessoas que chamam essa API e implementam seu delegado ou ouvinte personalizado de Falhas.

Personalize o uso do App Center Crashes

O App Center Crashes fornece callbacks para que os desenvolvedores executem ações adicionais antes e quando enviam logs de falhas para o App Center.

O acidente deve ser processado?

Defina este callback se quiser decidir se um crash específico precisa ser processado ou não. Por exemplo, pode haver uma falha no nível do sistema que você gostaria de ignorar e que não deseja enviar para o App Center.

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

Peça o consentimento do utilizador para enviar um registo de falhas

Se a privacidade do usuário for importante para você, convém obter a confirmação do usuário antes de enviar um relatório de falhas para o App Center. O SDK expõe um callback que indica ao App Center Crashes para aguardar a confirmação do utilizador antes de enviar qualquer relatório de falhas.

Se você optar por fazê-lo, você é responsável por obter a confirmação do usuário, por exemplo, através de um prompt de diálogo com uma das seguintes opções: Sempre enviar, Enviar e Não enviar. Com base na entrada, você informará ao App Center Crashes o que fazer e a falha será tratada de acordo.

O seguinte callback mostra como instruir o SDK a esperar pela confirmação do usuário antes de enviar crashes:

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

Caso você retorne true no retorno de chamada acima, seu aplicativo deve obter (usando seu próprio código) permissão de usuário e enviar uma mensagem ao SDK com o resultado usando a seguinte 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);

Obter informações sobre o estado de envio de um registo de falhas

Às vezes, você quer saber o status da falha do seu aplicativo. Um caso de uso comum é que você pode querer mostrar a interface do usuário que informa aos usuários que seu aplicativo está enviando um relatório de falhas ou, caso seu aplicativo esteja falhando rapidamente após a inicialização, você deseja ajustar o comportamento do aplicativo para garantir que os logs de falhas possam ser enviados. O App Center Crashes fornece três retornos de chamada diferentes que o utilizador pode usar no seu aplicativo para o notificar sobre o que está a acontecer.

O seguinte callback será invocado antes que o SDK envie um registo de falhas

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

No caso de termos problemas de rede ou uma interrupção no ponto de extremidade, e você reiniciar o aplicativo, SendingErrorReport é acionado novamente após a reinicialização do processo.

A função de retorno seguinte será invocada depois do SDK enviar com sucesso um relatório de falhas.

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

O seguinte callback irá ser invocado se o SDK não tiver conseguido enviar um registo de falhas.

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

Receber FailedToSendErrorReport significa que ocorreu um erro não recuperável, como ocorreu um código 4xx . Por exemplo, 401 significa que o appSecret está errado.

Esse retorno de chamada não é acionado se for um problema de rede. Nesse caso, o SDK continua tentando novamente (e também pausa novas tentativas enquanto a conexão de rede está inativa).

Adicionar anexos a um relatório de falhas

Você pode adicionar anexos binários e de texto a um relatório de falhas. O SDK irá enviá-los juntamente com o crash para que os possa ver no portal do App Center. O seguinte callback será invocado imediatamente antes de enviar a falha armazenada de lançamentos anteriores do aplicativo. Ele não será invocado quando a falha acontecer. Certifique-se de que o arquivo anexo não é nomeado minidump.dmp , pois esse nome está reservado para arquivos minidump. Aqui está um exemplo de como anexar texto e uma imagem a uma falha:

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

Ativar ou desativar falhas do App Center em tempo de execução

Você pode habilitar e desabilitar a funcionalidade Crashes do App Center em tempo de execução. Se você desativá-lo, o SDK não fará nenhum relatório de falhas para o aplicativo.

Crashes.SetEnabledAsync(false);

Para habilitar as falhas do App Center novamente, use a mesma API, mas passe true como parâmetro.

Crashes.SetEnabledAsync(true);

Você não precisa esperar essa chamada para tornar outras chamadas de API (como IsEnabledAsync) consistentes.

O estado é persistido no armazenamento do dispositivo em todas as inicializações de aplicativos.

Verifique se o App Center Crashes está ativado

Você também pode verificar se o App Center Crashes está ativado ou não:

bool isEnabled = await Crashes.IsEnabledAsync();

Erros tratados

O App Center também permite rastrear erros usando exceções manipuladas. Para fazer isso, use o TrackError método:

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

Opcionalmente, um aplicativo pode anexar propriedades a um relatório de erros manipulado para fornecer mais contexto. Passe as propriedades como um dicionário de pares chave/valor (somente strings), conforme mostrado no exemplo abaixo.

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

Opcionalmente, você também pode adicionar anexos binários e de texto a um relatório de erro manipulado. Passe os anexos como uma matriz de ErrorAttachmentLog objetos, conforme mostrado no exemplo abaixo.

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