Another major thing to port is the BackgroundTransfer stuff in the P | Cast app. Although the API is similar there was a lot of code that I needed to port, though a lot of this code could be deleted as well.

Starting a BackgroundTransfer

Let’s start with the easy part. We want to start a BackgroundTransfer. We are no longer bound to save the files to /Shared/Transfers which was required in Windows Phone 8.0, which makes it all much easier. Actually I think we can even download directly to a SD-card if we would like. We just create a StorageFile where we want to store the file to download. We create an instance of a BackgroundDownloader and use that to create a DownloadOperation out of the RequestUri and the StorageFile. Then we construct a CancellationTokenSource which we can use to cancel the download operation. We also construct a Progress feedback delegate. We end by starting the operation and attaching the CancellationToken and the Progress delegate.

Of course we don’t only want feedback on newly created DownloadOperations but also on stuff we created in a previous app-run but which didn’t complete yet. We can easily get all the CurrentDownloads via the BackgroundDownloader. We also construct a CancellationTokenSource and a Progress delegate. We use AttachAsync to attach the Progress delegate and the CancellationTokenSource to the existing DownloadOperation.

How do I cancel that DownloadOperation?

I was trying to port the code by just using the code intellisense, but I couldn’t find a way to cancel a specific BackgroundTransfer. In the end I found something, but for comparison first the Windows Phone 8.0 method to cancel a backgroundtransfer.

BackgroundTransferService.Remove(track.AssociatedRequest);

The explanation of Microsoft: “Because BT is based on the BackgroundTask infrastructure, you cancel a transfer simply by canceling the task”. Sounds nice, but the amount of code is much more than you expect.

In Windows Phone 8.0 we explicitly had to remove the completed downloads from the BackgroundTransfer queue, I couldn’t find anything pointing towards this requirement on Universal apps. So I tried doing BackgroundTransfers without explicitly removing them. And my conclusion is, you don’t need to explicitly remove them from the queue. When the transfer completed without the app running it will be in the queue the first time you start the app again. So you can handle it.

Handling very large files and how to read the different policies

One of the things you had to be aware of was even though you want to allow downloading while running on a battery this wasn’t allowed for files over 100MB. I handled this by trying to download it on battery and check if the TransferError.Message was “The transfer file size is bigger than the allowed limit”. The new BackgroundTransfer API handles this automatically.

In the old API you could set policies that were pretty simple, there were combinations of Allow Cellular and Allowing Battery. You can no longer set policies around the battery because those are handled automatically. Now you can set a policy to UnrestrictedOnly, Default and Always. This is something that needs a bit of clarification with scenario’s I found here.

Scenario

Unrestricted Only

Default

Always

Wi-Fi

Allow

Allow

Allow

Metered connection, not roaming, under data limit, on track to stay under limit

Deny

Allow

Allow

Metered connection, not roaming, under data limit, on track to exceed limit

Deny

Deny

Allow

Metered connection, roaming, under data limit

Deny

Deny

Allow

Metered connection, over data limit. This state only occurs when the user enables “Restrict background data in the Data Sense UI.

One of the things I noticed is the grouping of the TransferStatus.WaitingForX that I couldn’t map directly but are all captured within the BackgroundTransferStatus.PausedBySystemPolicy.

We do see a status Completed in the enum, but in practice I have never seen this status. Even when the transfer is actually completed, based on the BytesReceived is equal to TotalBytesToReceive. This is for both Windows and Windows Phone, so status is still Running but all bytes are already received.

Calculate Progress

Things have been moved around a bit, but calculating progress is still easy to do. So my previous code on Windows Phone 8.0.

Background Transfer Queue

The old BackgroundTransferService had a hard limit of 25 active and pending download requests per application. This caused any app to manage it’s queue. This limit doesn’t exist in the new Background Transfer API, it has a system limit of 1000 however. Nice, no longer managing the queue myself!

Background Transfer behaviors

There’s an important difference between the behavior of background transfers within Windows and Windows Phone. When the Windows Universal app is terminated the background transfers will be terminated as well. This is different from what we are used to within Windows Phone, where the background transfers continue without the app running.

After this I started investigating if I would be able to port my database including the data access code.

Prepare the Windows Phone project

