Rob Gibbens: Backgrounding with Xamarin.Forms

In Xamarin University, we have a few in depth courses dedicated to learning the concepts of backgrounding in iOS and Android _{[iOS210, iOS211, AND210]}. If you’re not familiar with the concept, I highly suggest checking out those courses if you’re a Xamarin University subscriber, or reading our excellent documentation on the Xamarin developer portal.

Backgrounding is the term we use for the process of allowing some of the code in our app to continue to execute while another app is in the foreground. On iOS, prior to iOS 9, only a single app is allowed to execute code at a time. This is referred to as the foreground app. If you don’t change your code to tell iOS that you plan on running code in the background, your app will be forcefully terminated and removed from memory if your code attempts to execute in the background. Android actually does allow code to run in a background activity, but background activities are one of the first things to be terminated if the operating system needs more memory. Instead, on Android, we should use another special class called a Service.

One of the most common questions we hear is “How can we run these background tasks in a Xamarin.Forms app?” One of the best features of the Xamarin platform, and Xamarin.Forms specifically, is the ability to share large chunks of our code across platforms. This is often true in the case of background tasks as well. The function that we want to execute, such as saving data or calling a web service, is going to be the same on both iOS and Android. Unfortunately, the way that these two platforms have evolved to handle executing background code is completely different. As such, there is no way that we can abstract the backgrounding feature into the Xamarin.Forms library. Instead, we going to continue to rely on the native APIs to execute our shared background task.

We could try to abstract this functionality with interfaces and dependency injection, but the platforms are so different that this won’t work well. Instead, we’ll turn to some features built into Xamarin.Forms to help us achieve these goals and create robust apps. The Xamarin.Forms framework has two feature built in to it that are going to help us here. The first is a simple way to quickly persist some data, called the Properties Dictionary. The second feature, called MessagingCenter will allow our shared code to communicate with each platform in a loosely coupled way. We’ll use this feature to build our UI in Xamarin.Forms, and then send a message to the iOS and Android apps to kick off a background task in each platform’s specific way, using its platform specific API.

The platform project will be able to execute its background apis, and then call into our shared code to actually execute the shared task.

As the background task is running, we will also want to send messages from the platform projects BACK to the shared Xamarin.Forms code in order to provide status notification and update the Xamarin.Forms UI.

Sample code is available at my Github repo

There are three common backgrounding scenarios that we are going to look at.

• Persisting some state quickly when the user sends our app to the background
• Long running, or finite length, tasks that are a normal part of our app’s logic. These are important tasks that we don’t want to be interrupted when the app is sent to the background, but we want to continue to run our code without terminating our app.
• Downloading a file, which is handled as a Background Necessary Application in iOS, and a Service in Android

Persist Data

Save data in Xamarin.Forms

public class App : Application { protected override void OnSleep () { Application.Current.Properties ["SleepDate"] = DateTime.Now.ToString("O"); Application.Current.Properties ["FirstName"] = _backgroundPage.FirstName; } protected override void OnStart () { LoadPersistedValues (); } protected override void OnResume () { LoadPersistedValues (); } private void LoadPersistedValues() { if (Application.Current.Properties.ContainsKey("SleepDate")) { var value = (string)Application.Current.Properties ["SleepDate"]; DateTime sleepDate; if (DateTime.TryParse (value, out sleepDate)) { _backgroundPage.SleepDate = sleepDate; } } if (Application.Current.Properties.ContainsKey("FirstName")) { var firstName = (string)Application.Current.Properties ["FirstName"]; _backgroundPage.FirstName = firstName; } }}

public class StartLongRunningTaskMessage {}public class StopLongRunningTaskMessage {}public class TickedMessage { public string Message { get; set; }}

public async Task RunCounter(CancellationToken token) { await Task.Run (async () => { for (long i = 0; i < long.MaxValue; i++) { token.ThrowIfCancellationRequested (); await Task.Delay(250); var message = new TickedMessage { Message = i.ToString() }; Device.BeginInvokeOnMainThread(() => { MessagingCenter.Send<TickedMessage>(message, "TickedMessage"); }); } }, token);}

startLongRunningTask.Clicked += (s, e) => { var message = new StartLongRunningTaskMessage (); MessagingCenter.Send (message, "StartLongRunningTaskMessage");};stopLongRunningTask.Clicked += (s, e) => { var message = new StopLongRunningTaskMessage (); MessagingCenter.Send (message, "StopLongRunningTaskMessage");};

[Register ("AppDelegate")]public partial class AppDelegate : global::Xamarin.Forms.Platform.iOS.FormsApplicationDelegate { public override bool FinishedLaunching (UIApplication app, NSDictionary options) { MessagingCenter.Subscribe<StartLongRunningTaskMessage> (this, "StartLongRunningTaskMessage", async message => { longRunningTaskExample = new iOSLongRunningTaskExample (); await longRunningTaskExample.Start (); }); MessagingCenter.Subscribe<StopLongRunningTaskMessage> (this, "StopLongRunningTaskMessage", message => { longRunningTaskExample.Stop (); }); }}

