백그라운드 작업 등록Register a background task

중요 APIImportant APIs

대부분의 백그라운드 작업을 안전하게 등록하기 위해 다시 사용할 수 있는 함수를 만드는 방법을 알아봅니다.Learn how to create a function that can be re-used to safely register most background tasks.

이 항목은 in-process 백그라운드 작업과 out-of-process 백그라운드 작업에 모두 적용 됩니다.This topic is applicable to both in-process background tasks and out-of-process background tasks. 이 항목에서는 등록 해야 하는 백그라운드 작업이 이미 있다고 가정 합니다.This topic assumes that you already have a background task that needs to be registered. 백그라운드 작업을 작성 하는 방법에 대 한 자세한 내용은 out-of-process를 실행 하는 백그라운드 작업 만들기 및 등록 또는 In-process 백그라운드 작업 생성 및 등록 을 참조 하세요.(See Create and register a background task that runs out-of-process or Create and register an in-process background task for information about how to write a background task).

이 항목에서는 백그라운드 작업을 등록 하는 유틸리티 함수를 안내 합니다.This topic walks through a utility function that registers background tasks. 이 유틸리티 함수는 여러 번의 등록 문제를 방지 하기 위해 작업을 여러 번 등록 하기 전에 먼저 기존 등록을 확인 하 고, 백그라운드 작업에 시스템 조건을 적용할 수 있습니다.This utility function checks for existing registrations first before registering the task multiple times to avoid problems with multiple registrations, and it can apply a system condition to the background task. 이 연습에는이 유틸리티 함수의 완전 한 작업 예가 포함 되어 있습니다.The walkthrough includes a complete, working example of this utility function.

참고Note  

유니버설 Windows 앱은 백그라운드 트리거 형식을 등록 하기 전에 Requestaccessasync 를 호출 해야 합니다.Universal Windows apps must call RequestAccessAsync before registering any of the background trigger types.

업데이트를 릴리스된 후에도 유니버설 Windows 앱이 제대로 실행 되도록 하려면 Removeaccess 를 호출한 다음 앱이 업데이트 된 후에 시작 될 때 requestaccessasync 를 호출 해야 합니다.To ensure that your Universal Windows app continues to run properly after you release an update, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. 자세한 내용은 백그라운드 작업에 대 한 지침을 참조 하세요.For more information, see Guidelines for background tasks.

메서드 시그니처와 반환 형식 정의Define the method signature and return type

이 메서드는 작업 진입점, 작업 이름, 미리 생성 된 백그라운드 작업 트리거 및 백그라운드 작업에 대 한 Systemcondition (선택 사항)을 사용 합니다.This method takes in the task entry point, task name, a pre-constructed background task trigger, and (optionally) a SystemCondition for the background task. 이 메서드는 BackgroundTaskRegistration 개체를 반환 합니다.This method returns a BackgroundTaskRegistration object.

중요

taskEntryPoint -in-process로 실행 되는 백그라운드 작업의 경우 네임 스페이스 이름, '. ' 및 백그라운드 클래스를 포함 하는 클래스의 이름으로 생성 되어야 합니다.taskEntryPoint - for background tasks that run in out of process, this must be constructed as the namespace name, '.', and the name of the class containing your background class. 문자열은 대/소문자를 구분 합니다.The string is case-sensitive. 예를 들어, 배경 클래스 코드를 포함 하는 "MyBackgroundTasks" 네임 스페이스와 "BackgroundTask1" 클래스가 있는 경우의 문자열은 taskEntryPoint "MyBackgroundTasks. BackgroundTask1"입니다.For example, if you had a namespace "MyBackgroundTasks" and a class "BackgroundTask1" that contained your background class code, the string for taskEntryPoint would be "MyBackgroundTasks.BackgroundTask1". 백그라운드 태스크가 앱과 동일한 프로세스에서 실행 되는 경우 (즉, in-process 백그라운드 작업) 설정 하면 안 됩니다 taskEntryPoint .If your background task runs in the same process as your app (i.e. a in-process background task) taskEntryPoint should not be set.

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.

}

기존 등록 확인Check for existing registrations