So of course we need to have the SQLite database engine for Windows Phone 8.1. So download this Visual Studio Extensions: SQLite for Windows Phone 8.1. Now it’s time to add a reference to the SQLite engine on the Windows Phone project. It will also add a reference to the Microsoft.VCLibs.

While in the past a special C++ project would have to be added to your Windows Phone 8.0 solution, this is much easier.

Prepare the Windows Project

While I’m still not sure if the Windows version of P | Cast will ever see the light, I want to know if my code is compatible. So I downloaded the Visual Studio Extension: SQLite for Windows Runtime (windows 8.1). So this time add a reference to the SQLite engine on the Windows project.

Time for some Data Access

As always I try to decouple the data access from the UI. It’s a best practice I always try to follow. Nowadays we have Portable Class Libraries so I add a new PCL project to the solution.

I reference this project from both the Windows Phone and the Windows project.

Next I add the same NuGet package I’m used to use in the P | Cast app, called sqlite-net.

Everything compiles, time to migrate code. First I took the code from a table definition. Actually I copied all of my table definition classes, but for this article I’ll show the Subscription definition.

As many of you readers probably know, I wrote a Podcast app called P | Cast. I did this in the early days of Windows Phone 8.0 because it lacked an internal podcast player (for most regions), and all the alternatives from the store weren’t working for me at that moment.

But then came Windows Phone 8.1, it included a podcast player, again. I thought this would be the death of my app. But it isn’t at least it isn’t for myself, I don’t like the internal podcast player that much. So I can of course expand P | Cast to become better, but one of the most requested features, modify playbackspeed, can’t be done on the Windows Phone 8.0 model. Time to port the P | Cast app to Windows Phone 8.1 Universal app. Not an easy task though.

User Interface

Yes both User Interfaces are in Xaml, but there are significant differences, in the controls that are available and also their richness. I’m currently using the Telerik UI for Windows Phone controls. They work perfectly right now, but I can’t use them on an universal app, and their Telerik UI for Windows Universal isn’t as rich as their Windows Phone counter part yet. On the other the current xaml can probably be a good base to start with.

Background Audio

In the Windows Phone 8.0 timeframe, all you have is a Background Audio Agent. There were a lot little quirks in the events that are or aren’t called in the Background Audio Agent. I had to do a lot to make sure track progress could be saved. Hope we don’t have to worry about that anymore. Even using NamedEvents to make sure the BackgroundAudio could somehow communicate with the UI.

Background Processing

P | Cast includes a background agent which is responsible for syncing all podcast feeds and eventually clean up of played podcasts. When the phone is plugged in for charging an even more intense version of the background agent launches which will do background downloading of podcasts. Although the Background Task API is different for Universal apps, the concepts are similar. Just Run code on the background!

Database

All meta-data of the podcasts is stored in a SQLite database. I know you have to do something different to actually use SQLite in the app, but I hope I can still use SQLite-Net library to access the database.

Windows 8 app?

Yes the big question is of course, will there also be a Windows 8 app? Maybe there will be, there’s a lot of code that can be shared in Universal Apps. A new UI design will be required for a Windows 8 app of course. And every user would expect the Windows Phone and Windows apps to be in sync, always. That would require some additional thinking for me. Because I have no idea on how to do that, yet.

What’s next?

So I will write blogposts for each of the above mentioned things. I will explain what I needed to do to implement the different parts, and if possible if I could reuse code or not. If you have any tips for me, please share them in the comments.

It’s already more than half a year ago when I started working on the Chain app. I tried to make the app as beautiful as possible, while thinking about all the Modern UI design principles.

But I’ve had help almost from the beginning. One of the users of my app wanted to help me, make the app even better. Martin Fujak sent me some pictures of improvements I could make. And that’s how both the Montly and Dashboard view came to be, along with some other improvements. Without his help I wouldn’t have come up with ideas on how to visualize the Monthly view. But this isn’t all yet, Martin came up with even more ideas for improvement complete with visual design that I will try to implement in future versions of the Chain app.

Thanks for all the help I got from you so far! I can really recommend you to others who need help with the design of their app.

Martin wasn’t the only Designer who helped with the Design of the Chain app. More on that in a next post.

With the introduction of Windows Phone 8.1 you’ve the choice to either continue with the Windows Phone Silverlight 8.1 option or to use the Windows Phone Store Apps model similar to Windows 8 Store Apps.

