偵錯背景工作Debug a background task

重要 APIImportant APIs

了解如何偵錯背景工作,包括 Windows 事件記錄檔中的背景工作啟用和偵錯追蹤。Learn how to debug a background task, including background task activation and debug tracing in the Windows event log.

對跨處理序與同處理序背景工作進行偵錯Debugging out-of-process vs. in-process background tasks

本主題主要用來說明在與主控 App 不同處理序中執行的背景工作。This topic primarily addresses background tasks that run in a separate process than the host app. 如果您正在對同處理序背景進行偵錯,您將不會有個別的背景工作專案,並可以在 OnBackgroundActivated() (同處理序背景程式碼執行所在的位置) 設定中斷點,請參閱下方位於手動觸發背景工作以偵錯背景工作程式碼中的步驟 2,以取得如何觸發背景程式碼執行的指示。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.

請確定已正確設定背景工作專案Make sure the background task project is set up correctly

本主題假設您已經有需要對其背景工作偵錯的 App。This topic assumes that you already have an existing app with a background task to debug. 下列項目適用於在跨處理序中執行的背景工作,且不適用於同處理序背景工作。The following is specific to background tasks that run out-of-process and does not apply to in-process background tasks.

  • 在 C# 與 C++ 中,確定主要專案參照背景工作專案。In C# and C++, make sure the main project references the background task project. 如果此參照未就緒,背景工作將不會包含在應用程式套件中。If this reference is not in place, the background task won't be included in the app package.
  • 在 C# 與 C++ 中,確定背景工作專案的 [輸出類型] 為「Windows 執行階段元件」。In C# and C++, make sure the Output type of the background task project is "Windows Runtime Component".
  • 背景類別必須在套件資訊清單的進入點屬性中進行宣告。The background class must be declared in the entry point attribute in the package manifest.

手動觸發背景工作以偵錯背景工作程式碼Trigger background tasks manually to debug background task code

您可以透過 Microsoft Visual Studio 手動觸發背景工作。Background tasks can be triggered manually through Microsoft Visual Studio. 然後就可以逐步檢查程式碼並進行偵錯。Then you can step through the code and debug it.

  1. 在 C# 中,請在背景類別的 Run 方法中設置中斷點 (若為同處理序背景工作,請在 App.OnBackgroundActivated() 設置中斷點),和/或使用 System.Diagnostics 來撰寫偵錯輸出。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.

    在 C++ 中,請在背景類別的 Run 類別中設置中斷點 (若為同處理序背景工作,請在 App.OnBackgroundActivated() 設置中斷點),和/或使用 OutputDebugString 來撰寫偵錯輸出。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. 在偵錯工具中執行您的應用程式,然後使用 [週期事件] 工具列來觸發背景工作。Run your application in the debugger and then trigger the background task using the Lifecycle Events toolbar. 這個下拉式清單會顯示可由 Visual Studio 啟用的背景工作名稱。This drop down shows the names of the background tasks that can be activated by Visual Studio.

注意

[生命週期事件] 工具列選項預設不會顯示在 Visual Studio 中。The Lifecycle Events toolbar options are not shown by default in Visual Studio. 若要顯示這些選項,請以滑鼠右鍵按一下 Visual Studio 中的目前工具列,並確定已啟用 [調試位置] 選項。To show these options, right-click on the current toolbar in Visual Studio and ensure the option Debug Location is enabled.

For this to work, the background task must already be registered and it must still be waiting for the trigger. 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.

注意

使用下列觸發程式的背景工作無法以這種方式啟用:應用程式觸發程式MediaProcessing 觸發程式、 ControlChannelTriggerPushNotificationTrigger和背景工作,使用具有SmsReceived觸發程式類型的SystemTriggerBackground 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.
ApplicationTriggerMediaProcessingTrigger 可以使用 trigger.RequestAsync() 在程式碼中手動發送訊號。Application trigger and MediaProcessingTrigger can be signaled manually in code with trigger.RequestAsync().

偵錯背景工作

  1. 當背景工作啟用時,偵錯工具會連結到工作,並在 VS 顯示偵錯輸出。When the background task activates, the debugger will attach to it and display debug output in VS.

偵錯背景工作啟用Debug background task activation

注意

本節適用於在跨處理序中執行的背景工作,且不適用於同處理序背景工作。This section is specific to background tasks the run out-of-process and does not apply to in-process background tasks.

