Compartilhar via

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 versus em 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 no processo é executado) e consulte 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 a execução do código em segundo plano.

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

Este tópico pressupõe que você já tenha um aplicativo existente com uma tarefa em segundo plano para depurar. O seguinte é específico para tarefas em segundo plano que são executadas fora do processo e não se aplica 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 do 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 plano de fundo deve ser declarada no atributo de ponto de entrada no manifesto do pacote.

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

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

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

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

  2. Execute seu aplicativo no depurador e dispare a tarefa em segundo plano usando a barra de ferramentas Eventos do Ciclo de Vida. Essa lista suspensa 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 estar registrada e ainda deve estar aguardando o gatilho. Por exemplo, se uma tarefa em segundo plano foi registrada com um TimeTrigger único e esse gatilho já foi disparado, iniciar a tarefa por meio do Visual Studio não terá efeito.

    Observação

    As 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 do 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 for ativada, o depurador será anexado a ela e exibirá a saída de depuração no VS.

Depurar ativação de tarefa em segundo plano

Observação

Esta seção é específica para tarefas em segundo plano que são executadas fora do processo e não se aplica a tarefas em segundo plano em 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 aplicativo ao registrar a tarefa em segundo plano

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

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

  2. Use o designer de manifesto para verificar 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 pelo nome da classe. Por exemplo: RuntimeComponent1.MyBackgroundTask.
    • Todos os tipos de gatilho usados com a tarefa também devem ser especificados.
    • O executável NÃO DEVE ser especificado, a menos que você esteja usando o 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 ponto de entrada ou gatilho errado para a tarefa em segundo plano, seu aplicativo não está registrando a tarefa em segundo plano 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 pesquisando eventvwr.exe.
    2. Vá para Logs de Aplicativos e Serviços ->Microsoft ->Windows ->BackgroundTaskInfrastructure no visualizador de eventos.
    3. No painel de 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óstico e clique em Ativar log.
    5. Agora tente usar seu aplicativo para registrar e ativar a tarefa em segundo plano novamente.
    6. Exiba os logs de diagnóstico para obter informações detalhadas sobre o erro. Isso incluirá o ponto de entrada registrado para a tarefa em segundo plano.

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

Tarefas em segundo plano e implantação de pacote do Visual Studio

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 Designer de Manifesto for atualizada, a reimplantação subsequente do aplicativo com o Visual Studio poderá fazer com que as tarefas em segundo plano do aplicativo sejam interrompidas. Isso pode ser corrigido 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 agora estão paralisadas, reinicialize ou faça logoff/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 a altere durante a depuração).

Comentários

  • Verifique se o aplicativo verifica se há registros de tarefas em segundo plano existentes antes de registrar a tarefa em segundo plano novamente. Vários registros da mesma tarefa em segundo plano podem causar resultados inesperados executando a tarefa em segundo plano mais de uma vez cada vez que ela é disparada.
  • Se a tarefa em segundo plano exigir acesso à tela de bloqueio, certifique-se de colocar o aplicativo na tela de bloqueio antes de tentar depurar a tarefa em segundo plano. Para obter informações sobre como especificar opções de manifesto para aplicativos compatíveis com tela de bloqueio, consulte Declarar tarefas em segundo plano no manifesto do aplicativo.
  • Os parâmetros de registro de tarefa em segundo plano são validados no momento do registro. Um erro será retornado se qualquer um dos parâmetros de registro for inválido. Certifique-se de que seu aplicativo lide normalmente com cenários em que o registro de tarefa em segundo plano falha – se, em vez disso, seu aplicativo depender de ter um objeto de registro válido depois de tentar registrar uma tarefa, ele poderá falhar.

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.