How to create a lock screen app that uses background network triggers (XAML)

Article
10/13/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

This topic shows how to create a lock screen app to receive background network notifications in a Windows Store app using network triggers with ControlChannelTrigger.

Objective: Create a lock screen app that receives network notifications using network triggers when the app is in the background.

Prerequisites

The following information applies to any connected or network-aware Windows Store app that depends on network connections using TCP to always be connected. This topic applies to apps written in C++/XAML and apps using the .NET Framework 4.5 in C#, VB.NET, or managed C++ on Windows 8.1 and Windows Server 2012 R2.

This topic does not apply to apps written in JavaScript or a foreground app in JavaScript with an in-process C# or C++ binary. Background network connectivity using a network trigger with ControlChannelTrigger is not supported by a JavaScript app. For information on background tasks that apply to JavaScript apps, see Supporting your app with background tasks. For information on background network connectivity supported by a JavaScript app, see Staying connected in the background (HTML).

Creating a lock screen app that uses background network triggers

Before you can use network triggers with ControlChannelTrigger, you must make your app a lock screen app.

You must set the appropriate capabilities in the app manifest so that your app requests to be placed on the lock screen. Your app must also include code to request to be added to the lock screen and handle cases where it is added to or removed from the lock screen by the user.

To get onto the lock screen, an app must get consent from the user. The consent prompt appears when the lock screen request API is called. If the user does not give your app permission to run on the lock screen, then you will not be able to prompt for permission again. However, if the user accidently dismisses the dialog you will be able to prompt again.

If the user denies your app permission to be a lock screen app, they can add the app to the lock screen at a later time via the system permissions fly-out for your app. Users can also manually add your app to the lock screen from the Personalize section of PC settings.

To request that your app be placed on the lock screen you must complete the following steps. You can make changes to the app manifest using Microsoft Visual Studio 2013 to open the package.appxmanifest file or by manually modifying the app manifest.

Register to become a lock screen app

Ensure that your app’s tile has a wide logo associated with it in the app manifest. Ensure that the app manifest has set the WideLogo attribute on the DefaultTile element.

The following sample adds a DefaultTile element under the <VisualElements> element in an app manifest.
```
    <DefaultTile ShowName="allLogos" WideLogo="images\tile.png" />
```
Indicate your app's intention to use a background task. The app manifest must also specify the executable file that contains the background task and the class name where the entry point of the background task is implemented.

When building a lock screen app that uses the network trigger feature, specify the controlChannel background task type. This will enable your app to receive network trigger notifications.

For the controlChannel background task type, the executable file for background task is the app itself. For other background tasks such as time triggers or system event triggers, the default host for background execution is the backgroundtaskhost.exe file.

Apps using ControlChannelTrigger rely on in-process background task activation. In this case, the DLL or executable binary file that implements the background tasks for keep-alive and push notification must be linked as a winmd file into the app. Linking the helper DLL or library as a winmd file will auto generate the in-process background extensions specified in the app package manifest. Otherwise the in-process background task is not activated.

The following sample adds a raw push notification and a network trigger notification under the <Application> element in an app manifest.
```
  <Extensions>
    <Extension Category="windows.backgroundTasks" 
        Executable="$targetnametoken$.exe" 
        EntryPoint="Background.ReceivePacketTask">
      <BackgroundTasks>
        <Task Type="controlChannel" />
      </BackgroundTasks>
    </Extension>
  </Extensions> 
```
Since your app will be on the lock screen, it must also have a lock screen icon that can be used to display missed notifications. To enable this, update your app manifest to include the LockScreen element.

The following sample shows a LockScreen element added under the <VisualElements> element in an app manifest.
```
    <LockScreen Notification="badge" BadgeLogo="Images\badgelogo.png" />
```
After you have completed the previous steps, your app can request permission from the user to be placed on the lock screen. The Background.BackgroundExecutionManager.RequestAccessAsync methods present the user with a dialog box that requests that an app be added to the lock screen. If the user approves the request, your app can run in the background and place notifications on the lock screen.

The following sample requests permission to be placed on the lock screen.
```
    bool lockScreenAdded = false;

    async void ClientInit() {
        // Lock screen is required to let in-process RealTimeCommunication related
        // background code to run.
        //
        if (lockScreenAdded == false) {
            BackgroundAccessStatus status = await BackgroundExecutionManager.RequestAccessAsync();
            Diag.DebugPrint("Lock screen status" + status);

            switch (status) {
                case BackgroundAccessStatus.AllowedWithAlwaysOnRealTimeConnectivity:
                    //
                    // App is allowed to use RealTimeConnection broker 
                    // functionality even in low power mode.
                    //
                    lockScreenAdded = true;
                    break;
                case BackgroundAccessStatus.AllowedMayUseActiveRealTimeConnectivity:
                    //
                    // App is allowed to use RealTimeConnection broker 
                    // functionality but not in low power mode.
                    //
                    lockScreenAdded = true;
                    break;
                case BackgroundAccessStatus.Denied:
                    //
                    // App should switch to polling mode (example: poll for email based on time triggers)
                    //
                    Diag.DebugPrint("As Lockscreen status was Denied, App should switch to polling mode such as email based on time triggers.");
                    break;
            }
        }
        return;
    }
```
When building a lock screen app using the network trigger feature, the BackgroundAccessStatus for your app may be set to AllowedWithAlwaysOnRealTimeConnectivity after permission has been granted. This allows the app to use the RealTimeConnection (RTC) broker even in low-power mode which is also referred to as connected-standby. Only a limited number of lockscreen apps are allowed permission to use RTC in low-power mode. So your app may be set to AllowedMayUseActiveRealTimeConnectivity if there are already three lock screen apps allowed to use RTC in low-power mode.

After your app is added to the lock screen it should be visible in the Personalize section of the PC settings. Note that users may opt to remove your app from the list of lock screen apps at any time. So you must ensure that your app is always functional even when it has been removed from lock screen.

If an app wants to use the ControlChannelTrigger and uses the Background.BackgroundExecutionManager.RequestAccessAsync method to request the user to let the app be added to the lock screen, the asynchronous completion of the Background.BackgroundExecutionManager.RequestAccessAsync method is not a guarantee that the ControlChannelTrigger object can be created successfully. The app may get an error that indicates that access was denied when it tries to create and register the ControlChannelTrigger object. The recommended way to create a ControlChannelTrigger object is to first register background tasks for the System Event trigger for lock screen add and lock screen remove events. When the background task for the lock screen add occurs for the app, then the app can safely create and register the ControlChannelTrigger object.

For more information on lock screen requests, see the Lock screen overview and the Lock screen apps sample.

Summary and next steps

For more information on how to use network triggers to deliver notifications to a lock screen app, see How to use network triggers to deliver notifications to a lock screen app.

For more information on how to write a background task to receive background network notifications that use network triggers, see How to write a background task for a network trigger.

For more information on how to re-establish a network trigger and a transport connection, see How to re-establish a network trigger and transport connection.

For more information on using a StreamSocket with a network trigger, see How to use a stream socket with a network trigger.

For more information on using a MessageWebSocket or StreamWebSocket with a network trigger, see How to use a WebSocket with a network trigger

For more information on how to use HttpClient with a network trigger, see How to use HttpClient with a network trigger.

For more information on how to use with a network trigger, see How to use IXMLHttpRequest2 with a network trigger

For more information on guidelines and checklists for using network triggers, see Guidelines and checklist for using network triggers.

Other resources

Adding support for networking

Background Networking

Lock screen overview

Staying connected in the background

Supporting your app with background tasks

Troubleshooting and debugging network connections