Simple, robust workflow system for mobile (.NET PCL) based apps

We build a lot of mobile apps. And those apps are usually complex. They send stuff to servers, process things in order, handle network connectivity issues, app exit and resume etc. It’s a lot going on, and we found our apps were getting a bit too complex and we were handling the same issues every time we start a new project – there had to be a better way.

Well now there is – we made a super simple workflow called XWorkflow. It’s available as part of the (under construction) MSPL based Xamling-Core.

Xamling-Core on GitHub.
Xamling-Core Nuget Package (Xamarin Unified build coming soon – just finishing testing).
Source code from a talk on Workflow bits – with examples – on GitHub.

More examples are in Xamling-Core test suite (in the Big Windows tests, it’s a bit quicker to work in there, then run on Xamarin later).

Gist showing how to track flows in the UI.

Note on platform support

Most of Xamling-Core is portable, and indeed you can use those bits stand-alone. The actual MVVM and UI components are designed to work on Xamarin Forms, Windows Phone and Windows 8 style apps. At the moment the UI bits are working on Xamarin Forms – iOS and Windows 8 (we call that BigWindows – because soon it will be Windows 10 and yeah, anyway – no more metro…). Anyway, we’re working on Windows Phone and Android MVVM stuff very soon.

What can it do?

By our definition here, a workflow is a bunch of tasks that need to be performed in a certain order, with pass or fail results.

You configure a bunch of stages in order, compile the flow and start firing entities in to it! The core goal of this system is not a fancy feature set – but to be very simple and reliable.

Features of our workflow system are:

  • Resume if app quits unexpectadly (or indeed – expectadly).
  • Configurable retry. Try again if it fails up to your defined count. Tell the user if it fails for ever.
  • UI can restart a flow easily without having to keep track of what actually failed (just say, try again with a button). Great for generic UI’s that don’t know about your underlying model etc.
  • Great for integration with UI (so can easily report progress in some funky UI you make). Receive notifications when flow stages are updated.
  • Wait for network (stages can be configured to require network before starting).
  • Disconnected flow – like a long running server process that sends a push when completed, or UI based stages that need user input.
  • It’s hardy – crashes will not affect it.
  • It’s serialisable – you can send WF state to the server for diagnosis.
  • Stages are pass or fail, and each stage can have friendly UI text for each result.
  • You can merge stages in to other stages – so merge your save item to server flow in to a create new item flow.
  • It’s portable. This will work on any .NET platform that supports Portable Class Libraries. It’s designed for mobile, but we’ve used it all over the place!
  • Much more!

Note on Entities

This workflow system works only with entities in the Xamling-Core entity system. It’s pretty easy – implement the interface IEntity and then call the .Set() extension method on them… they will then be available in the Xamling-Core entity management system – that’s another entire post in itself 🙂

See examples in the sample talk code here for entity manager usage. It’s pretty simple. I’ll do a better post on it another time.

A simple usage of this system might be to upload data to a server and wait for result (even if network doesnt come back until after the next app launch!).


The flow stage set up process is fluent.

await _hub
      .AddFlow(Workflows.DownloadEntity, "Download")

