Debuggen einer HintergrundaufgabeDebug a background task

Wichtige APIsImportant APIs

Hier erfahren Sie, wie Sie eine Hintergrundaufgabe einschließlich Hintergrundaufgabenaktivierung und Debugablaufverfolgung im Windows-Ereignisprotokoll debuggen.Learn how to debug a background task, including background task activation and debug tracing in the Windows event log.

Debuggen von Out-of-Process- im Vergleich zu In-Process-HintergrundaufgabenDebugging out-of-process vs. in-process background tasks

In diesem Thema werden hauptsächlich Hintergrundaufgaben behandelt, die in einem von der Host-App separaten Prozess ausgeführt werden.This topic primarily addresses background tasks that run in a separate process than the host app. Wenn Sie eine In-Process-Hintergrundaufgabe debuggen, verfügen Sie über kein separates Hintergrundaufgabenprojekt und können einen Haltepunkt auf OnBackgroundActivated() (wo Ihr In-Process-Hintergrundcode ausgeführt wird) festlegen. Anleitungen zum Auslösen des Hintergrundcodes finden Sie unter Schritt 2 in Manuelles Auslösen von Hintergrundaufgaben, um Hintergrundaufgabencode zu debuggen unten.If you are debugging an in-process background task, then you won't have a separate background task project and can set a breakpoint on OnBackgroundActivated() (where your in-process background code runs) and see step 2 in Trigger background tasks manually to debug background task code, below, for instructions about how to trigger your background code to execute.

Sicherstellen, dass das Hintergrundaufgabenprojekt richtig eingerichtet wurdeMake sure the background task project is set up correctly

In diesem Thema wird vorausgesetzt, dass Sie bereits über eine App mit einer Hintergrundaufgabe verfügen, die Sie debuggen möchten.This topic assumes that you already have an existing app with a background task to debug. Der folgende Code ist speziell für Hintergrundaufgaben geeignet, die außerhalb des Prozesses ausgeführt werden, und gilt nicht für In-Process-Hintergrundaufgaben.The following is specific to background tasks that run out-of-process and does not apply to in-process background tasks.

  • Stellen Sie für C# und C++ sicher, dass das Hauptprojekt auf das Hintergrundaufgabenprojekt verweist.In C# and C++, make sure the main project references the background task project. Ist dieser Verweis nicht vorhanden, wird die Hintergrundaufgabe nicht in das App-Paket eingebunden.If this reference is not in place, the background task won't be included in the app package.
  • Stellen Sie für C# und C++ sicher, dass der Ausgabetyp des Hintergrundaufgabenprojekts „Komponente für Windows-Runtime“ lautet.In C# and C++, make sure the Output type of the background task project is "Windows Runtime Component".
  • Die Background-Klasse muss im-Attribut für den Einstiegspunkt im Paket Manifest deklariert werden.The background class must be declared in the entry point attribute in the package manifest.

Manuelles Auslösen von Hintergrundaufgaben, um Hintergrundaufgabencode zu debuggenTrigger background tasks manually to debug background task code

