在應用程式資訊清單中宣告背景工作Declare background tasks in the application manifest

重要 APIImportant APIs

在應用程式資訊清單中,透過宣告背景工作為延伸的方式,啟用它們的使用。Enable the use of background tasks by declaring them as extensions in the app manifest.

重要

本文是針對跨處理序背景工作所撰寫。This article is specific to out-of-process background tasks. 同處理序背景工作不會在資訊清單中進行宣告。In-process background tasks are not declared in the manifest.

跨處理序背景工作必須在應用程式資訊清單中進行宣告,否則您的 App 將無法註冊背景工作 (將會擲回例外狀況)。Out-of-process background tasks must be declared in the app manifest or else your app will not be able to register them (an exception will be thrown). 此外,跨處理序背景工作必須在應用程式資訊清單中進行宣告才能通過認證。Additionally, out-of-process background tasks must be declared in the application manifest to pass certification.

這個主題假設您已建立了一或多個背景工作類別,而且您的 App 註冊要執行的每一項背景工作以回應至少一個觸發程序。This topic assumes you have a created one or more background task classes, and that your app registers each background task to run in response to at least one trigger.

手動新增延伸Add Extensions Manually

開啟 app 資訊清單 (Package.appxmanifest),然後移至 Application 元素。Open the application manifest (Package.appxmanifest) and go to the Application element. 建立 Extensions 元素 (如果還不存在時)。Create an Extensions element (if one doesn't already exist).

下列的程式碼片段取自背景工作範例The following snippet is taken from the background task sample:

<Application Id="App"
   ...
   <Extensions>
     <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.SampleBackgroundTask">
       <BackgroundTasks>
         <Task Type="systemEvent" />
         <Task Type="timer" />
       </BackgroundTasks>
     </Extension>
     <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ServicingComplete">
       <BackgroundTasks>
         <Task Type="systemEvent"/>
       </BackgroundTasks>
     </Extension>
   </Extensions>
 </Application>

新增背景工作延伸Add a Background Task Extension

宣告您的第一個背景工作。Declare your first background task.

將這個程式碼複製到 Extensions 元素 (您將在下列步驟新增屬性)。Copy this code into the Extensions element (you will add attributes in the following steps).

<Extensions>
    <Extension Category="windows.backgroundTasks" EntryPoint="">
      <BackgroundTasks>
        <Task Type="" />
      </BackgroundTasks>
    </Extension>
</Extensions>
  1. 將 EntryPoint 屬性變更成具有登錄背景工作時您的程式碼用來做為進入點的相同字串 (namespace.classname)。Change the EntryPoint attribute to have the same string used by your code as the entry point when registering your background task (namespace.classname).

    在此範例中,進入點是 ExampleBackgroundTaskNameSpace.ExampleBackgroundTaskClassName:In this example, the entry point is ExampleBackgroundTaskNameSpace.ExampleBackgroundTaskClassName:

<Extensions>
    <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ExampleBackgroundTaskClassName">
       <BackgroundTasks>
         <Task Type="" />
       </BackgroundTasks>
    </Extension>
</Extensions>
  1. 變更 Task Type 屬性清單以表示使用這個背景工作的工作登錄類型。Change the list of Task Type attribute to indicate the type of task registration used with this background task. 如果使用多個觸發程序類型來登錄背景工作,請針對每一個觸發程序類型,新增其他 Task 元素與 Type 屬性。If the background task is registered with multiple trigger types, add additional Task elements and Type attributes for each one.

    注意   請務必列出您所使用的每個觸發程式類型,否則背景工作將不會登錄未宣告的觸發程式類型, (register方法將會失敗,並擲回例外狀況) 。Note  Make sure to list each of the trigger types you're using, or the background task will not register with the undeclared trigger types (the Register method will fail and throw an exception).

    這個程式碼片段範例指出系統事件觸發程序和推播通知的用法:This snippet example indicates the use of system event triggers and push notifications:

<Extension Category="windows.backgroundTasks" EntryPoint="Tasks.BackgroundTaskClass">
    <BackgroundTasks>
        <Task Type="systemEvent" />
        <Task Type="pushNotification" />
    </BackgroundTasks>
</Extension>

新增多個背景工作擴充功能Add multiple background task extensions

針對每一個由應用程式註冊的其他背景工作類別,重複步驟 2。Repeat step 2 for each additional background task class registered by your app.

下列範例是取自背景工作範例的完整 Application 元素。The following example is the complete Application element from the background task sample. 這將示範兩種背景工作類別的使用,總共有 3 種觸發程序類型。This shows the use of 2 background task classes with a total of 3 trigger types. 複製此範例的 Extensions 區段,並視需要進行修改,以在應用程式資訊清單中宣告背景工作。Copy the Extensions section of this example, and modify it as needed, to declare background tasks in your application manifest.

<Applications>
    <Application Id="App"
      Executable="$targetnametoken$.exe"
      EntryPoint="BackgroundTask.App">
        <uap:VisualElements
          DisplayName="BackgroundTask"
          Square150x150Logo="Assets\StoreLogo-sdk.png"
          Square44x44Logo="Assets\SmallTile-sdk.png"
          Description="BackgroundTask"

          BackgroundColor="#00b2f0">
          <uap:LockScreen Notification="badgeAndTileText" BadgeLogo="Assets\smalltile-Windows-sdk.png" />
            <uap:SplashScreen Image="Assets\Splash-sdk.png" />
            <uap:DefaultTile DefaultSize="square150x150Logo" Wide310x150Logo="Assets\tile-sdk.png" >
                <uap:ShowNameOnTiles>
                    <uap:ShowOn Tile="square150x150Logo" />
                    <uap:ShowOn Tile="wide310x150Logo" />
                </uap:ShowNameOnTiles>
            </uap:DefaultTile>
        </uap:VisualElements>

      <Extensions>
        <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.SampleBackgroundTask">
          <BackgroundTasks>
            <Task Type="systemEvent" />
            <Task Type="timer" />
          </BackgroundTasks>
        </Extension>
        <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ServicingComplete">
          <BackgroundTasks>
            <Task Type="systemEvent"/>
          </BackgroundTasks>
        </Extension>
      </Extensions>
    </Application>
</Applications>

宣告背景工作執行所在位置Declare where your background task will run

您可以指定背景工作執行所在位置︰You can specify where your background tasks run:

  • 預設會在 BackgroundTaskHost.exe 處理序中執行。By default, they run in the BackgroundTaskHost.exe process.
  • 在前景應用程式所在的相同處理序中。In the same process as your foreground application.
  • 使用 ResourceGroup 將多背景工作放在相同的主控處理序,或分別放在不同的處理序。Use ResourceGroup to place multiple background tasks into the same hosting process, or to separate them into different processes.
  • 使用 SupportsMultipleInstances 在新處理序中執行背景處理程序,這個新的處理序會在每次引發新的觸發程序時取得本身的資源限制 (記憶體、CPU)。Use SupportsMultipleInstances to run the background process in a new process that gets its own resource limits (memory, cpu) each time a new trigger is fired.

在前景應用程式所在的那個處理序中執行Run in the same process as your foreground application

以下是宣告背景工作的範例 XML,這個背景工作與前景應用程式在相同處理序中執行。Here is example XML that declares a background task that runs in the same process as the foreground application.

<Extensions>
    <Extension Category="windows.backgroundTasks" EntryPoint="ExecModelTestBackgroundTasks.ApplicationTriggerTask">
        <BackgroundTasks>
            <Task Type="systemEvent" />
        </BackgroundTasks>
    </Extension>
</Extensions>

當您指定 EntryPoint 時,應用程式會在觸發程序引發時收到對指定之方法的回呼。When you specify EntryPoint, your application receives a callback to the specified method when the trigger fires. 如果沒有指定 EntryPoint,應用程式則會透過 OnBackgroundActivated() 收到回呼。If you do not specify an EntryPoint, your application receives the callback via OnBackgroundActivated(). 如需詳細資訊,請參閱建立和註冊同處理序的背景工作See Create and register an in-process background task for details.

使用 ResourceGroup 屬性來指定背景工作執行所在的位置。Specify where your background task runs with the ResourceGroup attribute.

以下是一個範例 XML,當中宣告在 BackgroundTaskHost.exe 處理程序中執行的背景工作,但該處理程序是與其他來自相同 App 的背景工作執行個體不同的執行個體。Here is example XML that declares a background task that runs in a BackgroundTaskHost.exe process, but in a separate one than other instances of background tasks from the same app. 注意 ResourceGroup 屬性,此屬性可識別哪些背景工作會在一起執行。Note the ResourceGroup attribute, which identifies which background tasks will run together.

<Extensions>
    <Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTasks.SessionConnectedTriggerTask" ResourceGroup="foo">
      <BackgroundTasks>
        <Task Type="systemEvent" />
      </BackgroundTasks>
    </Extension>
    <Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTasks.TimeZoneTriggerTask" ResourceGroup="foo">
      <BackgroundTasks>
        <Task Type="systemEvent" />
      </BackgroundTasks>
    </Extension>
    <Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTasks.TimerTriggerTask" ResourceGroup="bar">
      <BackgroundTasks>
        <Task Type="timer" />
      </BackgroundTasks>
    </Extension>
    <Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTasks.ApplicationTriggerTask" ResourceGroup="bar">
      <BackgroundTasks>
        <Task Type="general" />
      </BackgroundTasks>
    </Extension>
    <Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTasks.MaintenanceTriggerTask" ResourceGroup="foobar">
      <BackgroundTasks>
        <Task Type="general" />
      </BackgroundTasks>
    </Extension>
</Extensions>

每次觸發程序透過 SupportsMultipleInstances 屬性引發時,在新的處理序中執行Run in a new process each time a trigger fires with the SupportsMultipleInstances attribute

此範例會宣告在新處理序中執行的背景工作,這個新的處理序在每次引發新的觸發程序時取得本身的資源限制 (記憶體、CPU)。This example declares a background task that runs in a new process that gets its own resource limits (memory and CPU) every time a new trigger is fired. 注意啟用此行為的 SupportsMultipleInstances 使用方式。Note the use of SupportsMultipleInstances which enables this behavior. 若要使用此屬性,您必須將 SDK 版本 ' 10.0.15063 ' 設為目標 (Windows 10 Creators Update) 或更高版本。In order to use this attribute you must target SDK version '10.0.15063' (Windows 10 Creators Update) or higher.

<Package
    xmlns:uap4="https://schemas.microsoft.com/appx/manifest/uap/windows10/4"
    ...
    <Applications>
        <Application ...>
            ...
            <Extensions>
                <Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTasks.TimerTriggerTask">
                    <BackgroundTasks uap4:SupportsMultipleInstances="True">
                        <Task Type="timer" />
                    </BackgroundTasks>
                </Extension>
            </Extensions>
        </Application>
    </Applications>

注意

您無法連同 SupportsMultipleInstances 一起指定 ResourceGroupServerNameYou cannot specify ResourceGroup or ServerName in conjunction with SupportsMultipleInstances.