Tratar uma tarefa em segundo plano cancelada

Artigo
07/04/2024

APIs importantes

Saiba como criar uma tarefa em segundo plano que reconheça uma solicitação de cancelamento, interrompa o trabalho e relate o cancelamento ao aplicativo usando o armazenamento persistente.

Este tópico pressupõe que você já tenha criado uma classe de tarefa em segundo plano, incluindo o método Run que é usado como o ponto de entrada da tarefa em segundo plano. Para começar a criar rapidamente uma tarefa em segundo plano, consulte Criar e registrar uma tarefa em segundo plano fora do processo ou Criar e registrar uma tarefa em segundo plano em processo. Para obter informações mais detalhadas sobre condições e gatilhos, consulte Dar suporte ao seu aplicativo com tarefas em segundo plano.

Este tópico também é aplicável a tarefas em segundo plano no processo. Mas, em vez do método Run , substitua OnBackgroundActivated. As tarefas em segundo plano em processo não exigem que você use o armazenamento persistente para sinalizar o cancelamento, pois você pode comunicar o cancelamento usando o estado do aplicativo, pois a tarefa em segundo plano está em execução no mesmo processo que o aplicativo em primeiro plano.

Usar o método OnCanceled para reconhecer solicitações de cancelamento

Escreva um método para manipular o evento de cancelamento.

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.

Crie um método chamado OnCanceled da seguinte maneira. Esse método é o ponto de entrada chamado pelo Tempo de Execução do Windows quando uma solicitação de cancelamento é feita em sua tarefa em segundo plano.

private void OnCanceled(
    IBackgroundTaskInstance sender,
    BackgroundTaskCancellationReason reason)
{
    // TODO: Add code to notify the background task that it is cancelled.
}

void ExampleBackgroundTask::OnCanceled(
    Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance,
    Windows::ApplicationModel::Background::BackgroundTaskCancellationReason reason)
{
    // TODO: Add code to notify the background task that it is cancelled.
}

void ExampleBackgroundTask::OnCanceled(
    IBackgroundTaskInstance^ taskInstance,
    BackgroundTaskCancellationReason reason)
{
    // TODO: Add code to notify the background task that it is cancelled.
}

Adicione uma variável de sinalizador chamada _CancelRequested à classe de tarefa em segundo plano. Essa variável será usada para indicar quando uma solicitação de cancelamento foi feita.

volatile bool _CancelRequested = false;

private:
    volatile bool m_cancelRequested;

private:
    volatile bool CancelRequested;

No método OnCanceled criado na etapa 1, defina a variável de sinalizador _CancelRequested como true.

O método OnCanceled de exemplo de tarefa em segundo plano completo define _CancelRequested como true e grava uma saída de depuração potencialmente útil.

private void OnCanceled(IBackgroundTaskInstance sender, BackgroundTaskCancellationReason reason)
{
    // Indicate that the background task is canceled.
    _cancelRequested = true;

    Debug.WriteLine("Background " + sender.Task.Name + " Cancel Requested...");
}

void ExampleBackgroundTask::OnCanceled(
    Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance,
    Windows::ApplicationModel::Background::BackgroundTaskCancellationReason reason)
{
    // Indicate that the background task is canceled.
    m_cancelRequested = true;
}

void ExampleBackgroundTask::OnCanceled(IBackgroundTaskInstance^ taskInstance, BackgroundTaskCancellationReason reason)
{
    // Indicate that the background task is canceled.
    CancelRequested = true;
}

No método Run da tarefa em segundo plano, registre o método do manipulador de eventos OnCanceled antes de iniciar o trabalho. Em uma tarefa em segundo plano em processo, você pode fazer esse registro como parte da inicialização do aplicativo. Por exemplo, use a seguinte linha de código.

taskInstance.Canceled += new BackgroundTaskCanceledEventHandler(OnCanceled);

taskInstance.Canceled({ this, &ExampleBackgroundTask::OnCanceled });

taskInstance->Canceled += ref new BackgroundTaskCanceledEventHandler(this, &ExampleBackgroundTask::OnCanceled);

Lidar com o cancelamento saindo da tarefa em segundo plano

Quando uma solicitação de cancelamento é recebida, seu método que faz o trabalho em segundo plano precisa parar o trabalho e sair reconhecendo quando _cancelRequested está definido como true. Para tarefas em segundo plano no processo, isso significa retornar do método OnBackgroundActivated . Para tarefas em segundo plano fora do processo, isso significa retornar do método Run .

Modifique o código da classe de tarefa em segundo plano para verificar a variável de sinalizador enquanto ela está funcionando. Se _cancelRequested for definido como true, interrompa a continuação do trabalho.

O exemplo de tarefa em segundo plano inclui uma verificação que interrompe o retorno de chamada do temporizador periódico se a tarefa em segundo plano for cancelada.

