Falhas no App Center (MAUI e Xamarin)
Importante
O Visual Studio App Center está programado para ser desativado em 31 de março de 2025. Embora você possa continuar a usar o Visual Studio App Center até que ele seja totalmente desativado, há várias alternativas recomendadas para as quais você pode considerar a migração.
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 iniciar o aplicativo novamente, o relatório de falha será enviado para o App Center. A coleta de falhas funciona para aplicativos beta e dinâmicos, ou seja, aqueles enviados ao App Store. Os logs de falha contêm informações valiosas para ajudar a corrigir a falha.
Siga a seção Introdução se você ainda não configurou o SDK em seu aplicativo.
Além disso, os logs de falha no iOS exigem Simbolização, marcar a documentação diagnóstico do App Center que explica como fornecer símbolos para seu aplicativo.
Observação
No iOS e no Mac, o SDK não salvará nenhum log de falhas se você anexou um depurador. Verifique se o depurador não está anexado quando você trava o aplicativo iOS e macOS. No Android, você pode falhar ao ter o depurador anexado, mas precisa continuar a execução depois de invadir a exceção sem tratamento.
Gerar uma falha de teste
As falhas do App Center fornecem uma API para gerar uma falha de teste para facilitar o teste do SDK. Essa API verifica se há configurações de depuração versus versão. 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 seu aplicativo tenha falhado.
O aplicativo recebeu um aviso de memória baixa na sessão anterior?
A qualquer momento após iniciar o SDK, você poderá marcar se o aplicativo recebeu um aviso de memória na sessão anterior:
bool hadMemoryWarning = await Crashes.HasReceivedMemoryWarningInLastSessionAsync();
Observação
Esse método só deve ser usado depois Crashes de iniciado, ele sempre retornará false antes de começar.
Observação
Em alguns casos, um dispositivo com memória baixa não pode enviar eventos.
O aplicativo falhou na sessão anterior?
A qualquer momento após iniciar o SDK, você poderá marcar 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 aplicativo após uma falha. Alguns desenvolvedores optam por mostrar interface do usuário adicional para pedir desculpas aos usuários ou querem uma maneira de entrar em contato após uma falha.
Observação
Esse método só deve ser usado depois Crashes de iniciado, ele sempre retornará false antes de começar.
Detalhes sobre a última falha
Se o aplicativo falhou anteriormente, você poderá obter detalhes sobre a última falha.
ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();
Observação
Esse método só deve ser usado depois Crashes de iniciado, ele sempre retornará null antes de começar.
Há vários casos de uso para essa API, o mais comum são as pessoas que chamam essa API e implementam seu representante ou ouvinte personalizado de Falhas.
Personalizar o uso de falhas do App Center
O App Center Crashes fornece retornos de chamada para que os desenvolvedores executem ações adicionais antes e ao enviar logs de falha para o App Center.
Observação
Defina o retorno de chamada antes de chamar AppCenter.Start(), uma vez que o App Center inicia o processamento falha imediatamente após o início.
A falha deve ser processada?
Defina esse retorno de chamada se você quiser 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ê 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;
};
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 informa que o App Center falha para aguardar a confirmação do usuário antes de enviar relatórios de falha.
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 caixa de diálogo com uma das seguintes opções: Sempre Enviar, Enviar e Não enviar. Com base na entrada, você informará às Falhas do App Center o que fazer e a falha será tratada de acordo.
Observação
O SDK não exibe uma caixa de diálogo para isso, o aplicativo deve fornecer sua própria interface do usuário para solicitar o consentimento do usuário.
Observação
O aplicativo não deve chamar NotifyUserConfirmation explicitamente se não implementar uma caixa de diálogo de confirmação do usuário; o módulo Falhas tratará o envio de logs para você implicitamente.
O retorno de chamada a seguir mostra como informar o SDK para aguardar a confirmação do usuário antes de enviar falhas:
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);
Como exemplo, você pode consultar nosso exemplo de caixa de diálogo personalizada.
Obter informações sobre o envio de status para um log de falhas
À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. As falhas do App Center fornecem 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 enviar 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 enviado um log de falhas
Crashes.FailedToSendErrorReport += (sender, e) =>
{
// Your code goes here.
};
FailedToSendErrorReport Receber significa que ocorreu um erro não recuperável, como um código 4xx. Por exemplo, 401 significa que o appSecret está errado.
Esse retorno de chamada não será disparado 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 os enviará junto com a falha para que você possa vê-los no portal do App Center. O retorno de chamada a seguir será invocado logo antes de enviar a falha armazenada da inicialização do aplicativo anterior. Ele não será invocado quando a falha 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 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")
};
};
Observação
Atualmente, o limite de tamanho é de 7 MB. Tentar enviar um anexo maior disparará um erro.
Habilitar ou desabilitar falhas do App Center no runtime
Você pode habilitar e desabilitar falhas do App Center em runtime. Se você desabilitar, o SDK não fará nenhum relatório de falha para o aplicativo.
Crashes.SetEnabledAsync(false);
Para habilitar falhas do App Center novamente, use a mesma API, mas passe true como um parâmetro.
Crashes.SetEnabledAsync(true);
Você não precisa aguardar essa chamada para tornar outras chamadas à API (como IsEnabledAsync) consistentes.
O estado é persistente no armazenamento do dispositivo entre as inicializações de aplicativos.
Observação
Esse método só deve ser usado depois Crashes de ter sido iniciado.
Verificar se as falhas do App Center estão habilitadas
Você também pode marcar se falhas do App Center estiverem habilitadas ou não:
bool isEnabled = await Crashes.IsEnabledAsync();
Observação
Esse método só deve ser usado depois Crashes de iniciado, ele sempre retornará false antes de começar.
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 erro 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 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);
}