Depurar uma tarefa em segundo plano

  • Artigo

APIs importantes

Aprenda a depurar uma tarefa em segundo plano, incluindo ativação e rastreamento de depuração de tarefas em segundo plano no log de eventos do Windows.

Depurando tarefas em segundo plano fora do processo vs. no processo

Este tópico aborda principalmente tarefas em segundo plano que são executadas em um processo separado do aplicativo host. Se você estiver depurando uma tarefa em segundo plano no processo, não terá um projeto de tarefa em segundo plano separado e poderá definir um ponto de interrupção em OnBackgroundActivated() (onde o código em segundo plano em processo é executado) e verá a etapa 2 em Disparar tarefas em segundo plano manualmente para depurar o código da tarefa em segundo plano, abaixo, para obter instruções sobre como disparar seu código em segundo plano para executar.

Verificar se o projeto de tarefa em segundo plano está configurado corretamente

Este tópico pressupõe que você já tenha um aplicativo com uma tarefa em segundo plano para depurar. As instruções a seguir são específicas de tarefas em segundo plano que são executadas fora do processo e não se aplicam a tarefas em segundo plano no processo.

  • Em C# e C++, verifique se o projeto principal faz referência ao projeto de tarefa em segundo plano. Se essa referência não estiver em vigor, a tarefa em segundo plano não será incluída no pacote de aplicativo.
  • Em C# e C++, verifique se o Tipo de saída do projeto de tarefa em segundo plano é "componente do Tempo de Execução do Windows".
  • A classe de segundo plano deve ser declarada no atributo de ponto de entrada no manifesto do pacote.

Disparar tarefas em segundo plano manualmente para depurar o código dessas tarefas

As tarefas em segundo plano podem ser ativadas manualmente por meio do Microsoft Visual Studio. Em seguida, você pode percorrer o código e depurá-lo.

  1. Em C#, insira um ponto de interrupção no método Run da classe em segundo plano (para tarefas em segundo plano no processo, coloque o ponto de interrupção em App.OnBackgroundActivated()) e/ou crie a saída de depuração usando System.Diagnostics.

    Em C++, insira um ponto de interrupção na função Run da classe em segundo plano (para tarefas em segundo plano no processo, coloque o ponto de interrupção em App.OnBackgroundActivated()) e/ou crie a saída de depuração usando OutputDebugString.

  2. Execute seu aplicativo no depurador e, em seguida, dispare a tarefa em segundo plano usando a barra de ferramentas Eventos de Ciclo de Vida. Esse menu suspenso mostra os nomes das tarefas em segundo plano que podem ser ativadas pelo Visual Studio.

    Observação

    As opções da barra de ferramentas Eventos do Ciclo de Vida não são mostradas por padrão no Visual Studio. Para mostrar essas opções, clique com o botão direito do mouse na barra de ferramentas atual no Visual Studio e verifique se a opção Local de Depuração está habilitada.

    Para que isso funcione, a tarefa em segundo plano já deve ter sido registrada e ainda deve estar aguardando ser acionada. Por exemplo, se a tarefa em segundo plano foi registrada com um TimeTrigger único e esse gatilho já tiver sido disparado, iniciar a tarefa através do Visual Studio não produzirá nenhum efeito.

    Observação

    Tarefas em segundo plano que usam os seguintes gatilhos não podem ser ativadas dessa maneira: gatilho de aplicativo, gatilho MediaProcessing, ControlChannelTrigger, PushNotificationTrigger e tarefas em segundo plano usando um SystemTrigger com o tipo de gatilho SmsReceived .
    O Gatilho de aplicativo e o MediaProcessingTrigger podem ser sinalizados manualmente no código com trigger.RequestAsync().

    depurando tarefas em segundo plano

  3. Quando a tarefa em segundo plano é ativada, o depurador é anexado a ela e exibe a saída da depuração no VS.

Depurar a ativação de tarefas em segundo plano

Observação

Esta seção é específica de tarefas em segundo plano que são executadas fora do processo e não se aplica a tarefas em segundo plano no processo.