Hintergrundaufgaben können mit Microsoft Visual Studio manuell ausgelöst werden.Background tasks can be triggered manually through Microsoft Visual Studio. Anschließend können Sie den Code schrittweise durchlaufen und ihn debuggen.Then you can step through the code and debug it.

  1. Setzen Sie in C# einen Haltepunkt in der Run-Methode der Hintergrundklasse (für In-Process-Aufgaben den Haltepunkt in App.OnBackgroundActivated()) festlegen), und/oder schreiben Sie mithilfe von System.Diagnostics eine Debuggerausgabe.In C#, put a breakpoint in the Run method of the background class (for in-process background tasks put the breakpoint in App.OnBackgroundActivated()), and/or write debugging output by using System.Diagnostics.

    Setzen Sie in C++ einen Haltepunkt in der Run-Funktion der Hintergrundklasse (für In-Process-Aufgaben den Haltepunkt in App.OnBackgroundActivated()) festlegen, und/oder schreiben Sie mithilfe von OutputDebugString eine Debuggerausgabe.In C++, put a breakpoint in the Run function of the background class (for in-process background tasks put the breakpoint in App.OnBackgroundActivated()), and/or write debugging output by using OutputDebugString.

  2. Führen Sie Ihre Anwendung im Debugger aus, und lösen Sie dann die Hintergrundaufgabe über die Symbolleiste Zyklusereignisse aus.Run your application in the debugger and then trigger the background task using the Lifecycle Events toolbar. In diesem Dropdownmenü werden die Namen der Hintergrundaufgaben angezeigt, die von Visual Studio aktiviert werden können.This drop down shows the names of the background tasks that can be activated by Visual Studio.

    Hinweis

    Die Symbolleisten Optionen für Lebenszyklus Ereignisse werden in Visual Studio standardmäßig nicht angezeigt.The Lifecycle Events toolbar options are not shown by default in Visual Studio. Um diese Optionen anzuzeigen, klicken Sie mit der rechten Maustaste auf die aktuelle Symbolleiste in Visual Studio, und stellen Sie sicher, dass Debugspeicherort aktiviert ist.To show these options, right-click on the current toolbar in Visual Studio and ensure the option Debug Location is enabled.

    Dies funktioniert nur dann, wenn die Hintergrundaufgabe bereits registriert ist und noch auf den Auslöser wartet.For this to work, the background task must already be registered and it must still be waiting for the trigger. Wenn eine Hintergrundaufgabe z. B. mit einem einmaligen TimeTrigger registriert wurde und der Trigger bereits ausgelöst wurde, hat ein Start der Aufgabe mit Visual Studio keine Wirkung.For example, if a background task was registered with a one-shot TimeTrigger and that trigger has already fired, launching the task through Visual Studio will have no effect.

    Hinweis

    Hintergrundaufgaben, die folgende Trigger verwenden, können nicht auf diese Weise aktiviert werden: Anwendungs-Trigger, MediaProcessing Trigger, ControlChannelTrigger, PushNotificationTrigger und Hintergrundaufgaben, die einen SystemTrigger mit dem Triggertyp SmsReceived verwenden.Background tasks using the following triggers cannot be activated in this manner: Application trigger, MediaProcessing trigger, ControlChannelTrigger, PushNotificationTrigger, and background tasks using a SystemTrigger with the SmsReceived trigger type.
    Anwendungs-Trigger und MediaProcessingTrigger können im Code mit trigger.RequestAsync() manuell signalisiert werden.Application trigger and MediaProcessingTrigger can be signaled manually in code with trigger.RequestAsync().

    Debuggen von Hintergrundaufgaben

  3. Wenn die Hintergrundaufgabe aktiviert wird, wird sie vom Debugger übernommen, der die Debuggerausgabe dann in VS anzeigt.When the background task activates, the debugger will attach to it and display debug output in VS.

Debuggen der Aktivierung der HintergrundaufgabeDebug background task activation

Hinweis

Dieser Abschnitt behandelt speziell Hintergrundaufgaben, die außerhalb des Prozesses ausgeführt werden, und gilt nicht für In-Process-Hintergrundaufgaben.This section is specific to background tasks the run out-of-process and does not apply to in-process background tasks.

