Compartilhar via

Usar um gatilho de manutenção

APIs importantes

Saiba como usar a classe MaintenanceTrigger para executar código leve em segundo plano enquanto o dispositivo está conectado.

Criar um objeto de gatilho de manutenção

Este exemplo pressupõe que você tenha um código leve que pode ser executado em segundo plano para aprimorar seu aplicativo enquanto o dispositivo está conectado. Este tópico se concentra no MaintenanceTrigger, que é semelhante ao SystemTrigger.

Mais informações sobre como escrever uma classe de tarefa em segundo plano estão disponíveis no Criar e registrar uma tarefa em segundo plano no processo ou Criar e registrar uma tarefa em segundo plano fora do processo.

Crie um novo objeto MaintenanceTrigger. O segundo parâmetro, do OneShot, especifica se a tarefa de manutenção será executada apenas uma vez ou continuará a ser executada periodicamente. Se OneShot for definido como true, o primeiro parâmetro (FreshnessTime) especifica o número de minutos a esperar antes de agendar a tarefa em segundo plano. Se OneShot estiver definido como false, FreshnessTime especifica a frequência com que a tarefa em segundo plano será executada.

Observação

Se FreshnessTime for definido como menos de 15 minutos, uma exceção será gerada ao tentar registrar a tarefa em segundo plano.

Este código de exemplo cria um gatilho que é executado uma vez por hora.

uint waitIntervalMinutes = 60;
MaintenanceTrigger taskTrigger = new MaintenanceTrigger(waitIntervalMinutes, false);

uint32_t waitIntervalMinutes{ 60 };
Windows::ApplicationModel::Background::MaintenanceTrigger taskTrigger{ waitIntervalMinutes, false };

unsigned int waitIntervalMinutes = 60;
MaintenanceTrigger ^ taskTrigger = ref new MaintenanceTrigger(waitIntervalMinutes, false);

(Opcional) Adicionar uma condição

  • Se necessário, crie uma condição de tarefa em segundo plano para controlar quando a tarefa for executada. Uma condição impede que sua tarefa em segundo plano seja executada até que a condição seja atendida – para obter mais informações, consulte Definir condições para executar uma tarefa em segundo plano

Neste exemplo, a condição é definida como InternetAvailable para que a manutenção seja executada quando a Internet estiver disponível (ou quando ela estiver disponível). Para obter uma lista de possíveis condições de tarefa em segundo plano, consulte SystemConditionType.

O código a seguir adiciona uma condição ao construtor de tarefas de manutenção:

SystemCondition exampleCondition = new SystemCondition(SystemConditionType.InternetAvailable);

Windows::ApplicationModel::Background::SystemCondition exampleCondition{
    Windows::ApplicationModel::Background::SystemConditionType::InternetAvailable };

SystemCondition ^ exampleCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);

Registrar a tarefa em segundo plano

  • Registre a tarefa em segundo plano chamando sua função de registro de tarefa em segundo plano. Para obter mais informações sobre como registrar tarefas em segundo plano, consulte Registrar uma tarefa em segundo plano.

O código a seguir registra a tarefa de manutenção. Observe que ele pressupõe que sua tarefa em segundo plano seja executada em um processo separado do seu aplicativo porque especifica entryPoint. Se a tarefa em segundo plano for executada no mesmo processo que seu aplicativo, você não especifica entryPoint.

string entryPoint = "Tasks.ExampleBackgroundTaskClass";
string taskName   = "Maintenance background task example";

BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition);

std::wstring entryPoint{ L"Tasks.ExampleBackgroundTaskClass" };
std::wstring taskName{ L"Maintenance background task example" };

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{
    RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition) };

String ^ entryPoint = "Tasks.ExampleBackgroundTaskClass";
String ^ taskName   = "Maintenance background task example";

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

Observação

Para todas as famílias de dispositivos, exceto a área de trabalho, se o dispositivo ficar com pouca memória, as tarefas em segundo plano poderão ser encerradas. Se uma exceção de memória insuficiente não for exibida ou o aplicativo não a manipular, a tarefa em segundo plano será encerrada sem aviso e sem disparar o evento OnCanceled. Isso ajuda a garantir que a experiência do usuário com o aplicativo permaneça em primeiro plano. Sua tarefa em segundo plano deve ser projetada para lidar com esse cenário.

Observação

Aplicativos da Plataforma Universal do Windows devem chamar RequestAccessAsync antes de registrar qualquer um dos tipos de gatilho em segundo plano.

Para garantir que seu aplicativo Universal do Windows continue sendo executado corretamente depois de lançar uma atualização para seu aplicativo, você deve chamar RemoveAccess e, em seguida, chamar RequestAccessAsync quando seu aplicativo for iniciado após ser atualizado. Para obter mais informações, consulte Diretrizes para tarefas em segundo plano.

Observação

Os parâmetros de registro de tarefa em segundo plano são validados no momento do registro. Um erro será retornado se algum dos parâmetros de registro for inválido. Verifique se seu aplicativo manipula normalmente cenários em que o registro de tarefas 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.