Mendaftarkan tugas latar belakang

  • Artikel

API penting

Pelajari cara membuat fungsi yang dapat digunakan kembali untuk mendaftarkan sebagian besar tugas latar belakang dengan aman.

Topik ini berlaku untuk tugas latar belakang dalam proses dan tugas latar belakang di luar proses. Topik ini mengasumsikan bahwa Anda sudah memiliki tugas latar belakang yang perlu didaftarkan. (Lihat Membuat dan mendaftarkan tugas latar belakang yang berjalan di luar proses atau Membuat dan mendaftarkan tugas latar belakang dalam proses untuk informasi tentang cara menulis tugas latar belakang).

Topik ini berjalan melalui fungsi utilitas yang mendaftarkan tugas latar belakang. Fungsi utilitas ini memeriksa pendaftaran yang ada terlebih dahulu sebelum mendaftarkan tugas beberapa kali untuk menghindari masalah dengan beberapa pendaftaran, dan dapat menerapkan kondisi sistem ke tugas latar belakang. Panduan ini mencakup contoh lengkap dan berfungsi dari fungsi utilitas ini.

Catatan  

Aplikasi Windows universal harus memanggil RequestAccessAsync sebelum mendaftarkan salah satu jenis pemicu latar belakang.

Untuk memastikan bahwa aplikasi Universal Windows Anda terus berjalan dengan benar setelah merilis pembaruan, Anda harus memanggil RemoveAccess lalu memanggil RequestAccessAsync saat aplikasi Anda diluncurkan setelah diperbarui. Untuk informasi selengkapnya, lihat Panduan untuk tugas latar belakang.

Tentukan tanda tangan metode dan jenis pengembalian

Metode ini mengambil titik masuk tugas, nama tugas, pemicu tugas latar belakang yang telah dibangun sebelumnya, dan (opsional) SystemCondition untuk tugas latar belakang. Metode ini mengembalikan objek BackgroundTaskRegistration .

Penting

taskEntryPoint - untuk tugas latar belakang yang berjalan di luar proses, ini harus dibangun sebagai nama namespace layanan, '.', dan nama kelas yang berisi kelas latar belakang Anda. String peka huruf besar/kecil. Misalnya, jika Anda memiliki namespace "MyBackgroundTasks" dan kelas "BackgroundTask1" yang berisi kode kelas latar belakang Anda, string untuk taskEntryPoint adalah "MyBackgroundTasks.BackgroundTask1". Jika tugas latar belakang Anda berjalan dalam proses yang sama dengan aplikasi Anda (yaitu tugas latar belakang dalam proses) taskEntryPoint tidak boleh diatur.

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.

}

Periksa pendaftaran yang ada

Periksa apakah tugas sudah terdaftar. Penting untuk memeriksa ini karena jika tugas terdaftar beberapa kali, tugas akan berjalan lebih dari sekali setiap kali dipicu; ini dapat menggunakan kelebihan CPU dan dapat menyebabkan perilaku yang tidak terduga.

Anda dapat memeriksa pendaftaran yang ada dengan mengkueri properti BackgroundTaskRegistration.AllTasks dan iterasi pada hasilnya. Periksa nama setiap instans – jika cocok dengan nama tugas yang Anda daftarkan, lalu keluar dari perulangan dan atur variabel bendera sehingga kode Anda dapat memilih jalur yang berbeda di langkah berikutnya.

Catatan Gunakan nama tugas latar belakang yang unik untuk aplikasi Anda. Pastikan setiap tugas latar belakang memiliki nama yang unik.

Kode berikut mendaftarkan tugas latar belakang menggunakan SystemTrigger yang kami buat di langkah terakhir:

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

Daftarkan tugas latar belakang (atau kembalikan pendaftaran yang ada)

Periksa untuk melihat apakah tugas ditemukan dalam daftar pendaftaran tugas latar belakang yang ada. Jika demikian, kembalikan instans tugas tersebut.

Kemudian, daftarkan tugas menggunakan objek BackgroundTaskBuilder baru. Kode ini harus memeriksa apakah parameter kondisi null, dan jika tidak, tambahkan kondisi ke objek pendaftaran. Mengembalikan BackgroundTaskRegistration yang dikembalikan oleh metode BackgroundTaskBuilder.Register .

Catatan Parameter pendaftaran tugas latar belakang divalidasi pada saat pendaftaran. Kesalahan dikembalikan jika salah satu parameter pendaftaran tidak valid. Pastikan aplikasi Anda menangani skenario dengan lancar di mana pendaftaran tugas latar belakang gagal - jika sebaliknya aplikasi Anda bergantung pada memiliki objek pendaftaran yang valid setelah mencoba mendaftarkan tugas, itu mungkin crash. Catatan Jika Anda mendaftarkan tugas latar belakang yang berjalan dalam proses yang sama dengan aplikasi Anda, kirim String.Empty atau null untuk taskEntryPoint parameter .

Contoh berikut mengembalikan tugas yang ada, atau menambahkan kode yang mendaftarkan tugas latar belakang (termasuk kondisi sistem opsional jika ada):

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

Menyelesaikan fungsi utilitas pendaftaran tugas latar belakang

Contoh ini menunjukkan fungsi pendaftaran tugas latar belakang yang telah selesai. Fungsi ini dapat digunakan untuk mendaftarkan sebagian besar tugas latar belakang, dengan pengecualian tugas latar belakang jaringan.

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