Home > Articles > Programming > C#

  • Print
  • + Share This
From the author of Lock Screen Tasks

Lock Screen Tasks

Some background tasks are not available to your app unless you use the lock screen. These apps take advantage of the lock screen capabilities to provide real-time information to the user. Some background tasks are not available unless your app uses the lock screen. The Windows 8.1 lock screen provides “at a glance” information to users. It is possible for apps to present their own information on the lock screen. If your app has summary information that changes in real time, it may be a candidate for the lock screen. Example lock screen information includes upcoming appointments, current weather conditions, recent emails, and message alerts.

The lock screen information mirrors the app’s tile and/or badge content. In fact, the same API for updating tiles and badges is used for the lock screen. The only difference is that your app manifest indicates it has a presence on the lock screen, and a special lock screen badge is presented. Depending on whether you configure the app for badge or badge and tile access, tile updates and badge notifications will automatically propagate to the lock screen for your app.

The LockScreenExample app in the Chapter15 solution folder illustrates the proper way to set up an app to display on the lock screen. The first step is to configure lock screen notifications on the Application tab of the manifest. You must specify at a minimum a 24 x 24 pixel monochrome icon to represent your app on the lock screen. In addition, you must specify a background task. Lock screen apps require that you declare either control channel, timer, or push notification background task. You only have to declare the tasks for the app to compile—the app will run if you never implement the task, but it won’t be very functional for the user!

To declare the background task, add Background Tasks from the Declarations tab in the manifest. The entry point references the fully qualified name for a class (namespace and class name) that is used to run the task. The task itself is defined in a separate Windows Runtime project that will be referenced from the main project. This is necessary because of the way the background task will be activated and executed by the system. The LockScreenExample app references the LockScreenTasks project. The project contains a class that implements the IBackgroundTask interface. This is the class specified as the entry point for the background task. The LockTimer class is implemented for the example project.

The class exposes a static method that generates a random badge and sets the badge and tile text. It is implemented using a generic method so the main app can reuse the method to configure the initial badge and tile status (you can verify that the OnLaunched method in the App.xaml.cs file for LockScreenExample calls this method).

The Run method is required to implement the IBackgroundTask interface. It takes one parameter of type IBackgroundTaskInstance that represents the task being run. This enables you to use the same class to handle multiple task types. You can query the task instance for the name and instance id and to fire various events. This particular implementation only calls the static method to update the tile and badge information.

A common background task involves calling web services or querying websites for information. These are asynchronous tasks and require the task scheduler to wait until they are finished. If you don’t handle them correctly, the Run method will exit before the asynchronous tasks are complete. To fix this, simply flag the method as asynchronous and request a deferral from the task. Complete the deferral when your code is done processing. The general pattern looks like this:

public async void Run(IBackgroundTaskInstance taskInstance)
{
    var deferral = taskInstance.getDeferral();
    await DoStuff();
    deferral.complete();
}

The ability to run background tasks is useful especially when you don’t have a server set up to send push notifications. Your app may need to poll other websites periodically or even create a persistent connection that controls the apps. Now that you have the task written, you must set up the trigger that will make the task run and register it. The LockScreenExample project sets up the background task in MainPage.xaml.cs. It requests access to the lock screen and sets up the expected connectivity.

Although the user can opt-in for your app to appear on the lock screen, there is an additional step required to show the detailed status if you are using tile text. The only way your app will automatically show detailed status is if it is the first app to register for the lock screen. Due to built-in apps like Mail and Calendar, this is rarely the case. To see your detailed status (and not just the badge) on the lock screen, the user must activate the Charms bar and choose Settings followed by Change PC settings, PC and devices, then Lock screen. The user will then have to click on the icon below Choose an app to display detailed status and select your app from the list.

You create a background task using the BackgroundTaskBuilder. Create an instance of this class and set the Name property as well as the entry point for the task. The entry point is the fully qualified name of the class that implements the IBackgroundTask interface.

var builder = new BackgroundTaskBuilder
                    {
                        Name = TimerTask,
                        TaskEntryPoint = "LockScreenTasks.LockTimer"
                    };
                

The builder exposes a Register method to register the task that returns the instance of the task itself.

var registration = builder.Register();
  • + Share This
  • 🔖 Save To Your Account