背景工作啟用仰賴下列三要件:Background task activation depends on three things:

  • 背景工作類別的名稱與命名空間The name and namespace of the background task class
  • 在套件資訊清單中指定的進入點屬性The entry point attribute specified in the package manifest
  • 您的 app 在註冊背景工作時指定的進入點The entry point specified by your app when registering the background task
  1. 使用 Visual Studio 記下背景工作的進入點:Use Visual Studio to note the entry point of the background task:

    • 在 C# 與 C++ 中,記下背景工作專案中所指定的背景工作類別的名稱與命名空間。In C# and C++, note the name and namespace of the background task class specified in the background task project.
  2. 使用資訊清單設計工具來檢查已在套件資訊清單中正確宣告背景工作:Use the manifest designer to check that the background task is correctly declared in the package manifest:

    • 在 C# 與 C++ 中,進入點屬性必須符合類別名稱後的背景工作命名空間。In C# and C++, the entry point attribute must match the background task namespace followed by the class name. 例如: RuntimeComponent1.MyBackgroundTask.For example: RuntimeComponent1.MyBackgroundTask.
    • 也必須指定與工作搭配使用的所有觸發程序類型。All the trigger type(s) used with the task must also be specified.
    • 除非您使用 ControlChannelTriggerPushNotificationTrigger,否則「切勿」指定可執行檔。The executable MUST NOT be specified unless you are using the ControlChannelTrigger or PushNotificationTrigger.
  3. 僅 Windows。Windows only. 查看 Windows 使用的進入點來啟動背景工作、啟用偵錯追蹤,以及使用 Windows 事件記錄檔。To see the entry point used by Windows to activate the background task, enable debug tracing and use the Windows event log.

    如果您遵照此程序但事件日誌顯示背景工作發生錯誤進入點或觸發程序,表示您的 app 未正確註冊背景工作。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. 如需此工作的協助,請參閱註冊背景工作For help with this task see Register a background task.

    1. 移至 [開始] 畫面並搜尋 eventvwr.exe,開啟事件檢視器。Open event viewer by going to the Start screen and searching for eventvwr.exe.
    2. 前往 [事件檢視器] 中的 [應用程式和服務記錄 - >檔] [> Microsoft - Windows - > BackgroundTaskInfrastructure ]。Go to Application and Services Logs -> Microsoft -> Windows -> BackgroundTaskInfrastructure in the event viewer.
    3. 在 [動作] 窗格中 ,選取 - > [顯示分析和偵錯工具記錄] 以啟用診斷記錄。In the actions pane, select View -> Show Analytic and Debug Logs to enable the diagnostic logging.
    4. 選取 [診斷記錄檔] ,然後按一下 [啟用記錄]Select the Diagnostic log and click Enable Log.
    5. 現在嘗試使用應用程式再次註冊並啟動背景工作。Now try using your app to register and activate the background task again.
    6. 檢視診斷記錄檔,以取得詳細的錯誤資訊。View the diagnostic logs for detailed error information. 當中包含為背景工作註冊的進入點。This will include the entry point registered for the background task.

背景工作偵錯資訊的事件檢視器

背景工作和 Visual Studio 套件部署Background tasks and Visual Studio package deployment

如果使用背景工作的應用程式是利用 Visual Studio 所部署,且隨後更新了在資訊清單設計工具中指定的版本 (主要和/或次要),則後續透過 Visual Studio 重新部署應用程式時,可能會使應用程式的背景工作停止。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. 這可以透過下列方式來修正:This can be remedied as follows:

  • 執行與套件一起產生的指令碼,使用 Windows PowerShell (而非 Visual Studio) 來部署已更新的應用程式。Use Windows PowerShell to deploy the updated app (instead of Visual Studio) by running the script generated alongside the package.
  • 如果您已經使用 Visual Studio 部署應用程式,而應用程式的背景工作現在停止了,請重新啟動或登出/登入,讓應用程式的背景工作再次運作。If 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.
  • 您可以選取 [永遠重新安裝我的封裝] 偵錯選項,避免在 C# 專案中發生這個狀況。You can select the "Always re-install my package" debugging option to avoid this in C# projects.
  • 等待 app 準備就緒再進行最終部署,以遞增套件版本 (不要在偵錯期間變更)。Wait until the app is ready for final deployment to increment the package version (don’t change it while debugging).

備註Remarks

  • 確認您的 app 會先檢查現有背景工作註冊,以免再次註冊背景工作。Make sure your app checks for existing background task registrations before registering the background task again. 多次登錄相同背景工作會在每次觸發背景工作時多次執行該背景工作,因而造成無法預期的結果。Multiple registrations of the same background task can cause unexpected results by running the background task more than once each time it is triggered.
  • 如果背景工作需要鎖定畫面存取,請確定先將 app 置於鎖定畫面後,再嘗試偵錯背景工作。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. 如需為具有鎖定畫面功能的 App 指定資訊清單選項的詳細資訊,請參閱在應用程式資訊清單中宣告背景工作For info on specifying manifest options for lock screen-capable apps, see Declare background tasks in the application manifest.
  • 背景工作登錄參數都是在登錄時驗證。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.

如需使用 VS 來 debug 背景工作的詳細資訊,請參閱如何在 UWP 應用程式中觸發暫止、繼續和背景事件For more info on using VS to debug a background task see How to trigger suspend, resume, and background events in UWP apps.