Freigeben über

Registrieren einer Hintergrundaufgabe

  • Artikel

Wichtige APIs

Hier erfahren Sie, wie eine Funktion erstellt wird, die zum sicheren Registrieren der meisten Hintergrundaufgaben wiederverwendet werden kann.

Dieses Thema gilt sowohl für Hintergrundaufgaben als auch für Hintergrundaufgaben außerhalb von Prozessen. In diesem Thema wird davon ausgegangen, dass Sie bereits über eine Hintergrundaufgabe verfügen, die registriert werden muss. (Siehe Erstellen und registrieren Sie eine Hintergrundaufgabe, die außerhalb des Prozesses ausgeführt wird, oder erstellen und registrieren Sie eine In-Process-Hintergrundaufgabe , um Informationen zum Schreiben einer Hintergrundaufgabe zu erhalten.

In diesem Thema wird eine Hilfsfunktion erläutert, die Hintergrundaufgaben registriert. Diese Hilfsfunktion sucht zuerst nach vorhandenen Registrierungen, bevor Sie die Aufgabe mehrmals registrieren, um Probleme mit mehreren Registrierungen zu vermeiden, und sie kann eine Systembedingung auf die Hintergrundaufgabe anwenden. Die exemplarische Vorgehensweise enthält ein vollständiges, funktionierendes Beispiel für diese Hilfsfunktion.

Hinweis  

Universelle Windows-Apps müssen RequestAccessAsync aufrufen, bevor Sie einen der Hintergrundtriggertypen registrieren.

Um sicherzustellen, dass Ihre universelle Windows-App nach der Veröffentlichung eines Updates weiterhin ordnungsgemäß ausgeführt wird, müssen Sie RemoveAccess aufrufen und dann RequestAccessAsync aufrufen, wenn die App nach der Aktualisierung gestartet wird. Weitere Informationen finden Sie in den Richtlinien für Hintergrundaufgaben.

Definieren der Methodensignatur und des Rückgabetyps

Diese Methode übernimmt den Einstiegspunkt, den Aufgabennamen, einen vordefinierten Hintergrundaufgabentrigger und (optional) eine SystemCondition für die Hintergrundaufgabe. Diese Methode gibt ein BackgroundTaskRegistration -Objekt zurück.

Wichtig

taskEntryPoint - Für Hintergrundaufgaben, die außerhalb des Prozesses ausgeführt werden, muss dies als Namespacename , "." und den Namen der Klasse erstellt werden, die Ihre Hintergrundklasse enthält. Bei der Zeichenfolge wird die Groß-/Kleinschreibung beachtet. Wenn Sie beispielsweise einen Namespace "MyBackgroundTasks" und eine Klasse "BackgroundTask1" hatten, die Ihren Hintergrundklassencode enthielt, lautet die Zeichenfolge " taskEntryPoint MyBackgroundTasks.BackgroundTask1". Wenn Ihre Hintergrundaufgabe im selben Prozess wie Ihre App ausgeführt wird (d. h. eine Hintergrundaufgabe im Prozess), taskEntryPoint sollte nicht festgelegt werden.

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.

}

Überprüfen vorhandener Registrierungen

Überprüfen Sie, ob die Aufgabe bereits registriert ist. Es ist wichtig, dies zu überprüfen, da wenn eine Aufgabe mehrmals registriert wird, mehr als einmal ausgeführt wird, wenn sie ausgelöst wird. dies kann eine übermäßige CPU verwenden und kann zu unerwartetem Verhalten führen.

Sie können nach vorhandenen Registrierungen suchen, indem Sie die BackgroundTaskRegistration.AllTasks-Eigenschaft abfragen und das Ergebnis durchlaufen. Überprüfen Sie den Namen jeder Instanz – wenn sie mit dem Namen der Aufgabe übereinstimmt, die Sie registrieren, brechen Sie die Schleife auf, und legen Sie eine Flagvariable fest, damit Ihr Code im nächsten Schritt einen anderen Pfad auswählen kann.

Hinweis : Verwenden Sie Namen von Hintergrundaufgaben, die für Ihre App eindeutig sind. Stellen Sie sicher, dass jede Hintergrundaufgabe einen eindeutigen Namen hat.

Der folgende Code registriert eine Hintergrundaufgabe mithilfe des SystemTriggers, den wir im letzten Schritt erstellt haben:

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

Registrieren der Hintergrundaufgabe (oder Zurückgeben der vorhandenen Registrierung)

Überprüfen Sie, ob die Aufgabe in der Liste der vorhandenen Registrierungen für Hintergrundaufgaben gefunden wurde. Wenn dies der Fall ist, geben Sie diese Instanz der Aufgabe zurück.

Registrieren Sie dann die Aufgabe mithilfe eines neuen BackgroundTaskBuilder-Objekts. Dieser Code sollte überprüfen, ob der Bedingungsparameter null ist, und wenn nicht, fügen Sie die Bedingung dem Registrierungsobjekt hinzu. Gibt die BackgroundTaskRegistration zurück, die von der BackgroundTaskBuilder.Register-Methode zurückgegeben wird.

Hinweis: Registrierungsparameter für Hintergrundaufgaben werden zum Zeitpunkt der Registrierung überprüft. Wenn einer der Registrierungsparameter ungültig ist, wird ein Fehler zurückgegeben. Stellen Sie sicher, dass Ihre App Szenarien, in denen die Registrierung von Hintergrundaufgaben fehlschlägt, ordnungsgemäß behandelt. Wenn ihre App stattdessen von einem gültigen Registrierungsobjekt abhängt, nachdem Sie versucht haben, eine Aufgabe zu registrieren, kann es abstürzen. Hinweis : Wenn Sie eine Hintergrundaufgabe registrieren, die im selben Prozess wie Ihre App ausgeführt wird, senden String.Empty oder null für den taskEntryPoint Parameter.

Im folgenden Beispiel wird entweder die vorhandene Aufgabe zurückgegeben oder Code hinzugefügt, der die Hintergrundaufgabe registriert (einschließlich der optionalen Systembedingung, falls vorhanden):

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

Vollständige Funktion für die Registrierung von Hintergrundaufgaben

In diesem Beispiel wird die Registrierung der abgeschlossenen Hintergrundaufgabe veranschaulicht. Diese Funktion kann verwendet werden, um die meisten Hintergrundaufgaben zu registrieren, mit Ausnahme von Netzwerkhintergrundaufgaben.

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