What is a BackgroundTask? In short – it’s  a lightweight code that the OS run in the background. Its purpose can be various and it can nicely extend your App. In this example we would write an App for Windows Phone 8.1 Runtime (but as I’ve mentioned before the steps are the same for other platforms). We will write a BackgroundTask  that will send a Toast message from background. Where to start?

1. Fisrt we have to add a new RuntimeComponent to our solution. To do this, right click on your solution in Solution explorer window in Visual Studio. Then click Add, New project… and choose Windows Runtime Component (Pic. 1) - depending on your purpose it can be portable or windows phone.

Pic. 1 Add WinRT Component

Pic. 2 Add reference

2. Once we have the new project added, we need to add a reference  (Pic. 2) to it in our main project in which we will register our BackgroundTask – without this step, our App will crash once we try to run the background code.

3. Here comes the time to define our BackgroundTask. Of course the purpose of it depends on our needs. Let our task inform the User that it is running – for this we will implement a Toast message. We shall also remember that to make it work we need to set our App as Toast capable – open Package.appxmanifest file, chose Application tab, in section Notifications set App as toast capable. The simple code of our task can look like this:

namespace MyTask
{
    public sealed class FirstTask : IBackgroundTask
    {
        public void Run(IBackgroundTaskInstance taskInstance)
        {
            // simple example with a Toast, to enable this go to manifest file
            // and mark App as TastCapable - it won't work without this
            // The Task will start but there will be no Toast.
            ToastTemplateType toastTemplate = ToastTemplateType.ToastText02;
            XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(toastTemplate);
            XmlNodeList textElements = toastXml.GetElementsByTagName("text");
            textElements[0].AppendChild(toastXml.CreateTextNode("My first Task - Yeah"));
            textElements[1].AppendChild(toastXml.CreateTextNode("I'm a message from your background task!"));
            ToastNotificationManager.CreateToastNotifier().Show(new ToastNotification(toastXml));
        }
    }
}

What is imortant in the code above:

• we need to define a sealed class that will implement IBackgroundTask interface – which means that we will have to write a public void Run(IBackgroundTaskInstance taskInstance) method, that will perform our background work.
• the name of the class and the namespace are imortant as we will have to specify the entry point of our BackgroundTask (see next step)
• our Run method can be asynchronous, in this case we will have to obtain a BackgroundTaskDeferral  by using a taskInstance.GetDeferral() method. This will inform the OS that our background task might continue to perform work after the Run method returns. We must only remember to call BackgroundTaskDeferral.Complete() once we finish our job.

4. Now is the time to declare the entry point of our background task. To do this we need to open Package.appxmanifest file, find Declarations tab, choose BackgroundTask in dropdown menu and click Add. We should see it defined in the list below. We must also decide the type of our BackgroundTask - if it will be invoked upon System event, Timer or other. For the purpose of this example we will use Timer type – our task will be fired upon TimeTrigger event. All this you can see in the picture 3.

Pic. 3 Declarations

5. The time has come to register our BackgroundTask. First we shall check if the task is already registered, to do this we can enumerate BackgroundTaskRegistration.AllTasks , for the sake of simplicity, once we have found our task, we will just return from the method. To register the task we will use BackgroundTaskBuilder  - we will need to specify its entry point (the same as we had set in Declarations), provide a name of the task, set the Trigger (that will fire our task) and optionally we can specify SystemCondition. The sample code can look like this:

private async void RegisterBtn_Click(object sender, RoutedEventArgs e)
{
    string myTaskName = "FirstTask";

    // check if task is already registered
    foreach (var cur in BackgroundTaskRegistration.AllTasks)
        if (cur.Value.Name == myTaskName)
        {
            await (new MessageDialog("Task already registered")).ShowAsync();
            return;
        }

    // Windows Phone app must call this to use trigger types (see MSDN)
    await BackgroundExecutionManager.RequestAccessAsync();

    // register a new task
    BackgroundTaskBuilder taskBuilder = new BackgroundTaskBuilder { Name = "First Task", TaskEntryPoint = "MyTask.FirstTask" };
    taskBuilder.SetTrigger(new TimeTrigger(15, true));
    BackgroundTaskRegistration myFirstTask = taskBuilder.Register();

    await (new MessageDialog("Task registered")).ShowAsync();
}

