Lidar com uma tarefa em segundo plano cancelada

APIs importantes

BackgroundTaskCanceledEventHandler
IBackgroundTaskInstance
ApplicationData.Current

Saiba como fazer uma tarefa em segundo plano que reconhece uma solicitação de cancelamento, interrompe o trabalho e relata o cancelamento ao aplicativo usando 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 de 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 em processo. Em vez do método Run, substitua por OnBackgroundActivated. As tarefas em segundo plano em processo não exigem que você use armazenamento persistente para sinalizar o cancelamento, pois você pode comunicar o cancelamento usando o estado do aplicativo, já que a tarefa em segundo plano está sendo executada no mesmo processo do aplicativo em primeiro plano.

Use 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 podem ser encerradas. Se uma exceção de falta de memória 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 relação à 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 bandeira chamada _CancelRequested à classe de tarefa em segundo plano. Esta variável será usada para indicar quando um pedido de cancelamento foi feito.

volatile bool _CancelRequested = false;

private:
    volatile bool m_cancelRequested;

private:
    volatile bool CancelRequested;

No método OnCanceled que foi criado na etapa 1, defina a variável de sinalização _CancelRequested para true.

O exemplo de tarefa em segundo plano de completométodo OnCanceled define _CancelRequested para 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, registe o método manipulador do evento 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 terminando a tarefa em segundo plano

Quando uma solicitação de cancelamento é recebida, o seu método que faz processamento em segundo plano precisa parar de trabalhar e sair, reconhecendo quando _cancelRequested está definido como true. Para tarefas em segundo plano em 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 sua classe de tarefa em segundo plano para verificar a variável flag enquanto ela está funcionando. Se _cancelRequested for definido como true, pare de continuar o trabalho.

O exemplo de tarefa em segundo plano inclui uma verificação que interrompe o retorno de chamada periódico do temporizador 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 propriedade que está sendo usada para registrar o progresso da tarefa em segundo plano. O progresso é reportado de volta à aplicação 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 processos quando a tarefa em segundo plano foi cancelada. Para tarefas em segundo plano em 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();
}

Observações

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 Run

O método completo Run e o código de retorno de chamada do temporizador da amostra de tarefa em segundo plano são mostrados abaixo como 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);
}

Feedback

Esta página foi útil?

Last updated on 2025-06-10