Como registrar uma tarefa em segundo plano (HTML)
[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]
Aprenda a criar uma função que pode ser reutilizada para registrar com segurança a maioria das tarefas em segundo plano. Este tópico discorre sobre a função utilitária que registra tarefas em segundo plano. Esta função utilitária verifica registros existentes antes de registrar a tarefa várias vezes para evitar problemas com registros múltiplos e pode aplicar uma condição de sistema à tarefa em segundo plano. O tópico inclui um exemplo completo e prático desta função utilitária.
Observação
Para os aplicativos da Loja do Windows Phone, você deve chamar RequestAccessAsync antes de tentar registrar qualquer tarefa em segundo plano. No Windows, essa chamada é necessária somente para configurar tarefas em segundo plano que podem executar somente se seu aplicativo estiver na tela de bloqueio, mas no telefone você deve chamar esse método uma vez para poder registrar qualquer tarefa em segundo plano.
Para garantir que seu aplicativo do Windows Phone continua 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. Para saber mais, consulte Diretrizes para tarefas em segundo plano (HTML).
O que você precisa saber
Tecnologias
Pré-requisitos
- Este tópico pressupõe que você já possui uma tarefa em segundo plano que precisa ser registrada (o tópico não ensina a criar uma tarefa em segundo plano).
Instruções
Etapa 1: Definir a assinatura da função
Esta função obtém o ponto de entrada da tarefa, seu nome, um gatilho de tarefa em segundo plano pré-construído e (opcionalmente) uma SystemCondition para a tarefa em segundo plano. Observe que esta função retornará um objeto BackgroundTaskRegistration.
function RegisterBackgroundTask(taskEntryPoint,
taskName,
trigger,
condition)
{
// We’ll add code to this function in subsequent steps.
}
Etapa 2: Verificar registros existentes
Verifique se a tarefa já está registrada. É importante verificar isso porque, se a tarefa for registrada várias vezes, ela será executada mais de uma vez sempre que for disparada; isso pode utilizar cota excessiva de CPU e causar comportamentos inesperados.
Você pode verificar se existem registros consultando a propriedade BackgroundTaskRegistration.AllTasks e iterando no resultado. Verifique o nome de cada instância – se ele corresponder ao nome da tarefa que você está registrando, interrompa o loop e defina uma variável de sinalização, para que seu código possa escolher outro caminho na próxima etapa.
Observação Use nomes de tarefas em segundo plano exclusivos para seu aplicativo. Verifique se cada tarefa em segundo plano possui um nome exclusivo.
O código abaixo registra uma tarefa em segundo plano usando o SystemTrigger que criamos na última etapa:
function RegisterBackgroundTask(taskEntryPoint,
taskName,
trigger,
condition)
{
//
// Check for existing registrations of this background task.
//
var taskRegistered = false;
var background = Windows.ApplicationModel.Background;
var iter = background.BackgroundTaskRegistration.allTasks.first();
var hascur = iter.hasCurrent;
while (hascur) {
var cur = iter.current.value;
if (cur.name === taskName) {
taskRegistered = true;
break;
}
hascur = iter.moveNext();
}
// We’ll register the task in the next step.
}
Etapa 3: Registrar a tarefa em segundo plano (ou retornar ao registro existente)
Verifique se a tarefa foi encontrada na lista de registros de tarefas em segundo plano existentes. Caso afirmativo, retorne aquela instância da tarefa.
Em seguida, registre a tarefa usando um novo objeto BackgroundTaskBuilder. Este código deve verificar se o parâmetro da condição é nulo e, se não for, adicionar a condição ao objeto de registro. Retorne a BackgroundTaskRegistration retornada pela função BackgroundTaskBuilder.Register.
Observação
A partir do Windows 8.1, os parâmetros de registro de tarefas de segundo plano são validados no momento do registro. Um erro será retornado se algum parâmetro de registro for inválido. Seu aplicativo deve ser capaz de manipular cenários em que o registro de tarefas de segundo plano apresenta falha - por exemplo, use uma instrução condicional para verificar se há erros de registro e tente novamente o registro com falha usando valores de parâmetros diferentes.
O exemplo a seguir retorna a tarefa existente ou adiciona código que registra a tarefa em segundo plano (incluindo a condição de sistema opcional, se presente):
function RegisterBackgroundTask(taskEntryPoint,
taskName,
trigger,
condition)
{
//
// Check for existing registrations of this background task.
//
var taskRegistered = false;
var background = Windows.ApplicationModel.Background;
var iter = background.BackgroundTaskRegistration.allTasks.first();
var hascur = iter.hasCurrent;
while (hascur) {
var cur = iter.current.value;
if (cur.name === taskName) {
taskRegistered = true;
break;
}
hascur = iter.moveNext();
}
//
// If the task is already registered, return the registration object.
//
if (taskRegistered == true) {
return iter.current;
}
//
// Register the background task.
//
var builder = new background.BackgroundTaskBuilder();
builder.Name = taskName;
builder.TaskEntryPoint = taskEntryPoint;
builder.setTrigger(trigger);
if (condition != null) {
builder.addCondition(condition);
}
var task = builder.register();
return task;
}
Complete a função utilitária de registro de tarefa em segundo plano
Este exemplo mostra a função completa de registro de tarefa em segundo plano. Esta função pode ser usada para registrar a maioria das tarefas em segundo plano, com exceção das tarefas em segundo plano de rede.
//
// Register a background task with the specified taskEntryPoint, name, trigger,
// and condition (optional).
//
// taskEntryPoint: Task entry point for the background task.
// taskName: A name for the background task.
// trigger: The trigger for the background task.
// condition: Optional parameter. A conditional event that must be true for the task to fire.
//
function RegisterBackgroundTask(taskEntryPoint,
taskName,
trigger,
condition)
{
//
// Check for existing registrations of this background task.
//
var taskRegistered = false;
var background = Windows.ApplicationModel.Background;
var iter = background.BackgroundTaskRegistration.allTasks.first();
var hascur = iter.hasCurrent;
while (hascur) {
var cur = iter.current.value;
if (cur.name === taskName) {
taskRegistered = true;
break;
}
hascur = iter.moveNext();
}
//
// If the task is already registered, return the registration object.
//
if (taskRegistered == true) {
return iter.current;
}
//
// Register the background task.
//
var builder = new background.BackgroundTaskBuilder();
builder.Name = taskName;
builder.TaskEntryPoint = taskEntryPoint;
builder.setTrigger(trigger);
if (condition != null) {
builder.addCondition(condition);
}
var task = builder.register();
return task;
}
Tópicos relacionados
Guia de início rápido: criar e registrar uma tarefa em segundo plano
Como responder a eventos do sistema com tarefas em segundo plano
Como definir condições para execução de uma tarefa em segundo plano
Como usar gatilhos de manutenção
Como manipular uma tarefa em segundo plano cancelada
Como monitorar progresso e conclusão de tarefas em segundo plano
Como executar uma tarefa em segundo plano em um temporizador