Responder a eventos do sistema com tarefas em segundo planoRespond to system events with background tasks

APIs importantesImportant APIs

Saiba como criar uma tarefa em segundo plano que responda a eventos do SystemTrigger.Learn how to create a background task that responds to SystemTrigger events.

Este tópico pressupõe que você tenha uma classe de tarefa em segundo plano criada para o aplicativo e que essa tarefa precise ser executada em resposta a um evento acionado pelo sistema, como quando a disponibilidade da Internet muda ou o logon do usuário.This topic assumes that you have a background task class written for your app, and that this task needs to run in response to an event triggered by the system such as when internet availability changes or the user logging in. Este tópico se concentra na classe SystemTrigger.This topic focuses on the SystemTrigger class. Mais informações sobre como escrever uma classe de tarefa em segundo plano estão disponíveis em Criar e registrar uma tarefa em segundo plano no processo ou em Criar e registrar uma tarefa em segundo plano fora do processo.More information on writing a background task class is available in Create and register an in-process background task or Create and register an out-of-process background task.

Crie um objeto SystemTriggerCreate a SystemTrigger object

No código do seu aplicativo, crie um novo objeto SystemTrigger.In your app code, create a new SystemTrigger object. O primeiro parâmetro, triggerType, especifica o tipo de gatilho de evento do sistema que ativará esta tarefa em segundo plano.The first parameter, triggerType, specifies the type of system event trigger that will activate this background task. Para obter uma lista dos tipos de evento, consulte SystemTriggerType.For a list of event types, see SystemTriggerType.

O segundo parâmetro, OneShot, especifica se a tarefa em segundo plano só será executada uma única vez na próxima vez em que o evento do sistema ocorrer ou sempre que o evento do sistema ocorrer, até que o registro da tarefa seja cancelado.The second parameter, OneShot, specifies whether the background task will run only once the next time the system event occurs or every time the system event occurs until the task is unregistered.

O código a seguir determina que a tarefa em segundo plano seja executada sempre que a Internet ficar disponível:The following code specifies that the background task runs whenever the Internet becomes available:

SystemTrigger internetTrigger = new SystemTrigger(SystemTriggerType.InternetAvailable, false);
Windows::ApplicationModel::Background::SystemTrigger internetTrigger{
    Windows::ApplicationModel::Background::SystemTriggerType::InternetAvailable, false};
SystemTrigger ^ internetTrigger = ref new SystemTrigger(SystemTriggerType::InternetAvailable, false);

Registrar a tarefa em segundo planoRegister the background task

Registre a tarefa em segundo plano chamando sua função de registro da tarefa em segundo plano.Register the background task by calling your background task registration function. Para obter mais informações sobre como registrar tarefas em segundo plano, consulte Registrar uma tarefa em segundo plano.For more information on registering background tasks, see Register a background task.

O código a seguir registra a tarefa em segundo plano para um processo em segundo plano executado em um processo à parte.The following code registers the background task for a background process that runs out-of-process. Se você tivesse chamando uma tarefa em segundo plano executada no mesmo processo como o aplicativo de host, você não definiria entrypoint:If you were calling a background task that runs in the same process as the host app, you would not set entrypoint:

string entryPoint = "Tasks.ExampleBackgroundTaskClass"; // Namespace name, '.', and the name of the class containing the background task
string taskName   = "Internet-based background task";

BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition);
std::wstring entryPoint{ L"Tasks.ExampleBackgroundTaskClass" }; // don't set for in-process background tasks.
std::wstring taskName{ L"Internet-based background task" };

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{
    RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition) };
String ^ entryPoint = "Tasks.ExampleBackgroundTaskClass"; // don't set for in-process background tasks
String ^ taskName   = "Internet-based background task";

BackgroundTaskRegistration ^ task = RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition);

Observação

Plataforma Universal do Windows aplicativos devem chamar RequestAccessAsync antes de registrar qualquer um dos tipos de gatilho em segundo plano.Universal Windows Platform apps must call RequestAccessAsync before registering any of the background trigger types.

Para garantir que seu aplicativo Universal do Windows continue a ser executado corretamente depois que você liberar uma atualização, chame RemoveAccess e, em seguida, chame RequestAccessAsync quando seu aplicativo for iniciado após a atualização.To ensure that your Universal Windows app continues to run properly after you release an update, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. Para obter mais informações, consulte Diretrizes para tarefas em segundo plano.For more information, see Guidelines for background tasks.

Observação

Os parâmetros de registro de tarefas em segundo plano são validados no momento do registro.Background task registration parameters are validated at the time of registration. Um erro será retornado se algum parâmetro de registro for inválido.An error is returned if any of the registration parameters are invalid. 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.Ensure that your app gracefully handles scenarios where background task registration fails - if instead your app depends on having a valid registration object after attempting to register a task, it may crash.  

ComentáriosRemarks

Para ver o registro da tarefa em segundo plano em ação, baixe a amostra de tarefa em segundo plano.To see background task registration in action, download the background task sample.

Tarefas em segundo plano podem ser executadas em resposta aos eventos de SystemTrigger e MaintenanceTrigger sem entrar na tela de bloqueio, mas ainda será necessário declarar as tarefas em segundo plano no manifesto do aplicativo.Background tasks can run in response to SystemTrigger and MaintenanceTrigger events, but you still need to Declare background tasks in the application manifest. Você também deve chamar RequestAccessAsync antes de registrar qualquer tipo de tarefa em segundo plano.You must also call RequestAccessAsync before registering any background task type.

Os aplicativos com recurso de tela de bloqueio podem registrar tarefas em segundo plano que respondem aos eventos de TimeTrigger, PushNotificationTrigger e NetworkOperatorNotificationTrigger, permitindo que forneçam comunicação em tempo real com o usuário, mesmo quando o aplicativo não está em primeiro plano.Apps can register background tasks that respond to TimeTrigger, PushNotificationTrigger, and NetworkOperatorNotificationTrigger events, enabling them to provide real-time communication with the user even when the app is not in the foreground. Para obter mais informações, consulte dar suporte ao seu aplicativo com tarefas em segundo plano.For more information, see Support your app with background tasks.