Die Aktivierung von Hintergrundaufgaben hängt von drei Faktoren ab:Background task activation depends on three things:

  • Der Name und Namespace der HintergrundaufgabenklasseThe name and namespace of the background task class
  • Das im Paketmanifest angegebene EinstiegspunktattributThe entry point attribute specified in the package manifest
  • Der Einstiegspunkt, der von der App bei der Registrierung der Hintergrundaufgabe angegeben wirdThe entry point specified by your app when registering the background task
  1. Verwenden Sie Visual Studio, um den Einstiegspunkt der Hintergrundaufgabe zu notieren:Use Visual Studio to note the entry point of the background task:

    • Notieren Sie für C# und C++, den Namen und den Namespace der Hintergrundaufgabenklasse, die im Hintergrundaufgabenprojekt angegeben ist.In C# and C++, note the name and namespace of the background task class specified in the background task project.
  2. Verwenden Sie den Manifest-Designer, um zu überprüfen, ob die Hintergrundaufgabe ordnungsgemäß im Paketmanifest deklariert wurde:Use the manifest designer to check that the background task is correctly declared in the package manifest:

    • Für C# und C++ muss das Einstiegspunktattribut dem Namespace der Hintergrundaufgabe gefolgt vom Klassennamen entsprechen.In C# and C++, the entry point attribute must match the background task namespace followed by the class name. Beispiel: RuntimeComponent1.MyBackgroundTask.For example: RuntimeComponent1.MyBackgroundTask.
    • Alle Triggerarten, die mit der Aufgabe verwendet werden, müssen ebenfalls angegeben sein.All the trigger type(s) used with the task must also be specified.
    • Die ausführbare Datei DARF NICHT angegeben werden, es sei denn, Sie verwenden ControlChannelTrigger oder PushNotificationTrigger.The executable MUST NOT be specified unless you are using the ControlChannelTrigger or PushNotificationTrigger.
  3. Nur WindowsWindows only. Durch Aktivieren der Debugablaufverfolgung und Verwendung des Windows-Ereignisprotokolls können Sie den Einstiegspunkt ermitteln, der von Windows zum Aktivieren der Hintergrundaufgabe verwendet wird.To see the entry point used by Windows to activate the background task, enable debug tracing and use the Windows event log.

    Wenn Sie sich an dieses Verfahren halten und das Ereignisprotokoll den falschen Einstiegspunkt oder Trigger für die Hintergrundaufgabe anzeigt, wird die Hintergrundaufgabe nicht ordnungsgemäß von der App registriert.If you follow this procedure and the event log shows the wrong entry point or trigger for the background task, your app is not registering the background task correctly. Weitere Informationen zu dieser Aufgabe finden Sie unter Registrieren einer Hintergrundaufgabe.For help with this task see Register a background task.

    1. Öffnen Sie die Ereignisanzeige, indem Sie zum Startbildschirm wechseln und nach „eventvwr.exe“ suchen.Open event viewer by going to the Start screen and searching for eventvwr.exe.
    2. Wechseln Sie zu Anwendungs-und Dienst Protokolle - > Microsoft - > Windows - > backgroundtaskinfrastructure in der Ereignisanzeige.Go to Application and Services Logs -> Microsoft -> Windows -> BackgroundTaskInfrastructure in the event viewer.
    3. Wählen Sie im Aktionsbereich Ansicht - > analytische und Debugprotokolle anzeigen aus, um die Diagnoseprotokollierung zu aktivieren.In the actions pane, select View -> Show Analytic and Debug Logs to enable the diagnostic logging.
    4. Wählen Sie die Option Diagnoseprotokoll aus, und klicken Sie auf Protokoll aktivieren.Select the Diagnostic log and click Enable Log.
    5. Versuchen Sie nun, die App zu verwenden, um die Hintergrundaufgabe erneut zu registrieren und zu aktivieren.Now try using your app to register and activate the background task again.
    6. Zeigen Sie detaillierte Fehlerinformationen im Diagnoseprotokoll an.View the diagnostic logs for detailed error information. Dies schließt den Einstiegspunkt ein, der für die Hintergrundaufgabe registriert ist.This will include the entry point registered for the background task.

Ereignisanzeige für Debuginformationen für Hintergrundaufgaben

Hintergrundaufgaben und Bereitstellung des Visual Studio-PaketsBackground tasks and Visual Studio package deployment