public class iOSLongRunningTaskExample { nint _taskId; CancellationTokenSource _cts; public async Task Start () { _cts = new CancellationTokenSource (); _taskId = UIApplication.SharedApplication.BeginBackgroundTask ("LongRunningTask", OnExpiration); try { //INVOKE THE SHARED CODE var counter = new TaskCounter(); await counter.RunCounter(_cts.Token); } catch (OperationCanceledException) { } finally { if (_cts.IsCancellationRequested) { var message = new CancelledMessage(); Device.BeginInvokeOnMainThread ( () => MessagingCenter.Send(message, "CancelledMessage") ); } } UIApplication.SharedApplication.EndBackgroundTask (_taskId); } public void Stop () { _cts.Cancel (); } void OnExpiration () { _cts.Cancel (); }}

[Activity (Label = "FormsBackgrounding.Droid", Icon = "@drawable/icon", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation)]public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsApplicationActivity { protected override void OnCreate (Bundle bundle) { MessagingCenter.Subscribe<StartLongRunningTaskMessage> (this, "StartLongRunningTaskMessage", message => { var intent = new Intent (this, typeof(LongRunningTaskService)); StartService (intent); }); MessagingCenter.Subscribe<StopLongRunningTaskMessage> (this, "StopLongRunningTaskMessage", message => { var intent = new Intent (this, typeof(LongRunningTaskService)); StopService (intent); }); }}

[Service]public class LongRunningTaskService : Service { CancellationTokenSource _cts; public override IBinder OnBind (Intent intent) { return null; } public override StartCommandResult OnStartCommand (Intent intent, StartCommandFlags flags, int startId) { _cts = new CancellationTokenSource (); Task.Run (() => { try { //INVOKE THE SHARED CODE var counter = new TaskCounter(); counter.RunCounter(_cts.Token).Wait(); } catch (OperationCanceledException) { } finally { if (_cts.IsCancellationRequested) { var message = new CancelledMessage(); Device.BeginInvokeOnMainThread ( () => MessagingCenter.Send(message, "CancelledMessage") ); } } }, _cts.Token); return StartCommandResult.Sticky; } public override void OnDestroy () { if (_cts != null) { _cts.Token.ThrowIfCancellationRequested (); _cts.Cancel (); } base.OnDestroy (); }}

void HandleReceivedMessages () { MessagingCenter.Subscribe<TickedMessage> (this, "TickedMessage", message => { Device.BeginInvokeOnMainThread (() => { ticker.Text = message.Message; }); }); MessagingCenter.Subscribe<CancelledMessage> (this, "CancelledMessage", message => { Device.BeginInvokeOnMainThread (() => { ticker.Text = "Cancelled"; }); });}

downloadButton.Clicked += (sender, e) => { var message = new DownloadMessage { Url = "http://xamarinuniversity.blob.core.windows.net/ios210/huge_monkey.png" }; MessagingCenter.Send (message, "Download");}

MessagingCenter.Subscribe<DownloadMessage> (this, "Download", async message => { var downloader = new Downloader (message.Url); await downloader.DownloadFile ();});

public class CustomSessionDownloadDelegate : NSUrlSessionDownloadDelegate { public override void DidWriteData (NSUrlSession session, NSUrlSessionDownloadTask downloadTask, long bytesWritten, long totalBytesWritten, long totalBytesExpectedToWrite) { float percentage = (float)totalBytesWritten / (float)totalBytesExpectedToWrite; var message = new DownloadProgressMessage () { BytesWritten = bytesWritten, TotalBytesExpectedToWrite = totalBytesExpectedToWrite, TotalBytesWritten = totalBytesWritten, Percentage = percentage }; MessagingCenter.Send<DownloadProgressMessage> (message, "DownloadProgressMessage"); } public override void DidFinishDownloading (NSUrlSession session, NSUrlSessionDownloadTask downloadTask, NSUrl location) { CopyDownloadedImage (location); var message = new DownloadFinishedMessage () { FilePath = targetFileName, Url = downloadTask.OriginalRequest.Url.AbsoluteString }; MessagingCenter.Send<DownloadFinishedMessage> (message, "DownloadFinishedMessage"); } /// More}

MessagingCenter.Subscribe<DownloadMessage> (this, "Download", message => { var intent = new Intent (this, typeof(DownloaderService)); intent.PutExtra ("url", message.Url); StartService (intent);});

[Service]public class DownloaderService : Service { public override IBinder OnBind (Intent intent) { return null; } public override StartCommandResult OnStartCommand (Intent intent, StartCommandFlags flags, int startId) { var url = intent.GetStringExtra ("url"); Task.Run (() => { var imageHelper = new ImageHelper (); imageHelper.DownloadImageAsync (url) .ContinueWith (filePath => { var message = new DownloadFinishedMessage { FilePath = filePath.Result }; MessagingCenter.Send (message, "DownloadFinishedMessage"); }); }); return StartCommandResult.Sticky; }}

MessagingCenter.Subscribe<DownloadProgressMessage> (this, "DownloadProgressMessage", message => { Device.BeginInvokeOnMainThread(() => { this.downloadStatus.Text = message.Percentage.ToString("P2"); });});MessagingCenter.Subscribe<DownloadFinishedMessage> (this, "DownloadFinishedMessage", message => { Device.BeginInvokeOnMainThread(() => { catImage.Source = FileImageSource.FromFile(message.FilePath); });});