Регистрация фоновой задачи

Статья
06/14/2024

Важные API

Узнайте, как создать функцию, которую можно повторно использовать для безопасной регистрации большинства фоновых задач.

Этот раздел применим как к фоновым задачам внутри процесса, так и к фоновым задачам вне процесса. В этом разделе предполагается, что у вас уже есть фоновая задача, которая должна быть зарегистрирована. (См. раздел Создайте и зарегистрируйте фоновую задачу, которая выполняется вне процесса или создает и регистрирует фоновую задачу внутри процесса для получения сведений о написании фоновой задачи ).

В этом разделе описывается служебная функция, которая регистрирует фоновые задачи. Эта служебная функция сначала проверяет наличие существующих регистраций перед регистрацией задачи несколько раз, чтобы избежать проблем с несколькими регистрациями, и она может применить системное условие к фоновой задаче. Пошаговое руководство содержит полный рабочий пример этой служебной функции.

Примечание

Универсальные приложения Windows должны вызывать RequestAccessAsync перед регистрацией любого из типов фоновых триггеров.

Чтобы убедиться, что приложение универсального windows продолжает работать должным образом после выпуска обновления, необходимо вызвать RemoveAccess, а затем вызвать RequestAccessAsync при запуске приложения после обновления. Дополнительные сведения см. в руководстве по фоновым задачам.

Определение сигнатуры метода и возвращаемого типа

Этот метод принимает точку входа задачи, имя задачи, предварительно созданный триггер фоновой задачи и (необязательно) SystemCondition для фоновой задачи. Этот метод возвращает объект BackgroundTaskRegistration.

Внимание

taskEntryPoint — для фоновых задач, которые выполняются вне процесса, это должно быть создано как имя пространства имен, "." и имя класса, содержащего фоновый класс. Строка учитывает регистр. Например, если у вас есть пространство имен MyBackgroundTasks и класс BackgroundTask1, содержащий код фонового класса, строка для taskEntryPoint параметра "MyBackgroundTasks.BackgroundTask1". Если фоновая задача выполняется в том же процессе, что и приложение (т. е. фоновая задача внутри процесса) taskEntryPoint не должна быть задана.

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    
    // We'll add code to this function in subsequent steps.

}

BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{
    
    // We'll add code to this function in subsequent steps.

}

Проверка существующих регистраций

Проверьте, уже ли зарегистрирована задача. Важно проверить это, так как если задача зарегистрирована несколько раз, она будет выполняться несколько раз при активации; это может использовать избыточный ЦП и может вызвать непредвиденное поведение.

Вы можете проверить наличие существующих регистраций, запросив свойство BackgroundTaskRegistration.AllTasks и итерируя результат. Проверьте имя каждого экземпляра— если оно соответствует имени задачи, которую вы регистрируете, затем разорвать цикл и задать переменную флага, чтобы код смог выбрать другой путь на следующем шаге.

Примечание. Используйте имена фоновых задач, уникальные для приложения. Убедитесь, что каждая фоновая задача имеет уникальное имя.

Следующий код регистрирует фоновую задачу с помощью SystemTrigger , созданной на последнем шаге:

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == name)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }
    
    // We'll register the task in the next step.
}

BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{
    //
    // Check for existing registrations of this background task.
    //
    
    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;
    
    while (hascur)
    {
        auto cur = iter->Current->Value;
        
        if(cur->Name == name)
        {
            //
            // The task is registered.
            //
            
            return (BackgroundTaskRegistration ^)(cur);
        }
        
        hascur = iter->MoveNext();
    }
    
    // We'll register the task in the next step.
}

Регистрация фоновой задачи (или возврат существующей регистрации)

Проверьте, найдена ли задача в списке существующих регистраций фоновых задач. Если да, верните этот экземпляр задачи.

Затем зарегистрируйте задачу с помощью нового объекта BackgroundTaskBuilder. Этот код должен проверить, имеет ли параметр условия значение NULL, а если нет, добавьте условие в объект регистрации. Возвращает значение BackgroundTaskRegistration, возвращаемое методом BackgroundTaskBuilder.Register.

