Compartilhar via

Usar um gatilho de manutenção

  • Artigo

APIs importantes

Saiba como usar a classe MaintenanceTrigger para executar um código leve em segundo plano enquanto o dispositivo estiver 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 em Criar e registrar uma tarefa em segundo plano em processo ou Criar e registrar uma tarefa em segundo plano fora do processo.

Crie um novo objeto MaintenanceTrigger. O segundo parâmetro, OneShot, especifica se a tarefa de manutenção será executada apenas uma vez ou continuará a ser executada periodicamente. Se OneShot estiver definido como true, o primeiro parâmetro (FreshnessTime) especificará o número de minutos a aguardar antes de agendar a tarefa em segundo plano. Se OneShot for definido como false, FreshnessTime especificará 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á lançada 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 é 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 se tornar 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 o aplicativo, você não especificará 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 desktop, 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 lidar com ela, a tarefa em segundo plano será encerrada sem aviso e sem gerar o evento OnCanceled. Isso ajuda a garantir a experiência do usuário do aplicativo em primeiro plano. Sua tarefa em segundo plano deve ser projetada para lidar com esse cenário.

Observação

Os 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 a ser executado corretamente depois que você 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 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.