Upgrading to the Windows Phone Store Apps model isn’t an easy task either, the Background Audio is implemented in a completely different way. But there are reasons for people to do upgrade to the Windows Phone Store Apps model. One of these is the ability to change the speed of playback, an often requested feature for the P | Cast podcast app I created. Another option is to share a lot of the code by creating a Universal app which will enable both a Windows Store app and a Windows Phone Store app. I will not go into the details of the Background Audio for the Windows Store apps, but they are a little bit different compared to the implementation of the Background Audio in the Windows Phone Store apps. Different, but still similar though!

Alright, enough about the background, let’s start building a very basic app with Background Audio!

A little bit of architecture

We want to play audio which stays playing while our user interface isn’t active. So we need to have a background process that’s capable of playing audio. See the green blocks at the right in below diagram. The actual audio playback occurs in the background process while the foreground process has access to the MediaPlayer information via a Proxy Object.

To manage the Universal Volume Control, like the one below we’ll need to talk to the SystemMediaTransportControl. This API that also exists in Windows 8.1 so if we ever want to create a Universal App this will come in handy.

But the actual communication between the foreground process aka the UI and the background process happens through messaging. You can pass messages from foreground to background, but also the other way around. A message consists of a string message, but can also pass an additional value (only simple value types).

Life Cycle of the Background Task

You want the background audio to continue playing, so you have to get a BackgroundTaskDeferral in the Run method of the IBackgroundTask. You’ll have to complete the deferral upon the Canceled or Completed events of the task. The actual Run method should run to the end in a timely fashion, if it’s more or less waiting in the Run method the Background Task could be terminated to release resources.

The background task for running audio can be cancelled in a couple of situations:

When another app with audio playback starts

When the background task is running but no audio is playing (paused or never started) and the foreground app is suspended

The playback will be automatically paused by media interruptions like a phone call or VoIP call. When the phone call or VoIP call ends within 5 minutes, the background audio is resumed by executing the Run method and sending a ButtonPressed (PlayButton) event on the SystemMediaTransportControls instance. When the call takes longer than 5 minutes the playback doesn’t start but the Universal Volume Control doesn’t loose state and hitting the play button will restart the Background Audio manually.

In the Windows Phone 8.1 App project you can add a reference to the Windows Runtime Component project. Please don’t make it a class library.

Go to the Package.appxmanifest to the Declarations tab and add a Background Task. Give it the the task type Audio and set the Entry point to the BackgroundAudioTask we created by using the full type name (namespace+type name).

The UI of the Player

Because I want to focus on the background audio, I made the UI simple, very simple. One Button, just the play button.

So the little bit of xaml that’s there to create a button with the click handler.

And the PlayButtonClick is almost empty as well. We send a message to the background task. The message has a key indicating the operation Play, the value being a url to the background media we want to play. We will have to handle this in the background audio, but this is all we do in the UI.

Code a Background Task for Background Audio

After all the explanation above it’s time to write some real code. In the below piece of code you can see that all we do in the Run method is preparation. My advice to you is to keep this as short as possible as well. In line 3, we get a reference to the SystemMediaTransportControls, being the Universal Volume Control, and enable the Universal Volume Control.

Let’s first make sure we handle the closing of the background task correctly. The implementation of playing music can wait a bit. Make sure that you save some state if required in the OnCanceled implementation before completing the deferral.

Yes I know, now it’s time to implement the Play back code. Our UI did send a Message to the Background Audio Task, so we need to handle that message. The handling of the message happens in the MessageReceivedFromForeground method. We’re getting the ValueSet message as an argument and need to loop through the ValueSet keys to process the message. If we find a key with the value “Play” (line 8), we want to start the playback of the value passed to the message (line 10).

The implementation isn’t that difficult, most of the code behind the Play method is the updating of the Universal Volume Control with the correct information. For the playing we set AutoPlay and the UriSource (lines 3-5).

The Universal Volume Control has buttons we need to handle as well. In this example we just handle the Play and Pause button, but you can think about implementing the Next and Previous buttons as well.

I am Mark Monster, a Software Engineer specialized in Microsoft technology with
a special interest for Silverlight and Windows Phone 7. In april 2010, Microsoft
rewarded me with a MVP Award for Silverlight.