Partilhar via

Falhas do App Center (UWP/WinUI)

Importante

O Visual Studio App Center foi desativado em 31 de março de 2025, exceto para os recursos de Análise e Diagnóstico, que continuarão a ter suporte até 30 de junho de 2026. Mais informações.

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. A recolha de falhas funciona tanto para as aplicações beta como para as que são submetidas à Loja Windows. Os registos de falhas contêm informações valiosas para ajudar a corrigir as falhas.

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 a seção Introdução se ainda não configurou o SDK em seu aplicativo.

Observação

Atualmente, não suportamos a deteção de avisos de memória insuficiente na plataforma UWP/WinUI.

Adicionando o módulo de falhas

Console do Gestor de Pacotes

  • Abra o console no Visual Studio. Para fazer isso, escolha Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes.
  • Escreva os seguintes comandos:
Install-Package Microsoft.AppCenter.Crashes

Adicionar as declarações using

Adicione os namespaces apropriados antes de usar nossas APIs.

using Microsoft.AppCenter.Crashes;

Modificar o Start() método

Adicione ou edite a seguinte chamada ao construtor do seu aplicativo para incluir o módulo crashes:

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

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.

Observação

Este método só deve ser usado depois de Crashes iniciado, ele sempre retornará false antes do início.

Detalhes sobre o último acidente

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

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

Observação

Este método só deve ser usado depois de Crashes iniciado, ele sempre retornará null antes do início.

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.

Observação

Defina o callback antes de invocar AppCenter.Start(), pois o App Center começa a processar erros logo após o início.

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

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.

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 lidará com o envio de logs para você implicitamente.

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

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

Observação

Atualmente, o limite de tamanho é de 7 MB. A tentativa de enviar um anexo maior desencadeará um erro.

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);
}
  • Last updated on