Here we configure a new flow. This one downloads something from the server (when it calls _entityProcessService.RefreshEntryFromServer.

First you add a new flow giving it a flowId and a friendly name. You can use this flowId later to access it from other places in your code.

public XFlow AddFlow(string flowId, string friendlyName)

Next you configure the steps. Give each step a friendly id, a success UI text, fail UI text, the method to run, is disconnected, requires network, number of retries and a special fail function if needed.

We often pass in strings that the UI will use to look up the localised version of the text.

 public XFlow AddStage(string stageId, string processingText, string failText, Func<Guid, Task<XStageResult>> function,
            bool isDisconnectedProcess = false, bool requiresNetwork = false, int retries = 0, Func<Guid, Task<XStageResult>> failFunction = null)

You can do other stuff like merge flows


Remember to call .Complete() when you’re done!

Our tip is to make your flows small, and merge them in to larger flows. Compose them…

Starting a flow

Getting an entity in to the flow is simple using hte extension method. Of course you can do it the long way (check out EntityDataExtensions.cs)

using XamlingCore.Portable.Data.Extensions
await thisEntity.StartWorkflow(Workflows.ProcessNotificationMessage);

Off it goes!

As I said the Workflow systems uses the EntityManager system (which is another part of Xamling-Core). The core principal of that system is that once an entity is set, it always gets the same item given the same Id. It’s also serialized to the local storage, so you can get it later even if the app restarts. So the WF system uses only Ids to transport data around… making the entire thing super simple internally.

Call backs to your code look something like this

public async Task RefreshEntryFromServer(Guid entryId)
var entry = await _entryEntityManager.Get(entryId);
if (entry == null)
return new XStageResult(false, entryId);

As you can see – it’s up to you to get the entity and ensure it’s good to go.

A successful result would be returned like this

return new XStageResult(true, entryId);

You can control a fair bit from those XStageResult returns, you can even change the Id of the entity… just in case the server gave you a new Id when it did it’s bit.

public XStageResult(bool isSuccess, Guid id, string extraText = null, bool completeNow = false, string exception = null)

It obviously say if the operation was successful or not, can provide some more text for the UI, can terminate the flow early (successful result, but terminate now) and provide any exception details – either for the UI or to send up to the server as part of diagnosis (keeping in mind the entire workflow state is serialised).

Work in progress

We’re still just adding in some features and making it better, but so far it’s pretty stable and seems to be working well… It’s being used in the Project Tripod for iPhone code to upload images to the sever, wait for processing, then download the result again after a push notification.

If you need some help getting it going or have any other ideas and feedback please let me know! Remember to check through the examples at the top and to keep an eye out for more posts coming soon.


Simple Alternative to AutoMapper

Recently we had some troubles with AutoMapper after upgrading our core libraries (Xamling-Core) to Xamarin Unified. Our unit tests started failing.

There is more detail on that issue here:

In the meantime it left us scrambling for a replacement. Our entity cache and management system relies on mapping to ensure entity instances are the same no matter how you get it… a job for a mapper. Keep original entity in memory, any updates come in you copy the new data on to the in memory instance… all references are happy.

So we had a look around, and turns our – we don’t really use many of AutoMappers features. Great lib to be sure – but we are doing the most basic of mappings.

The solution was found on StackOverflow (naturally) posted by user Azerothian here.

We made a few little mods and made it available as part of the Xamling-Core library.



EDIT – it was pointed out by @JakeGinnivan that this would be slower than AutoMapper… keep that in mind for high usage scenarios. Shouldn’t be a problem in a mobile app, but worth keeping in mind – thanks Jake!

Strange SIGSEGV after upgrading to Xamarin Unified

So we upgraded to Xamarin Unified so our app – Project Tripod – would be accepted in to the store. It wasn’t a horrible process. Few refactors here and there. Of course, that meant we had to update Xamling-Core too. There were a few headaches there unfortunately.

We kept getting this strange crash when writing strings to the file system. It showed in a lot of our tests – ending with a crash something like this:

2015-01-24 12:35:23.660 AutomapperProblemReplicate[601:149248] critical: Stacktrace:
2015-01-24 12:35:23.661 AutomapperProblemReplicate[601:149248] critical:   at  
2015-01-24 12:35:23.661 AutomapperProblemReplicate[601:149248] critical:   at (wrapper managed-to-native) object.__icall_wrapper_mono_array_new_specific (intptr,int) 
2015-01-24 12:35:23.662 AutomapperProblemReplicate[601:149248] critical:   at System.IO.StreamWriter.Initialize (System.Text.Encoding,int) [0x00017] in /Developer/MonoTouch/Source/mono/mcs/class/corlib/System.IO/StreamWriter.cs:77
2015-01-24 12:35:23.662 AutomapperProblemReplicate[601:149248] critical:   at System.IO.StreamWriter..ctor (string,bool,System.Text.Encoding,int) [0x00076] in /Developer/MonoTouch/Source/mono/mcs/class/corlib/System.IO/StreamWriter.cs:146

We spent quite some time debugging this… only to discover much later the culprit was something else entirely.

It was AutoMapper. Very strange indeed… remove all Mapper.CreateMap calls and Mapper.Map etc – and voila, problem gone.

We’ve raised an issue on the AutoMapper GitHub. It’s not been accepted or reviewed yet, so it’s not officially recognised, but maybe this post will help you anyway.

File read problems on Xamarin + iOS

The repro code for this post can be found here:

Note: The solution to the problem is not in that repro, it’s below. The repro helped us figure out what was happening.

I was having some quite severe issues when reading content in my Xamarin.iOS app. Data would either come back corrupted (out of order) or the file read operation would return the entirely wrong data (old data!).

The corruptions were what tipped it off first. We were saving serialised entities to the filesystem but when reading them back again the JSON parser started throwing errors. The text would be out of order, parts replicated, and double end braces and other strange bits and bobs.

The problem was using IsolatedStorageFile! Don’t use it! It sort of works sometimes… seems the problems occur after a while. I didn’t get to the bottom of exactly what was causing the problem or why, but essentially don’t use it!

Instead use File.WriteAllText and the other related methods as outlined in the Xamarin documentation here:

For a working example see


        public async Task<bool> SaveString(string fileName, string data)
           var path = _getPath(fileName);

            File.WriteAllText(path, data);
            return true;

        void _createDirForFile(string fileName)
            var dir = Path.GetDirectoryName(fileName);

            //Debug.WriteLine("Creating Directory: {0}", fileName);

            if (dir == null)

            if (!Directory.Exists(dir))

        // <summary>
        /// iOS 8 Specific get path
        /// </summary>
        /// <param name="fileName"></param>
        /// <returns></returns>
        private string _getPath(string fileName)
            var documents = NSFileManager.DefaultManager.GetUrls(NSSearchPathDirectory.LibraryDirectory, NSSearchPathDomain.User)[0];
            var str = documents.Path;
            var result = Path.Combine(str, fileName);
            return result;


Developer User Experience – It’s your Job!

This is an excerpt from my up coming TechEd Melbourne Talk entitled Xamarin with a View.

As a senior developer, software architect or just all round gun developer – your duty is to set up your projects for your end users…

And by that I mean other devs. You are responsible to choosing patterns and practices to keep them in the game, to reduce work, complexity and improve quality.

That is squarely your job – you facilitate them. They are your end user.

So often devs go in and set up projects the “correct” way with out any regards for the devs that actually have to sit there and use it. I see this a lot especially with consultancies. They give you best break neck up to date stuff on the latest nugets -> then leave with no regard for developer user experience – there is no elegance to it. Just smashing things in there and leaving them is just not good enough. It’s easy – you need to finish the job.

Your framework set up needs to be the sheep dog, the guardian angel and their roadblock all at once.

It must be super easy for devs to introduce new code using your conventions and patterns – it should be so hard to get wrong it’s embarrassing.

Your developers will be forced in to using the best patterns and practices without even knowing it half the time.

I want you to consider these things when you’re next setting up a project or when you’re asked to make framework choices.

I want you to join me in improving the Developer User Experience (DEVUX).

Developer UX – something that I think we don’t consider enough.

Of course I’ll be showing some techniques on how to do this!


Time Period Library for .NET

Extensive time period calculations and individual calendar periods.

A while ago we had to write an EPG for a WP8 TV app that we’re building for a client. As part of this we had the need to do some pretty difficult DateTime calculations.

Finding out if a C# DateTime is within a time range is hard. Finding out if two time ranges intersect is even harder!

Install this little Nuget package and you can do stuff like:

var cellTimeRange = new TimeRange(nowTime.AddHours(-2), nowTime.AddHours(3));
var timeCellsInRange = cell.TimeCells.Where(_ => new TimeRange(_.StartTime, _.EndTime).IntersectsWith(cellTimeRange)).ToList();

How cool is that!