Falhas no App Center (Windows)

As falhas do App Center gerarão automaticamente um log de falhas sempre que o aplicativo falhar. O log é gravado pela primeira vez no armazenamento do dispositivo e, quando o usuário inicia o aplicativo novamente, o relatório de falha será enviado para o App Center.

O SDK do App Center coleta apenas falhas causadas por exceções do .NET sem tratamento. Ele não coleta falhas nativas, por exemplo, ao usar C ou C++. No entanto, se você tiver um aplicativo com falhas do C++, poderá carregá-los no App Center por meio da API de falhas de upload.

Siga a introdução do WPF/WinForms se você ainda não configurou o SDK em seu aplicativo.

Exceções sem tratamento em aplicativos WinForms

Por padrão, uma exceção sem tratamento em um aplicativo WinForms não resulta em uma falha (o aplicativo não se encerra) se o depurador não estiver conectado.

Em vez disso, o Windows mostra uma caixa de diálogo para o usuário a opção de continuar ou encerrar a 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 Parar ).

As falhas serão coletadas no App Center somente se ele fizer com que o aplicativo saia automaticamente. O App Center dá suporte a apenas uma falha por sessão.

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

Configurar o aplicativo para sair em caso de falha

Essa é a única maneira de relatar a exceção não tratada como uma falha dentro do App Center. Isso fará com que o aplicativo saia em 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 sem tratamento como um erro de runtime (descrito abaixo).

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

Se o aplicativo precisar continuar em execução após uma exceção sem tratamento, você não poderá relatar a exceção como uma falha no App Center, mas pode denunciá-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 simular um crash de teste, facilitando o teste do SDK. Esta API verifica se as configurações são de depuração ou de lançamento. Portanto, você só pode usá-lo ao depurar, pois ele 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 o aplicativo tenha falhado.

O aplicativo falhou na sessão anterior?

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

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

Isso é útil caso você deseje ajustar o comportamento ou a interface do usuário do seu aplicativo depois que ocorreu 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 depois que ocorreu uma falha.

Detalhes sobre a última falha

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

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Há diversos casos de uso para esta API, sendo o mais comum as pessoas que chamam esta API e implementam seu delegado ou ouvinte de Erros personalizados.

Personalize o uso do recurso de falhas do App Center

O App Center Crashes fornece retornos de chamada para os desenvolvedores executarem ações adicionais antes de enviar e ao enviar relatórios de falhas para o App Center.

A falha deve ser processada?

Você pode definir este retorno de chamada caso queira decidir se uma falha específica precisa ser processada ou não. Por exemplo, pode haver uma falha no nível do sistema que você deseja 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;
};

Solicitar o consentimento do usuário para enviar um log de falhas

Se a privacidade do usuário for importante para você, talvez você queira obter a confirmação do usuário antes de enviar um relatório de falha para o App Center. O SDK expõe um retorno de chamada que indica ao App Center Crashes para aguardar a confirmação do usuário antes de enviar quaisquer relatórios de falhas.

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

O seguinte callback mostra como instruir o SDK a aguardar a 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 API a seguir.

// 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 status de envio de um relatório de erro

Às vezes, você deseja saber o status da falha do aplicativo. Um caso de uso comum é que talvez você queira mostrar a interface do usuário que informa aos usuários que seu aplicativo está enviando um relatório de falha 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 falha possam ser enviados. O App Center Crashes fornece três retornos de chamada diferentes que você pode usar em seu aplicativo para ser notificado sobre o que está acontecendo:

O retorno de chamada a seguir será invocado antes que o SDK envie um log de falhas

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

Caso tenhamos problemas de rede ou uma interrupção no ponto de extremidade e você reinicie o aplicativo, SendingErrorReport será disparado novamente após a reinicialização do processo.

O retorno de chamada a seguir será invocado depois que o SDK enviou um log de falhas com êxito

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

O retorno de chamada a seguir será invocado se o SDK não tiver conseguido enviar um relatório de falhas

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

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

Esse retorno de chamada não será ativado 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 falha

Você pode adicionar anexos binários e de texto a um relatório de falha. O SDK enviará essas informações junto com a falha, para que você possa vê-las no portal do App Center. O callback a seguir será invocado logo antes de enviar o crash armazenado dos lançamentos anteriores do aplicativo. Ele não será invocado quando o acidente acontecer. Verifique se o arquivo de anexo não está nomeado minidump.dmp , pois esse nome está reservado para arquivos de minidump. Aqui está um exemplo de como anexar texto e uma imagem a um crash:

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

Habilitar ou desabilitar falhas do App Center no tempo de execução

Você pode habilitar e desabilitar o Crashes no App Center durante o tempo de execução. Se você desabilitá-lo, o SDK não fará nenhum relatório de falha para o aplicativo.

Crashes.SetEnabledAsync(false);

Para habilitar o App Center Crashes novamente, use a mesma API, mas passe true como um parâmetro.

Crashes.SetEnabledAsync(true);

Você não precisa aguardar essa chamada para fazer outras chamadas à API (como IsEnabledAsync) consistentes.

O estado é mantido no armazenamento do dispositivo entre as inicializações do aplicativo.

Verificar se o recurso de 'Crashes' do App Center está habilitado

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

bool isEnabled = await Crashes.IsEnabledAsync();

Erros tratados

O App Center também permite que você rastreie erros usando exceções tratadas. 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 cadeias de caracteres), 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 erros 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);
}