A ativação da tarefa em segundo plano depende de três coisas:

  • O nome e o namespace da classe de tarefa em segundo plano
  • O atributo de ponto de entrada especificado no manifesto do pacote
  • O ponto de entrada especificado pelo seu aplicativo durante o registro da tarefa em segundo plano

  1. Use o Visual Studio para anotar o ponto de entrada da tarefa em segundo plano:

    • Em C# e C++, anote o nome e o namespace da classe de tarefa em segundo plano especificada no projeto de tarefa em segundo.

  2. Use o designer de manifesto para conferir se a tarefa em segundo plano está declarada corretamente no manifesto do pacote:

    • Em C# e C++, o atributo de ponto de entrada deve corresponder ao namespace da tarefa em segundo plano, seguido do nome da classe. Por exemplo: RuntimeComponent1.MyBackgroundTask.
    • Todo(s) o(s) tipo(s) de gatilho usado(s) com a tarefa também deve(m) ser especificado(s).
    • O executável NÃO DEVE ser especificado, a não ser que você esteja usando ControlChannelTrigger ou PushNotificationTrigger.

  3. Somente Windows. Para ver o ponto de entrada usado pelo Windows para ativar a tarefa em segundo plano, habilite o rastreamento de depuração e use o log de eventos do Windows.

    Se você seguir este procedimento, e o log de eventos mostrar o gatilho ou ponto de entrada incorreto para a tarefa em segundo plano, é sinal de que o seu aplicativo não está registrando essa tarefa corretamente. Para obter ajuda com essa tarefa, consulte Registrar uma tarefa em segundo plano.

    1. Abra o visualizador de eventos acessando a tela inicial e procurando eventvwr.exe.
    2. Acesse Logs de Aplicativos e Serviços ->Microsoft ->Windows ->BackgroundTaskInfrastructure no visualizador de eventos.
    3. No painel ações, selecione Exibir ->Mostrar Logs de Análise e Depuração para habilitar o log de diagnóstico.
    4. Selecione o Log de diagnósticos e clique em Habilitar Log.
    5. Agora, tente usar seu aplicativo para registrar e ativar a tarefa em segundo plano de novo.
    6. Examine os logs de diagnósticos para obter detalhes dos erros. Essas informações incluirão o ponto de entrada registrada para a tarefa em segundo plano.

visualizador de eventos para informações de depuração das tarefas em segundo plano

Implantação do pacote Visual Studio e tarefas em segundo plano

Se um aplicativo que usa tarefas em segundo plano for implantado usando o Visual Studio e a versão (principal e/ou secundária) especificada no Manifest Designer for atualizada, a implantação posterior do aplicativo com o Visual Studio poderá fazer com que as tarefas em segundo plano do aplicativo fiquem paralisadas. Isso pode ser remediado da seguinte maneira:

  • Use o Windows PowerShell para implantar o aplicativo atualizado (em vez do Visual Studio) executando o script gerado junto com o pacote.
  • Se você já implantou o aplicativo usando o Visual Studio e suas tarefas em segundo plano estão paralisadas, reinicie ou faça logoff/faça logon para que as tarefas em segundo plano do aplicativo funcionem novamente.
  • Você pode selecionar a opção de depuração "Sempre reinstalar meu pacote" para evitar isso em projetos C#.
  • Aguarde até que o aplicativo esteja pronto para a implantação final para incrementar a versão do pacote (não altere-a durante a depuração).

Comentários

  • Veja se seu aplicativo verifica os registros de tarefas em segundo plano existentes antes de registrar novamente a tarefa em segundo plano. Vários registros da mesma tarefa em segundo plano podem causar resultados inesperados ao executarem a tarefa em segundo plano mais de uma vez sempre que ela é disparada.
  • Se a tarefa em segundo plano exigir acesso à tela de bloqueio, coloque o aplicativo na tela de bloqueio antes de tentar depurar essa tarefa. Para obter informações sobre como especificar opções de manifesto para aplicativos compatíveis com a tela de bloqueio, consulte Declarar tarefas em segundo plano no manifesto do aplicativo.
  • Os parâmetros de registro de tarefas em segundo plano são validados no momento do registro. Um erro será retornado se algum parâmetro de registro for inválido. Verifique se o aplicativo trata tranquilamente cenários em que o registro de tarefas de segundo plano apresenta falha. Se, em vez disso, o aplicativo depender de ter um objeto de registro válido depois de tentar registrar uma tarefa, ele poderá travar.

Para obter mais informações sobre como usar o VS para depurar uma tarefa em segundo plano , consulte Como disparar eventos de suspensão, retomada e em segundo plano em aplicativos UWP.