Обратите внимание, что параметры регистрации фоновой задачи проверяются во время регистрации. Ошибка возвращается, если какие-либо из параметров регистрации недопустимы. Убедитесь, что приложение корректно обрабатывает сценарии, в которых регистрация фоновых задач завершается ошибкой. Если вместо этого приложение зависит от наличия допустимого объекта регистрации после попытки регистрации задачи, это может завершиться сбоем. Обратите внимание , что если вы регистрируете фоновую задачу, которая выполняется в том же процессе, что и приложение, отправляете String.Empty или null для taskEntryPoint параметра.

В следующем примере возвращается существующая задача или добавляется код, регистрирующий фоновую задачу (включая необязательное условие системы при наличии):

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == taskName)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }

    //
    // Register the background task.
    //

    var builder = new BackgroundTaskBuilder();

    builder.Name = name;

    // in-process background tasks don't set TaskEntryPoint
    if ( taskEntryPoint != null && taskEntryPoint != String.Empty)
    {
        builder.TaskEntryPoint = taskEntryPoint;
    }
    builder.SetTrigger(trigger);

    if (condition != null)
    {
        builder.AddCondition(condition);
    }

    BackgroundTaskRegistration task = builder.Register();

    return task;
}

BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{

    //
    // Check for existing registrations of this background task.
    //

    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;

    while (hascur)
    {
        auto cur = iter->Current->Value;

        if(cur->Name == name)
        {
            //
            // The task is registered.
            //

            return (BackgroundTaskRegistration ^)(cur);
        }

        hascur = iter->MoveNext();
    }

    //
    // Register the background task.
    //

    auto builder = ref new BackgroundTaskBuilder();

    builder->Name = name;
    builder->TaskEntryPoint = taskEntryPoint;
    builder->SetTrigger(trigger);

    if (condition != nullptr) {
        
        builder->AddCondition(condition);
    }

    BackgroundTaskRegistration ^ task = builder->Register();

    return task;
}

Завершение функции служебной программы регистрации фоновых задач

В этом примере показана завершенная функция регистрации фоновых задач. Эту функцию можно использовать для регистрации большинства фоновых задач, за исключением фоновых задач сети.

//
// 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.
//
public static BackgroundTaskRegistration RegisterBackgroundTask(string taskEntryPoint,
                                                                string taskName,
                                                                IBackgroundTrigger trigger,
                                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == taskName)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }

    //
    // Register the background task.
    //

    var builder = new BackgroundTaskBuilder();

    builder.Name = taskName;
    builder.TaskEntryPoint = taskEntryPoint;
    builder.SetTrigger(trigger);

    if (condition != null)
    {

        builder.AddCondition(condition);
    }

    BackgroundTaskRegistration task = builder.Register();

    return task;
}

//
// 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.
//
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(Platform::String ^ taskEntryPoint,
                                                             Platform::String ^ taskName,
                                                             IBackgroundTrigger ^ trigger,
                                                             IBackgroundCondition ^ condition)
{

    //
    // Check for existing registrations of this background task.
    //

    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;

    while (hascur)
    {
        auto cur = iter->Current->Value;

        if(cur->Name == name)
        {
            //
            // The task is registered.
            //

            return (BackgroundTaskRegistration ^)(cur);
        }

        hascur = iter->MoveNext();
    }


    //
    // Register the background task.
    //

    auto builder = ref new BackgroundTaskBuilder();

    builder->Name = name;
    builder->TaskEntryPoint = taskEntryPoint;
    builder->SetTrigger(trigger);

    if (condition != nullptr) {

        builder->AddCondition(condition);
    }

    BackgroundTaskRegistration ^ task = builder->Register();

    return task;
}

Поделиться через

Регистрация фоновой задачи

Определение сигнатуры метода и возвращаемого типа

Проверка существующих регистраций

Регистрация фоновой задачи (или возврат существующей регистрации)

Завершение функции служебной программы регистрации фоновых задач

Обратная связь

Дополнительные ресурсы

Поделиться через

Регистрация фоновой задачи

Определение сигнатуры метода и возвращаемого типа

Проверка существующих регистраций

Регистрация фоновой задачи (или возврат существующей регистрации)

Завершение функции служебной программы регистрации фоновых задач

См. также

Обратная связь

Дополнительные ресурсы