Wenn eine APP, die Hintergrundaufgaben verwendet, mithilfe von Visual Studio bereitgestellt wird und die im Manifest-Designer angegebene Version (Haupt-und/oder neben Version) dann aktualisiert wird, kann das erneute Bereitstellen der APP mit Visual Studio dazu führen, dass die Hintergrundaufgaben der APP nicht mehr ausgeführt werden.If an app that uses background tasks is deployed using Visual Studio, and the version (major and/or minor) specified in Manifest Designer is then updated, subsequently re-deploying the app with Visual Studio may cause the app's background tasks to stall. Dieses Problem kann wie folgt behoben werden:This can be remedied as follows:

  • Stellen Sie die aktualisierte App mit Windows PowerShell (anstelle von Visual Studio) bereit, indem Sie das für das Paket erstellte Skript ausführen.Use Windows PowerShell to deploy the updated app (instead of Visual Studio) by running the script generated alongside the package.
  • Wenn Sie die APP bereits mithilfe von Visual Studio bereitgestellt haben und ihre Hintergrundaufgaben jetzt angehalten wurden, starten Sie neu, oder melden Sie sich ab, und melden Sie sich an, um die Hintergrundaufgaben der APP erneut auszuführenIf you already deployed the app using Visual Studio and its background tasks are now stalled, reboot or log off/log in to get the app's background tasks working again.
  • Sie können dies in C#-Projekten vermeiden, indem Sie die Debugoption "Paket immer neu installieren" auswählen.You can select the "Always re-install my package" debugging option to avoid this in C# projects.
  • Warten Sie, bis die APP bereit für die endgültige Bereitstellung ist, um die Paketversion zu erhöhen (ändern Sie Sie beim Debuggen nicht).Wait until the app is ready for final deployment to increment the package version (don't change it while debugging).

BemerkungenRemarks

  • Stellen Sie sicher, dass Ihre App nach vorhandenen Registrierungen von Hintergrundaufgaben sucht, bevor sie die Hintergrundaufgabe erneut registriert.Make sure your app checks for existing background task registrations before registering the background task again. Eine mehrfache Registrierung derselben Hintergrundaufgabe kann zu unerwarteten Ergebnissen führen, da die Hintergrundaufgabe mehrfach ausgelöst und ausgeführt wird.Multiple registrations of the same background task can cause unexpected results by running the background task more than once each time it is triggered.
  • Wenn für die Hintergrundaufgabe der Zugriff auf den Sperrbildschirm erforderlich ist, müssen Sie dafür sorgen, dass die App auf dem Sperrbildschirm platziert wird, bevor Sie versuchen, die Hintergrundaufgabe zu debuggen.If the background task requires lock screen access make sure to put the app on the lock screen before trying to debug the background task. Weitere Informationen zum Angeben von Manifestoptionen für sperrbildschirmfähige Apps finden Sie unter Deklarieren von Hintergrundaufgaben im Anwendungsmanifest.For info on specifying manifest options for lock screen-capable apps, see Declare background tasks in the application manifest.
  • Parameter für die Registrierung von Hintergrundaufgaben werden zum Zeitpunkt der Registrierung überprüft.Background task registration parameters are validated at the time of registration. Bei ungültigen Registrierungsparametern wird ein Fehler zurückgegeben.An error is returned if any of the registration parameters are invalid. Stellen Sie sicher, dass Ihre App problemlos mit Szenarien ohne erfolgreiche Registrierung von Hintergrundaufgaben zurechtkommt. Andernfalls stürzt die App unter Umständen ab, wenn sie so konzipiert ist, dass nach dem Versuch, eine Aufgabe zu registrieren, ein gültiges Registrierungsobjekt vorhanden sein muss.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.

Weitere Informationen zum Verwenden von vs zum Debuggen einer Hintergrundaufgabe finden Sie unter Vorgehens Weise beim Ausführen von Suspend-, Resume-und Background-Ereignissen in UWP-apps.For more info on using VS to debug a background task see How to trigger suspend, resume, and background events in UWP apps.