Registrare un'attività in background

  • Articolo

API importanti

Informazioni su come creare una funzione da poter riutilizzare per registrare correttamente la maggior parte delle attività in background.

Questo argomento è applicabile sia alle attività in background in-process che alle attività in background out-of-process. In questo argomento si presuppone che l'utente disponga già di un'attività in background che deve essere registrata. (Vedere Creare e registrare un'attività in background che viene eseguita out-of-process o Crea e registra un'attività in background in-process per informazioni su come scrivere un'attività in background.

Questo argomento illustra una funzione di utilità che registra le attività in background. Questa funzione di utilità controlla prima di registrare più volte le registrazioni esistenti per evitare problemi con più registrazioni e può applicare una condizione di sistema all'attività in background. La procedura dettagliata include un esempio completo e funzionante di questa funzione di utilità.

Nota  

Le app Universal Windows devono chiamare RequestAccessAsync prima di registrare uno dei tipi di trigger in background.

Per assicurarsi che l'app di Universal Windows continui a funzionare correttamente dopo il rilascio di un aggiornamento, è necessario chiamare RemoveAccess e quindi chiamare RequestAccessAsync quando l'app viene avviata dopo essere stata aggiornata. Per maggiori informazioni, vedere Linee guida per le attività in background.

Definire il metodo esclusivo e il tipo restituito

Questo metodo accetta il punto di ingresso dell'attività, il nome dell'attività, un trigger di attività in background predefinito e (facoltativamente) una SystemCondition per l'attività in background. Questo metodo restituisce un oggetto BackgroundTaskRegistration.

Importante

taskEntryPoint - per le attività in background che vengono eseguite in modo non elaborato, questo deve essere costruito come nome dello spazio dei nomi , '.' e il nome della classe contenente la classe in background. La stringa fa distinzione tra maiuscole e minuscole. Ad esempio, se si dispone di uno spazio dei nomi "MyBackgroundTasks" e una classe "BackgroundTask1" che contiene il codice della classe in background, la stringa per taskEntryPoint dovrebbe essere "MyBackgroundTasks.BackgroundTask1". Se l'attività in background viene eseguita nello stesso processo dell'app (ad esempio, un'attività in background in-process) taskEntryPoint non deve essere impostata.

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.

}

Verificare la presenza di registrazioni esistenti

Controllare se l'attività è già registrata. È importante verificarlo perché se un'attività viene registrata più volte, verrà eseguita più volte ogni volta che viene attivata; questo può usare una CPU in eccesso e può causare un comportamento imprevisto.

È possibile verificare la presenza di registrazioni esistenti eseguendo una query sulla proprietà packgroundTaskRegistration.AllTasks ed eseguendo l'iterazione sul risultato. Controllare il nome di ogni istanza: se corrisponde al nome dell'attività che si sta registrando, interrompere il ciclo e impostare una variabile flag in modo che il codice possa scegliere un percorso diverso nel passaggio successivo.

Nota Usare nomi di attività in background univoci per l'app. Verificare che ogni attività in background abbia un nome univoco.

Il codice seguente registra un'attività in background usando SystemTrigger creato nell'ultimo passaggio:

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

Registrare l'attività in background (o restituire la registrazione esistente)

Verificare se l'attività è stata trovata nell'elenco delle registrazioni delle attività in background esistenti. In tal caso, restituire l'istanza dell'attività.

Registrare quindi l'attività usando un nuovo oggetto BackgroundTaskBuilder. Questo codice deve verificare se il parametro della condizione è Null e, in caso contrario, aggiungere la condizione all'oggetto di registrazione. Restituire BackgroundTaskRegistration restituito dal metodo BackgroundTaskBuilder.Register.

Nota I parametri di registrazione delle attività in background vengono convalidati al momento della registrazione. Se uno dei parametri di registrazione non è valido, viene restituito un errore. Assicurarsi che l'app gestisca correttamente gli scenari in cui la registrazione delle attività in background ha esito negativo. Se invece l'app dipende dalla presenza di un oggetto di registrazione valido dopo il tentativo di registrazione di un'attività, potrebbe verificarsi un arresto anomalo. Nota Se si sta registrando un'attività in background eseguita nello stesso processo dell'app, inviare String.Empty o null per il parametro taskEntryPoint.

Nell'esempio seguente viene restituita l'attività esistente oppure viene aggiunto il codice che registra l'attività in background (inclusa la condizione di sistema facoltativa, se presente):

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

Completare la funzione dell'utilità di registrazione delle attività in background

Questo esempio mostra la funzione di registrazione dell'attività in background completata. Questa funzione può essere usata per registrare la maggior parte delle attività in background, ad eccezione delle attività in background di rete.

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