In the code above, we have registered a task that will be fired upon TimeTrigger event. Althought we have set its freshness time to 15 minutes, it doesn’t mean that it will be fired exacly after this time – OS has a build-in timer that runs background tasks in 30 minutes intervals on Windows Phone (15 minutes on Windows). We have also set the task as OneShot, which means that it will be fired once (not in 15-30 minute intervals).

Finally once we click the button (invoke the method), our BackgroundTask will be registered and it should be run after 15-30 minutes. But what to do to test it faster – do we, as developers, have to wait? No, there is quite an easy way to invoke the BackgroundTask earlier, upon demand. To do this we have to open the Debug location toolbar in Visual Studio, select our task from dropdown menu Lifecycle events (sometimes you may need to open the menu few times to refresh it) and once we click on the name it will be fired (Pic. 4).

Pic. 4 Test the Task

The complete working example you can download here – SimpleBackgrounsTask

When writing a Windows Runtime App , the situation it’s little different – we cannot use above Task as it doen’t exist in the API. We will have to use MediaCapture class.

First what we have to do is to initialize the class – within this step we will also need to declare which camera we wish to use and set the resolution. The sample code can look like this:

private static async Task<DeviceInformation> GetCameraID(Windows.Devices.Enumeration.Panel desiredCamera)
{
    // get available devices for capturing pictures
    DeviceInformation deviceID = (await DeviceInformation.FindAllAsync(DeviceClass.VideoCapture))
        .FirstOrDefault(x => x.EnclosureLocation != null && x.EnclosureLocation.Panel == desiredCamera);

    if (deviceID != null) return deviceID;
    else throw new Exception(string.Format("Camera of type {0} doesn't exist.", desiredCamera));
}

async private void InitCameraBtn_Click(object sender, RoutedEventArgs e)
{
    var cameraID = await GetCameraID(Windows.Devices.Enumeration.Panel.Back);
    captureManager = new MediaCapture();

    await captureManager.InitializeAsync(new MediaCaptureInitializationSettings
        {
            StreamingCaptureMode = StreamingCaptureMode.Video,
            PhotoCaptureSource = PhotoCaptureSource.VideoPreview,
            AudioDeviceId = string.Empty,
            VideoDeviceId = cameraID.Id
        });

    var maxResolution = captureManager.VideoDeviceController.GetAvailableMediaStreamProperties(MediaStreamType.Photo).Aggregate((i1, i2) => (i1 as VideoEncodingProperties).Width > (i2 as VideoEncodingProperties).Width ? i1 : i2);
    await captureManager.VideoDeviceController.SetMediaStreamPropertiesAsync(MediaStreamType.Photo, maxResolution);
}

Pic. 1. Image stripes

Choosing camera device is quite obvious – most mobile devices nowadays have at least two cameras and we should pick one (on my Phone default is Front camera). The code above identifies the ID of Back camera and then initializes MediaCapture class with suitable properties. Why do we have to set the resolution after initialization? – there is probably a default one. Yes that’s right, but if we don’t set the proper resolution then our taken photo can suffer strange stripes on its sides (Pic. 1).

So we have our class initialized, it’s prepared to take photos, but it will be nice to see what we will be in our picture. Here comes CaptureElement class with help. Using it in XAML is very simple:

<CaptureElement x:Name="capturePreview" Stretch="Uniform" Height="200" Width="300"/>

When we have it defined, then we can start previewing:

async private void StartPreviewBtn_Click(object sender, RoutedEventArgs e)
{
    // rotate to see preview vertically
    captureManager.SetPreviewRotation(VideoRotation.Clockwise90Degrees);
    capturePreview.Source = captureManager;
    await captureManager.StartPreviewAsync();
}

To stop it – just call

await captureManager.StopPreviewAsync(); 