if ((_cancelRequested == false) && (_progress < 100))
{
    _progress += 10;
    _taskInstance.Progress = _progress;
}
else
{
    _periodicTimer.Cancel();
    // TODO: Record whether the task completed or was cancelled.
}

if (!m_cancelRequested && m_progress < 100)
{
    m_progress += 10;
    m_taskInstance.Progress(m_progress);
}
else
{
    m_periodicTimer.Cancel();
    // TODO: Record whether the task completed or was cancelled.
}

if ((CancelRequested == false) && (Progress < 100))
{
    Progress += 10;
    TaskInstance->Progress = Progress;
}
else
{
    PeriodicTimer->Cancel();
    // TODO: Record whether the task completed or was cancelled.
}

Observação

O exemplo de código mostrado acima usa o IBackgroundTaskInstance.Progress sendo usada para registrar o progresso da tarefa em segundo plano. O progresso é relatado de volta ao aplicativo usando a classe BackgroundTaskProgressEventArgs.

Modifique o método Run para que, após a interrupção do trabalho, ele registre se a tarefa foi concluída ou cancelada. Esta etapa se aplica a tarefas em segundo plano fora do processo porque você precisa de uma maneira de se comunicar entre os processos quando a tarefa em segundo plano foi cancelada. Para tarefas em segundo plano no processo, você pode simplesmente compartilhar o estado com o aplicativo para indicar que a tarefa foi cancelada.

O exemplo de tarefa em segundo plano registra o status em LocalSettings.

if ((_cancelRequested == false) && (_progress < 100))
{
    _progress += 10;
    _taskInstance.Progress = _progress;
}
else
{
    _periodicTimer.Cancel();

    var settings = ApplicationData.Current.LocalSettings;
    var key = _taskInstance.Task.TaskId.ToString();

    // Write to LocalSettings to indicate that this background task ran.
    if (_cancelRequested)
    {
        settings.Values[key] = "Canceled";
    }
    else
    {
        settings.Values[key] = "Completed";
    }
        
    Debug.WriteLine("Background " + _taskInstance.Task.Name + (_cancelRequested ? " Canceled" : " Completed"));
        
    // Indicate that the background task has completed.
    _deferral.Complete();
}

if (!m_cancelRequested && m_progress < 100)
{
    m_progress += 10;
    m_taskInstance.Progress(m_progress);
}
else
{
    m_periodicTimer.Cancel();

    // Write to LocalSettings to indicate that this background task ran.
    auto settings{ Windows::Storage::ApplicationData::Current().LocalSettings() };
    auto key{ m_taskInstance.Task().Name() };
    settings.Values().Insert(key, (m_progress < 100) ? winrt::box_value(L"Canceled") : winrt::box_value(L"Completed"));

    // Indicate that the background task has completed.
    m_deferral.Complete();
}

if ((CancelRequested == false) && (Progress < 100))
{
    Progress += 10;
    TaskInstance->Progress = Progress;
}
else
{
    PeriodicTimer->Cancel();
        
    // Write to LocalSettings to indicate that this background task ran.
    auto settings = ApplicationData::Current->LocalSettings;
    auto key = TaskInstance->Task->Name;
    settings->Values->Insert(key, (Progress < 100) ? "Canceled" : "Completed");
        
    // Indicate that the background task has completed.
    Deferral->Complete();
}

Comentários

Você pode baixar o exemplo de tarefa em segundo plano para ver esses exemplos de código no contexto de métodos.

Para fins ilustrativos, o código de exemplo mostra apenas partes do método Run (e temporizador de retorno de chamada) do exemplo de tarefa em segundo plano.

Exemplo de método de execução

O método Run completo e o código de retorno de chamada do temporizador do exemplo de tarefa em segundo plano são mostrados abaixo para contexto.

// The Run method is the entry point of a background task.
public void Run(IBackgroundTaskInstance taskInstance)
{
    Debug.WriteLine("Background " + taskInstance.Task.Name + " Starting...");

    // Query BackgroundWorkCost
    // Guidance: If BackgroundWorkCost is high, then perform only the minimum amount
    // of work in the background task and return immediately.
    var cost = BackgroundWorkCost.CurrentBackgroundWorkCost;
    var settings = ApplicationData.Current.LocalSettings;
    settings.Values["BackgroundWorkCost"] = cost.ToString();

    // Associate a cancellation handler with the background task.
    taskInstance.Canceled += new BackgroundTaskCanceledEventHandler(OnCanceled);

    // Get the deferral object from the task instance, and take a reference to the taskInstance;
    _deferral = taskInstance.GetDeferral();
    _taskInstance = taskInstance;

    _periodicTimer = ThreadPoolTimer.CreatePeriodicTimer(new TimerElapsedHandler(PeriodicTimerCallback), TimeSpan.FromSeconds(1));
}

