在应用程序清单中声明后台任务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.

必须在应用清单中声明进程外后台任务,否则你的应用将无法注册它们(会引发异常)。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.

本主题假定你已创建一个或多个后台任务类,并且你的应用注册了为响应至少一个触发器而运行的所有后台任务。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

打开应用程序清单 (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. 复制此示例的“扩展”部分,并根据需要进行修改,以在应用程序清单中声明后台任务。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 进程中运行。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. 请注意使用可启用此行为的 SupportsMultipleInstancesNote the use of SupportsMultipleInstances which enables this behavior. 若要使用此属性,必须以 SDK 版本 "10.0.15063" 为目标 (Windows 10 创意者更新) 或更高版本。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.