Declarar tarefas em segundo plano no manifesto do appDeclare background tasks in the application manifest

APIs importantesImportant APIs

Habilite o uso de tarefas em segundo plano declarando-as como extensões no manifesto do aplicativo.Enable the use of background tasks by declaring them as extensions in the app manifest.

Importante

Este artigo é específico para tarefas em segundo plano fora do processo.This article is specific to out-of-process background tasks. Tarefas em segundo plano no processo não são declaradas no manifesto.In-process background tasks are not declared in the manifest.

As tarefas em segundo plano fora do processo devem ser declaradas no manifesto do aplicativo ou ele não será capaz de registrá-las (uma exceção será gerada).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). Além disso, as tarefas em segundo plano fora do processo devem ser declaradas no manifesto do aplicativo para passar certificação.Additionally, out-of-process background tasks must be declared in the application manifest to pass certification.

Este tópico considera que você criou uma ou mais classes de tarefa em segundo plano e que o seu aplicativo registra cada tarefa em segundo plano para execução em resposta a pelo menos um gatilho.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.

Adicionar extensões manualmenteAdd Extensions Manually

Abra o manifesto do aplicativo (Package.appxmanifest) e vá para o elemento Application.Open the application manifest (Package.appxmanifest) and go to the Application element. Crie um elemento Extensions (caso não haja um).Create an Extensions element (if one doesn't already exist).

O seguinte trecho foi retirado do exemplo de tarefa de segundo plano: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>

Adicionar uma extensão de tarefa em segundo planoAdd a Background Task Extension

Declare sua primeira tarefa em segundo plano.Declare your first background task.

Copie o código no elemento Extensions (você adicionará atributos nas próximas etapas).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. Altere o atributo EntryPoint para que ele tenha a mesma cadeia de caracteres usada pelo código como o ponto de entrada ao registrar a tarefa em segundo plano (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).

    Neste exemplo, o ponto de entrada é 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. Modifique a lista de atributos Tipo de Tarefa para indicar o tipo do registro de tarefa usado com essa tarefa em segundo plano.Change the list of Task Type attribute to indicate the type of task registration used with this background task. Se a tarefa em segundo plano for registrada com vários tipos de gatilho, adicione outros elementos Task e atributos Type para cada um deles.If the background task is registered with multiple trigger types, add additional Task elements and Type attributes for each one.

    Observação    Certifique-se de listar cada um dos tipos de gatilho que você está usando, ou a tarefa em segundo plano não será registrada com os tipos de gatilho não declarados (o método Register irá falhar e gerar uma exceção).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).

    Este exemplo de trecho indica o uso de gatilhos de evento do sistema e notificações por push: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>

Adicionar múltiplas extensões de tarefa em segundo planoAdd multiple background task extensions

Repita a etapa 2 para cada classe adicional de tarefa em segundo plano registrada pelo aplicativo.Repeat step 2 for each additional background task class registered by your app.

O exemplo a seguir mostra o elemento Application completo da amostra de tarefa em segundo plano.The following example is the complete Application element from the background task sample. Ele ilustra o uso de 2 classes de tarefa em segundo plano com um total de 3 tipos de gatilho.This shows the use of 2 background task classes with a total of 3 trigger types. Copie a seção Extensões desse exemplo e modifique-a conforme o necessário para declarar tarefas em segundo plano no manifesto do aplicativo.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>

Declarar onde a tarefa em segundo plano será executadaDeclare where your background task will run

Você pode especificar onde as tarefas em segundo plano são executadas:You can specify where your background tasks run:

  • Por padrão, elas são executadas no processo BackgroundTaskHost.exe.By default, they run in the BackgroundTaskHost.exe process.
  • No mesmo processo do aplicativo em primeiro plano.In the same process as your foreground application.
  • Use ResourceGroup para inserir diversas tarefas em segundo plano no mesmo processo de hospedagem ou para separá-las em processos diferentes.Use ResourceGroup to place multiple background tasks into the same hosting process, or to separate them into different processes.
  • Use SupportsMultipleInstances para executar o processo em segundo plano em um novo processo que obtém seus próprio limites de recursos (cpu, memória) sempre que um novo gatilho é acionado.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.

Execute no mesmo processo do aplicativo em primeiro plano.Run in the same process as your foreground application

Aqui está o XML de exemplo que declara uma tarefa em segundo plano, a qual é executada no mesmo processo como o aplicativo em primeiro plano.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>

Ao especificar o EntryPoint, o aplicativo recebe um retorno de chamada para o método especificado quando o gatilho é acionado.When you specify EntryPoint, your application receives a callback to the specified method when the trigger fires. Se você não especificar um EntryPoint, o aplicativo recebe o retorno de chamada por meio de OnBackgroundActivated().If you do not specify an EntryPoint, your application receives the callback via OnBackgroundActivated(). Consulte Criar e registrar uma tarefa em segundo plano no processo para obter mais detalhes.See Create and register an in-process background task for details.

Especifique onde sua tarefa em segundo plano é executada com o atributo ResourceGroup.Specify where your background task runs with the ResourceGroup attribute.

Aqui está o XML de exemplo que declara uma tarefa em segundo plano que é executada em um processo do BackgroundTaskHost.exe, mas em um separado de outras instâncias de tarefas em segundo plano do mesmo aplicativo.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. Observe o atributo ResourceGroup, que identifica quais tarefas em segundo plano serão executadas juntas.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>

Execute em um novo processo sempre que um gatilho é acionado com o atributo SupportsMultipleInstancesRun in a new process each time a trigger fires with the SupportsMultipleInstances attribute

Esse exemplo declara uma tarefa em segundo plano executada em um novo processo que obtém seus próprios limites de recursos (memória e CPU) sempre que um novo gatilho é acionado.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. Observe o uso de SupportsMultipleInstances, que habilita esse comportamento.Note the use of SupportsMultipleInstances which enables this behavior. Para usar esse atributo, você deve ter como destino a versão do SDK ' 10.0.15063 ' (atualização do Windows 10 para criadores) ou superior.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>

Observação

Você não pode especificar ResourceGroup ou ServerName juntamente com SupportsMultipleInstances.You cannot specify ResourceGroup or ServerName in conjunction with SupportsMultipleInstances.