// Simulate the background task activity.
private void PeriodicTimerCallback(ThreadPoolTimer timer)
{
    if ((_cancelRequested == false) && (_progress < 100))
    {
        _progress += 10;
        _taskInstance.Progress = _progress;
    }
    else
    {
        _periodicTimer.Cancel();

        var settings = ApplicationData.Current.LocalSettings;
        var key = _taskInstance.Task.Name;

        // Write to LocalSettings to indicate that this background task ran.
        settings.Values[key] = (_progress < 100) ? "Canceled with reason: " + _cancelReason.ToString() : "Completed";
        Debug.WriteLine("Background " + _taskInstance.Task.Name + settings.Values[key]);

        // Indicate that the background task has completed.
        _deferral.Complete();
    }
}

void ExampleBackgroundTask::Run(Windows::ApplicationModel::Background::IBackgroundTaskInstance const& taskInstance)
{
    // Query BackgroundWorkCost
    // Guidance: If BackgroundWorkCost is high, then perform only the minimum amount
    // of work in the background task and return immediately.
    auto cost{ Windows::ApplicationModel::Background::BackgroundWorkCost::CurrentBackgroundWorkCost() };
    auto settings{ Windows::Storage::ApplicationData::Current().LocalSettings() };
    std::wstring costAsString{ L"Low" };
    if (cost == Windows::ApplicationModel::Background::BackgroundWorkCostValue::Medium) costAsString = L"Medium";
    else if (cost == Windows::ApplicationModel::Background::BackgroundWorkCostValue::High) costAsString = L"High";
    settings.Values().Insert(L"BackgroundWorkCost", winrt::box_value(costAsString));

    // Associate a cancellation handler with the background task.
    taskInstance.Canceled({ this, &ExampleBackgroundTask::OnCanceled });

    // Get the deferral object from the task instance, and take a reference to the taskInstance.
    m_deferral = taskInstance.GetDeferral();
    m_taskInstance = taskInstance;

    Windows::Foundation::TimeSpan period{ std::chrono::seconds{1} };
    m_periodicTimer = Windows::System::Threading::ThreadPoolTimer::CreatePeriodicTimer([this](Windows::System::Threading::ThreadPoolTimer timer)
    {
        if (!m_cancelRequested && m_progress < 100)
        {
            m_progress += 10;
            m_taskInstance.Progress(m_progress);
        }
        else
        {
            m_periodicTimer.Cancel();

            // Write to LocalSettings to indicate that this background task ran.
            auto settings{ Windows::Storage::ApplicationData::Current().LocalSettings() };
            auto key{ m_taskInstance.Task().Name() };
            settings.Values().Insert(key, (m_progress < 100) ? winrt::box_value(L"Canceled") : winrt::box_value(L"Completed"));

            // Indicate that the background task has completed.
            m_deferral.Complete();
        }
    }, period);
}

void ExampleBackgroundTask::Run(IBackgroundTaskInstance^ taskInstance)
{
    // Query BackgroundWorkCost
    // Guidance: If BackgroundWorkCost is high, then perform only the minimum amount
    // of work in the background task and return immediately.
    auto cost = BackgroundWorkCost::CurrentBackgroundWorkCost;
    auto settings = ApplicationData::Current->LocalSettings;
    settings->Values->Insert("BackgroundWorkCost", cost.ToString());

    // Associate a cancellation handler with the background task.
    taskInstance->Canceled += ref new BackgroundTaskCanceledEventHandler(this, &ExampleBackgroundTask::OnCanceled);

    // Get the deferral object from the task instance, and take a reference to the taskInstance.
    TaskDeferral = taskInstance->GetDeferral();
    TaskInstance = taskInstance;

    auto timerDelegate = [this](ThreadPoolTimer^ timer)
    {
        if ((CancelRequested == false) &&
            (Progress < 100))
        {
            Progress += 10;
            TaskInstance->Progress = Progress;
        }
        else
        {
            PeriodicTimer->Cancel();

            // Write to LocalSettings to indicate that this background task ran.
            auto settings = ApplicationData::Current->LocalSettings;
            auto key = TaskInstance->Task->Name;
            settings->Values->Insert(key, (Progress < 100) ? "Canceled with reason: " + CancelReason.ToString() : "Completed");

            // Indicate that the background task has completed.
            TaskDeferral->Complete();
        }
    };

    TimeSpan period;
    period.Duration = 1000 * 10000; // 1 second
    PeriodicTimer = ThreadPoolTimer::CreatePeriodicTimer(ref new TimerElapsedHandler(timerDelegate), period);
}

Compartilhar via

Tratar uma tarefa em segundo plano cancelada

Usar o método OnCanceled para reconhecer solicitações de cancelamento

Lidar com o cancelamento saindo da tarefa em segundo plano

Comentários

Exemplo de método de execução

Comentários

Recursos adicionais

Compartilhar via

Tratar uma tarefa em segundo plano cancelada

Usar o método OnCanceled para reconhecer solicitações de cancelamento

Lidar com o cancelamento saindo da tarefa em segundo plano

Comentários

Exemplo de método de execução

Tópicos relacionados

Comentários

Recursos adicionais