async private void TakePhotoBtn_Click(object sender, RoutedEventArgs e)
{
    // create a file
    StorageFile photoFile = await ApplicationData.Current.LocalFolder.CreateFileAsync("myFirstPhoto.jpg", CreationCollisionOption.ReplaceExisting);

    // take a photo with choosen Encoding
    await captureManager.CapturePhotoToStorageFileAsync(ImageEncodingProperties.CreateJpeg(), photoFile);

    // we can also take a photo to memory stream
    // InMemoryRandomAccessStream memStream = new InMemoryRandomAccessStream();
    // await captureManager.CapturePhotoToStreamAsync(ImageEncodingProperties.CreateJpegXR(), memStream);

    // show a photo on screen
    BitmapImage bitmapToShow = new BitmapImage(new Uri(photoFile.Path));
    imagePreivew.Source = bitmapToShow;  // show image on screen inside Image control defined in XAML
}

After invoking the method we should see the photo in Image control (of course if we had defined one).

What is important – remember always to Dispose() your MediaCapture class, stop previewing and handle possible errors. Also protect the initializing method from being invoked few times at the same moment – it can hang your Phone or camera so that any other app won’t be able to use it.

<TextBox x:Name="FirstBox" InputScope="Number" Grid.Row="0"/> 
<TextBox x:Name="SecondBox" InputScope="Number" Grid.Row="1"/> 
<TextBox x:Name="ThirdBox" InputScope="Number" Grid.Row="2"/>

Pic. 1 Overlook

The main task of our App is that it should update all three TextBoxes, depending on the user input. So in the code behind we will create an event handler and subscribe it to TextBox.TextChanged event (in this simple example I’ll just put the text informing which TextBox was changed):

public MainPage()
{
   InitializeComponent();
   FirstBox.TextChanged += Box_ChangedOne;
   SecondBox.TextChanged += Box_ChangedOne;
   ThirdBox.TextChanged += Box_ChangedOne;
}
private string info = "";
private void Box_ChangedOne(object sender, TextChangedEventArgs e)
{
    TextBox modifedTextBox = sender as TextBox;
    if (modifedTextBox.Name == "FirstBox") info = "User modified FirstBox";
    else if (modifedTextBox.Name == "SecondBox") info = "User modified SecondBox";
    else if (modifedTextBox.Name == "ThirdBox") info = "User modified ThirdBox";
    FirstBox.Text = info; // this line fires next Box_ChangedOne event
    SecondBox.Text = info; // this line fires next Box_ChangedOne event
    ThirdBox.Text = info; // this line fires next Box_ChangedOne event
}

As you can see, I’ve subscribed Box_ChangedOne to all three TextBoxes  – let’s update everything right after one of them changes (why not?). Here comes the first problem, just after we focus on any control and try to put text – our App hangs. Aha – longer look at the code and it turns out that we are in an infinite loop – our event fires another one (cause it is changing TextBox.Text) and so on.  So we will improve the event handler with a flag which will inform if the change was invoked by user or from the code:

private bool dontChangeFlag = false;
private void Box_ChangedTwo(object sender, TextChangedEventArgs e)
{
    if (!dontChangeFlag)
    {
        TextBox modifedTextBox = sender as TextBox;
        if (modifedTextBox.Name == "FirstBox") info = "User modified FirstBox";
        else if (modifedTextBox.Name == "SecondBox") info = "User modified SecondBox";
        else if (modifedTextBox.Name == "ThirdBox") info = "User modified ThirdBox";
        dontChangeFlag = true; // set the flag to prevent next fired event from further changing Boxes
        FirstBox.Text = info;
        SecondBox.Text = info;
        ThirdBox.Text = info;
        dontChangeFlag = false; // enable changing
    }
}

Looks great, so we should test it. Oops, the program hangs – what is wrong? The solution comes with the MSDN: The TextChanged event is asynchronous. Our simple code is racy, and line 

dontChangeFlag = false;