태스크가 이미 등록 되어 있는지 확인 합니다.Check whether the task is already registered. 작업을 여러 번 등록 하는 경우 트리거될 때마다 두 번 이상 실행 되므로이를 확인 하는 것이 중요 합니다. 이 경우 과도 한 CPU를 사용할 수 있으며 예기치 않은 동작이 발생할 수 있습니다.It's important to check this because if a task is registered multiple times, it will run more than once whenever it’s triggered; this can use excess CPU and may cause unexpected behavior.

BackgroundTaskRegistration 속성을 쿼리하고 결과를 반복 하 여 기존 등록을 확인할 수 있습니다.You can check for existing registrations by querying the BackgroundTaskRegistration.AllTasks property and iterating on the result. 각 인스턴스의 이름을 확인 합니다. 즉, 등록 하는 작업의 이름과 일치 하면 다음 단계에서 코드에서 다른 경로를 선택할 수 있도록 루프를 중단 하 고 플래그 변수를 설정 합니다.Check the name of each instance – if it matches the name of the task you’re registering, then break out of the loop and set a flag variable so that your code can choose a different path in the next step.

참고    앱에 고유한 백그라운드 작업 이름을 사용 합니다.Note  Use background task names that are unique to your app. 각 백그라운드 작업에 고유한 이름이 있는지 확인 합니다.Ensure each background task has a unique name.

다음 코드는 마지막 단계에서 만든 Systemtrigger 를 사용 하 여 백그라운드 작업을 등록 합니다.The following code registers a background task using the SystemTrigger we created in the last step:

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.
}

백그라운드 작업을 등록 하거나 기존 등록을 반환 합니다.Register the background task (or return the existing registration)

태스크가 기존 백그라운드 작업 등록 목록에 있는지 확인 합니다.Check to see if the task was found in the list of existing background task registrations. 이 경우 해당 작업의 인스턴스를 반환 합니다.If so, return that instance of the task.

그런 다음 새 BackgroundTaskBuilder 개체를 사용 하 여 작업을 등록 합니다.Then, register the task using a new BackgroundTaskBuilder object. 이 코드는 condition 매개 변수가 null 인지 여부를 확인 하 고, 그렇지 않은 경우 등록 개체에 조건을 추가 합니다.This code should check whether the condition parameter is null, and if not, add the condition to the registration object. BackgroundTaskBuilder 메서드에서 반환 된 BackgroundTaskRegistration 를 반환 합니다.Return the BackgroundTaskRegistration returned by the BackgroundTaskBuilder.Register method.

참고    등록 시 백그라운드 작업 등록 매개 변수의 유효성이 검사 됩니다.Note  Background task registration parameters are validated at the time of registration. 등록 매개 변수가 잘못 된 경우 오류가 반환 됩니다.An error is returned if any of the registration parameters are invalid. 앱이 백그라운드 작업 등록에 실패 하는 시나리오를 정상적으로 처리 하는지 확인 합니다. 대신 앱이 작업 등록을 시도한 후 유효한 등록 개체가 있는 경우 충돌이 발생할 수 있습니다.Ensure that your app gracefully handles scenarios where background task registration fails - if instead your app depends on having a valid registration object after attempting to register a task, it may crash. 참고 앱과 동일한 프로세스에서 실행 되는 백그라운드 작업을 등록 하는 경우 String.Empty null 매개 변수에 대해 또는를 보냅니다 taskEntryPoint .Note If you are registering a background task that runs in the same process as your app, send String.Empty or null for the taskEntryPoint parameter.

다음 예에서는 기존 작업을 반환 하거나 백그라운드 작업을 등록 하는 코드를 추가 합니다 (있는 경우 선택적 시스템 조건 포함).The following example either returns the existing task, or adds code that registers the background task (including the optional system condition if present):

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;
}

백그라운드 작업 등록 유틸리티 함수 완료Complete background task registration utility function

이 예제에서는 완료 된 백그라운드 작업 등록 함수를 보여 줍니다.This example shows the completed background task registration function. 이 함수는 네트워킹 백그라운드 작업을 제외 하 고 대부분의 백그라운드 작업을 등록 하는 데 사용할 수 있습니다.This function can be used to register most background tasks, with the exception of networking background tasks.

//
// 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;
}