Declarar tarefas em segundo plano no manifesto do app

  • Artigo

APIs importantes

Habilite o uso de tarefas em segundo plano declarando-as como extensões no manifesto do aplicativo.

Importante

Este artigo é específico para tarefas em segundo plano fora do processo. As tarefas em segundo plano em processo não são declaradas no manifesto.

As tarefas em segundo plano fora do processo devem ser declaradas no manifesto do aplicativo, caso contrário, seu aplicativo não poderá registrá-las (uma exceção será gerada). Além disso, as tarefas em segundo plano fora do processo devem ser declaradas no manifesto do aplicativo para passar na certificação.

Este tópico pressupõe que você tenha criado uma ou mais classes de tarefa em segundo plano e que seu aplicativo registre cada tarefa em segundo plano a ser executada em resposta a pelo menos um gatilho.

Adicionar extensões manualmente

Abra o manifesto do aplicativo (Package.appxmanifest) e vá para o elemento Application. Crie um elemento Extensions (se ainda não existir).

O snippet a seguir é obtido do exemplo de tarefa em segundo plano:

<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 plano

Declare sua primeira tarefa em segundo plano.

Copie esse código para o elemento Extensions (você adicionará atributos nas etapas a seguir).

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

  1. Altere o atributo EntryPoint para ter a mesma cadeia de caracteres usada pelo código como o ponto de entrada ao registrar sua tarefa em segundo plano (namespace.classname).

    Neste exemplo, o ponto de entrada é ExampleBackgroundTaskNameSpace.ExampleBackgroundTaskClassName:

<Extensions>
    <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ExampleBackgroundTaskClassName">
       <BackgroundTasks>
         <Task Type="" />
       </BackgroundTasks>
    </Extension>
</Extensions>

  1. Altere a lista do atributo Tipo de Tarefa para indicar o tipo de registro de tarefa usado com essa tarefa em segundo plano. Se a tarefa em segundo plano estiver registrada com vários tipos de gatilho, adicione elementos Task e atributos Type adicionais para cada um.

    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 falhará e gerará uma exceção).

    Este exemplo de snippet indica o uso de gatilhos de eventos do sistema e notificações por push:

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

Adicionar várias extensões de tarefas em segundo plano

Repita a etapa 2 para cada classe de tarefa em segundo plano adicional registrada pelo seu aplicativo.

O exemplo a seguir é o elemento Application completo do exemplo de tarefa em segundo plano. Isso mostra o uso de 2 classes de tarefa em segundo plano com um total de 3 tipos de gatilho. Copie a seção Extensões deste exemplo e modifique-a conforme necessário para declarar tarefas em segundo plano no manifesto do aplicativo.

<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 onde sua tarefa em segundo plano será executada

Você pode especificar onde suas tarefas em segundo plano são executadas:

  • Por padrão, eles são executados no processo BackgroundTaskHost.exe.
  • No mesmo processo que seu aplicativo em primeiro plano.
  • Use ResourceGroup para colocar várias tarefas em segundo plano no mesmo processo de hospedagem ou para separá-las em processos diferentes.
  • Use SupportsMultipleInstances para executar o processo em segundo plano em um novo processo que obtém seus próprios limites de recursos (memória, cpu) sempre que um novo gatilho é disparado.

Execute no mesmo processo que seu aplicativo em primeiro plano

Aqui está um exemplo de XML que declara uma tarefa em segundo plano que é executada no mesmo processo que o aplicativo em primeiro plano.

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

Quando você especifica EntryPoint, seu aplicativo recebe um retorno de chamada para o método especificado quando o gatilho é acionado. Se você não especificar um EntryPoint, seu aplicativo receberá o retorno de chamada por meio de OnBackgroundActivated(). Consulte Criar e registrar uma tarefa em segundo plano em processo para obter detalhes.

Especifique onde sua tarefa em segundo plano é executada com o atributo ResourceGroup.

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

<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 for acionado com o atributo SupportsMultipleInstances

Este exemplo declara uma tarefa em segundo plano que é executada em um novo processo que obtém seus próprios limites de recursos (memória e CPU) sempre que um novo gatilho é disparado. Observe que o uso de SupportsMultipleInstances que habilita esse comportamento. Para usar esse atributo, você deve direcionar a versão do SDK '10.0.15063' (Windows 10 Creators Update) ou posterior.

<Package
    xmlns:uap4="http://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 em conjunto com SupportsMultipleInstances.