private async void Box_ChangedThree(object sender, TextChangedEventArgs e)
{
    if (!dontChangeFlag)
    {
        TextBox modifedTextBox = sender as TextBox;
        if (modifedTextBox.Name == "FirstBox") info = "User modified FirstBox";
        else if (modifedTextBox.Name == "SecondBox") info = "User modified SecondBox";
        else if (modifedTextBox.Name == "ThirdBox") info = "User modified ThirdBox";
        dontChangeFlag = true; // set the flag to prevent next fired event from further changing Boxes
        FirstBox.Text = info;
        SecondBox.Text = info;
        ThirdBox.Text = info;
        await Task.Delay(1000); // let's give some time to change Boxes
        dontChangeFlag = false; // enable changing
    }
}

This time we get what we wanted – our flag is working. So far so good – but how to predict how long will it take the phone to finish the events? The answer is – we can’t and don’t do it – let the event informs when it is finished. For this purpose I’ll use a SemaphoreSlim class. And here we will also improve our code (to show the next issue) – our first TextBox will be set up with the entered text:

private string enteredText = "";
private SemaphoreSlim semWait = new SemaphoreSlim(0, 1);
private async void Box_ChangedFour(object sender, TextChangedEventArgs e)
{
    if (!dontChangeFlag)
    {
        TextBox modifedTextBox = sender as TextBox;
        if (modifedTextBox.Name == "FirstBox")
        {
            info = "User modified FirstBox";
            enteredText = FirstBox.Text;
        }
        else if (modifedTextBox.Name == "SecondBox") info = "User modified SecondBox";
        else if (modifedTextBox.Name == "ThirdBox") info = "User modified ThirdBox";
        dontChangeFlag = true; // set the lag to prevent next fired event from further changing Boxes
        FirstBox.Text = enteredText;
        await semWait.WaitAsync(); // wait until finished changing
        SecondBox.Text = info;
        await semWait.WaitAsync(); // wait until finished changing
        ThirdBox.Text = info;
        await semWait.WaitAsync(); // wait until finished changing
        dontChangeFlag = false; // enable changing
    }
    else semWait.Release();
}

Our semaphore should wait until it is released, and it does so, but if we just change the text in the FirstBox then we will see that something is worng – there is no change in other TextBoxes. Quick debug shows that the semaphore waits to be released – what is wrong? Again qucik look at MSDN shows what is going on – If the Text property is set to the same string as the content in the TextBox, the event is not raised. The simpliest way will be to check if the event is going to run:

private async void Box_ChangedFive(object sender, TextChangedEventArgs e)
{
    if (!dontChangeFlag)
    {
        TextBox modifedTextBox = sender as TextBox;
        if (modifedTextBox.Name == "FirstBox")
        {
            info = "User modified FirstBox";
            enteredText = FirstBox.Text;
        }
        else if (modifedTextBox.Name == "SecondBox") info = "User modified SecondBox";
        else if (modifedTextBox.Name == "ThirdBox") info = "User modified ThirdBox";
        dontChangeFlag = true; // set the lag to prevent next fired event from further changing Boxes
        if (FirstBox.Text != enteredText)
        {
            FirstBox.Text = info;
            await semWait.WaitAsync(); // wait until finished changing
        }
        if (SecondBox.Text != info)
        {
            SecondBox.Text = info;
            await semWait.WaitAsync(); // wait until finished changing
        }
        if (ThirdBox.Text != info)
        {
            ThirdBox.Text = info;
            await semWait.WaitAsync(); // wait until finished changing
        }
    }
    else semWait.Release();
}

Finally our code is working as it should.

One may ask – what is the purpose of the slider in the picture? This is a simple test showing that not every event is run asynchronous – if we write a similar method like above, but for Slider’s change:

private void mySlider_ValueChanged(object sender, RoutedPropertyChangedEventArgs<double> e)
{
    if (!dontChangeFlag)
    {
        dontChangeFlag = true;
        mySlider.Value = 50;
        // below process continues after the second   
        // mySlider_ValueChanged has finished its job
        dontChangeFlag = false;
    }
}

and set up breakpoints at lines 3 and 9, then we will see in debug mode that everything works synchronously.

Conclusion: Even if think that you write your code as synchronous, some events/methods can be run as asynchronous, so it’s worth to check them in the documentation.

Complete working example you can download from here.