Nick's .NET Travels

Continually looking for the yellow brick road so I can catch me a wizard....

Windows Phone Page Lifecycle, Tombstoning and Data Caching

The title of this post sounds a little weird but is actually quite fundamental to how you develop for Windows Phone. Most training content/courses for Windows Phone seem to focus unnecessarily on the application wide events of launching, closing, activating and deactivating. These are useful to get an understanding of what tombstoning is and why it happens. However, in most cases what’s more important is knowing and understanding the page methods which you can override to intercept the page lifecycle, namely OnNavigatedTo and OnNavigatedFrom. These methods always occur as a pair and as such make a useful point at which to save and restore page data.

Let’s assume we now know that we are going to save and restore information in the OnNavigatedFrom and OnNavigatedTo. The next question is what data are we going to load and where to load it from. So now we need to look at different scenarios:

First time arriving at a page

The only thing you should rely on absolutely is the navigation uri for the page (look at the navigationeventargs). This should tell you all the information you need in order to load the data for the page. It might include a product id, a serialized object or some other identifier of the data you want to load.

Using the information from the navigation uri you then need to load the data for the page. This might come from:

- an in-memory application wide store (eg repository model)
- loaded from cached data on disk
- retrieve data from a service

Notice that these are in order of increasing latency. To make your applications appear more responsive you need to think about how you can cache content in memory and/or disk before calling out to a service

Leaving a page

When you leave a page there are two options:

- Forward navigation to some other page and/or application – in this case you need to cache the current data for the page in the State dictionary for the page. When the user comes back to the page, you should retrieve the information from the State dictionary and use it to populate the page. The advantage of the State dictionary is that it automatically handles Tombstoning for you!

- Backward navigation – in this case it’s up to you as to whether you cache the data or not. Caching the data has the advantage that if the use goes to that page again, the data can be loaded very quickly (eg browsing to the same news article again). You can’t use the built in page State dictionary for this because each time you navigate to a page, it will get an new State dictionary, so you’ll have to come up with your own caching mechanism.

Returning to a page

This is similar to arriving at a page, with the only exception that you need to look in the State dictionary first.

The important take away from this post is that looking up data should be a progressive action: start with the page State dictionary; then to an application wide in-memory cache; next look to disk; then call to a service.

Fiddler and Proxies for Windows Phone

This article from last year is a great starting point for addressing issues either with proxies or for accessing network traffic from the Windows Phone emulator: http://blogs.msdn.com/b/wsdevsol/archive/2013/06/05/configure-the-windows-phone-8-emulator-to-work-with-fiddler.aspx

Probably the missing piece for most people is step 4:

In the command windows on the bottom left corner of Fiddler type: prefs set fiddler.network.proxy.registrationhostname HostName where HostName is the name of your desktop computer

Then you can simply navigate to :8888/FiddlerRoot.cer">http://<yourhostmachinename>:8888/FiddlerRoot.cer to install the Fiddler root certificate (useful for SSL debugging!)

Visual States in Windows Phone and Windows Applications using MvvmCross

I’m a big fan of using Visual States defined in Blend to be able to see all the different states that a page/view within your application would look like under different conditions. Most of these conditions are reflected in the state of your view model. However, there is no built in mechanism for data binding to a visual state. There are a number of different ways to tackle this problem, for example data triggers to control state changes. On technique we’ve used quite successfully is to simply bubble up appropriate state changed events from the view model, which in turn triggers a state change at the page level. In this post I’m going to walk you through how we’ve extended MvvmCross to include our own base view model and base page which allows us to trigger and track the state of the page.

We’ll start by defining an interface which will be implemented by our base view model. This includes the StateChanged event and methods for invoking a state change, ChangePageState, and querying the current state, CurrentState. You’ll notice that these methods take a type parameter, this is so that we can use an enumeration, rather than string literals to define our states.

public interface IStateAndTransitions
{
    event EventHandler<DualParameterEventArgs<string, bool>> StateChanged;
    void ChangePageState<T>(T stateName, bool useTransitions = true) where T : struct;
    T CurrentState<T>() where T : struct;
}

Next, we’ll implement the IStateAndTransitions interface in our BaseViewModel class. This class also inherits from MvxViewModel, bringing with it all the goodness of MvvmCross.

public class BaseViewModel : MvxViewModel, IStateAndTransitions
{
    public event EventHandler<DualParameterEventArgs<string, bool>> StateChanged;

    private readonly Dictionary<string, string> currentStates = new Dictionary<string, string>();
    public T CurrentState<T>() where T : struct
    {
        var current = currentStates.SafeDictionaryValue<string, string, string>(typeof(T).FullName);
        var tvalue = current.EnumParse<T>();
        return tvalue;
    }

    public void ChangePageState<T>(T stateName, bool useTransitions = true) where T : struct
    {
        var current = currentStates.SafeDictionaryValue<string, string, string>(typeof(T).FullName);
        var newState = stateName.ToString();
        if (string.IsNullOrWhiteSpace(current) || current != newState)
        {
            currentStates[typeof(T).FullName] = newState;
            StateChanged.SafeRaise(this, newState, useTransitions);
        }
    }
}

The last thing to do is to extend the MvxPhonePage to wire up an event handler for the StateChanged event. The event handler simply invokes the state change by calling GoToState on the VisualStateManager.

public class BasePhonePage : MvxPhonePage
{

    protected IStateAndTransitions StatesAndTransitionsViewModel
    {
        get
        {
            return DataContext as IStateAndTransitions;
        }
    }

    protected override void OnNavigatedTo(NavigationEventArgs e)
    {
        base.OnNavigatedTo(e);

        var satvm = StatesAndTransitionsViewModel;
        if (satvm != null)
        {
            satvm.StateChanged += ViewModelStateChanged;
        }
    }

    private void ViewModelStateChanged(object sender, DualParameterEventArgs<string, bool> e)
    {
        //var controlName = e.Parameter1;
        var stateName = e.Parameter1;
        var useTransitions = e.Parameter2;

        // Locate the control to change state of (use this Page if controlNAme is null)
        Control control = this;
        VisualStateManager.GoToState(control, stateName, useTransitions);
    }

    protected override void OnNavigatedFrom(NavigationEventArgs e)
    {
        var satvm = StatesAndTransitionsViewModel;
        if (satvm != null)
        {
            satvm.StateChanged -= ViewModelStateChanged;
        }

        base.OnNavigatedFrom(e);
    }
}

For completeness you’ll also need the parameter and dualparameter event args classes. These are used to make it easier to pass data values around when raising events.

public class ParameterEventArgs<T> : EventArgs
{
    public T Parameter1 { get; set; }

    public ParameterEventArgs(T parameter)
    {
        Parameter1 = parameter;
    }

  public static implicit operator ParameterEventArgs<T>(T parameter)
    {
        return new ParameterEventArgs<T>(parameter);
    }
}

public class DualParameterEventArgs<T1, T2> : ParameterEventArgs<T1>
{
    public T2 Parameter2 { get; set; }

    public DualParameterEventArgs(T1 parameter1, T2 parameter2):base(parameter1)
    {
        Parameter2 = parameter2;
    }

    public static implicit operator DualParameterEventArgs<T1, T2>(object[] parameters )
    {
        if(parameters==null || parameters.Length!=2) return null;
        return new DualParameterEventArgs<T1, T2>((T1)parameters[0], (T2)parameters[1]);
    }
}

Now, let’s see this in action in a view model, FirstViewModel:

public class FirstViewModel : BaseViewModel
{
    public enum FirstStates
    {
        Base,
        Loading,
        Loaded
    }

    public async Task LoadData()
    {
        ChangePageState(FirstStates.Loading);
        // Load some data (async to ensure no UI blocking)
        ChangePageState(FristStates.Loaded);
    }
}

Your page, FirstView, needs to inherit from BasePhonePage and have visual states called Loading and Loaded. The “Base” enumeration value is there just to represent the default state of the page. You should never have a state called “Base”, nor should you call ChangePageState with a value of Base. You can however, call CurrentState and compare the value to Base to see if a state has been set.

Hope this makes it easier for you to build your visual states in Blend.

Nokia Lumia Black Update and App Folder

From Nokia: http://conversations.nokia.com/2014/01/09/lumia-black-update/

The one thing that I thought was “cute” was the App Folder idea. If you recall clustering apps into folders/groups has been around since almost the beginning of guis (eg you could group programs in Windows 3.11). Which is why Apple was ridiculed when it claims that introducing folders was innovative.

I’m not saying App Folderis at all innovative but it can be a useful feature to the platform. Unfortunately it does require apis that aren’t available to third party developers to build this functionality which is why it had to wait for Microsoft or Nokia to build it. I do live the fact that it doesn’t require an OS refresh in order to get this app. I also like the fact that the images on the folder tile are big enough to see what’s actually in there, particularly with the wide tile. Here’s mine for games…..

image

Querying data from the Windows Phone and Windows Stores

We had a requirement today to query both the Windows Phone and Windows Stores for information about some of the apps we’ve been working on. Since both stores have a rich client interface it’s only natural that the store can be queried via a hidden pseudo api (“pseudo” because they’re more feed-like than a real api).

To work out how the api is structured the easiest thing to do is to setup Fiddler with SSL decoding and remote connections enabled on one computer and then on your Windows Phone and/or Windows 8 device you set the Fiddler computer to be the proxy. In order for this to work you’ll need to install the Fiddler certificate onto the device (Windows Phone installs the certificate correctly by default; Windows 8 you’ll need to put the certificate into the Trusted Root Certificate Authorities store for it to work).

Here’s what I pulled from my Windows Phone:

Application Info URL

http://marketplaceedgeservice.windowsphone.com/v8/catalog/apps/{app guid}?os=8.0.10211.0&cc=AU&lang=en-US

Replace “app guid” with the Guid for your application. You can find the Guid for your application by finding the application in the web version of the Windows Phone Store and then looking in the address bar.

Image URL

http://cdn.marketplaceimages.windowsphone.com/v8/images/{image guid}?hw=486577666&imagetype=icon_small

Replace “image guid” with the Guid for the image you want to retrieve. The image Guids are listed in the information returned from the application info URL.

 

Here’s what I pulled from my Windows 8 device:

Application Info URL

https://next-services.apps.microsoft.com/browse/6.3.9600-0/776/en-GB_en-AU.en-US.en/c/AU/cp/10005001/Apps/{app guid}

Replace “app guid” with the Guid for your application. You can find the Guid for your application by finding the application in the web version of the Windows Store and then looking in the address bar.

Image URL

http://wscont1.apps.microsoft.com/winstore/1.4x/{image path}

Replace “image path” with the relative path to the image that you want which can be found in the Application Info URL

Boosting Reviews of your Windows Phone Application using the MarketplaceReviewTask Launcher

One thing that so many developers forget is that reviews are a crucial element in driving the adoption of your application. Not only do a lot of developers forget to provide a link to submit a review within their application, they also don’t prompt the user to post a review. Here’s a simple suggestion that should help drive reviews:

- Make sure the user can navigate to the Windows Phone Store review page for your application from somewhere within your application

- Prompt the user to complete a review based on some algorithm eg:

         > After X days of using the app

         > After running the app X number of times

         > After successfully completing something within the app

The simplest way to navigate users to the review page is using the MarketplaceReviewTask:

MarketplaceReviewTask marketplaceReviewTask = new MarketplaceReviewTask();
marketplaceReviewTask.Show();

Windows Phone Dev Fusion

Some of the Windows Phone MVPs are putting together some awesome online content later this month

“Along with Christmas we have a little gift from the Windows Phone development community for you: The WPDev Fusion „New Year Edition“, supported by Microsoft and Nokia. This is an evolution of the Windows Phone Week from last october, where over 1500 developers participated in. But these events also have a few downsides: You have to be at a specific time at a specific place in conjunction with travel costs. Here actually WPDev Fusion comes into the game as this event is pure virtual. Relaxed from your couch you can join this global event on January 22nd.”

More info at http://winphonedev.de/2013/12/23/ankndigung-zu-wpdev-fusion-new-year-edition-announcing-wpdev-fusion-new-year-edition/

Windows Phone goes BIG with 1080p resolution

Windows Phone 8 applications will, out of the box, automatically scale on these high resolution devices. But what if you want to make use of this extra resolution, particularly on larger devices such as the Lumia 1520. Here are some links to some useful guidance on how you can take advantage of the extra space:

Taking Advantage of Large-Screen Windows Phones

Porting Existing Apps to large Screen Device

Simulate 1080p windows phone emulator

Windows Phone Application Testing

Here’s a couple of useful links on testing for Windows Phone applications:

Unit testing for Windows Phone apps

Options for publishing Windows Phone beta apps and testing in-app purchase

Nokia: Remote Device Access

One additional comment I would make about unit testing for Windows Phone is that unfortunately the tests written using a Visual Studio Windows Phone unit testing project can’t be executed (easily) as part of a Visual Studio Online automated build. The work around for this is to place most of your business logic in a Portable Class Library and to simply use a regular unit testing project to test the functionality. Of course, this isn’t as accurate as testing using either the emulator or a real device but it will give you some level of regression testing with each build (ideally after each check in).

Conditional Includes with Visual Studio Project Files

Often during development your application may be set to connect to a dev or test set of services. When you go to release your application you’ll then switch to point to the production or live set of services. A common way to do this is to define a constant which is the base url for the services and then use the DEBUG conditional compilation constant to control what the value of the constant is. For example

public static class Contants
{
#if DEBUG
    public const string BaseUrl = "
http://test.apiservice.com";
#else
    public const string BaseUrl = "
http://production.apiservice.com";
#endif
}

This is a simple but effective strategy to control which services are used based on build configuration. If you select a Debug build, you’ll connect to the test services; the Release build will connect to the production services. This strategy also keeps the differences between a debug and release build to a minimum, since all that is changing is the base url for the service. However, this simplicity can lead to some confusion as it can be hard to tell whether you’re using a debug or release build of an application.

One work around for this is to surface up the base url in the UI, for example in the About page, so that you can tell which version of the app is running. Another alternative is to customise the default tile for the application so that it is clear which build is installed. This can be done by dynamically switching between multiple image files during the build process.

Let’s start by creating our two live tiles (one for debug, one for release):

FlipCycleTileMedium FlipCycleTileMedium

Create the following folder structure in the solution folder:

\DefaultTiles
         \Debug
               FlipCycleTileMedium.png
         \Release
               FlipCycleTileMedium.png

Place the created images into the appropriate folder – note that they should have the same file name.

In Visual Studio, right-click on the project node and select “Unload Project”. Then right-click the project node again and select Edit. Locate where the live tile image is included eg:

<Content Include="Assets\Tiles\FlipCycleTileMedium.png">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>

And replace it with the following xml

<Content Include="..\DefaultTiles\$(Configuration)\FlipCycleTileMedium.png">
  <Link>Assets\Tiles\FlipCycleTileMedium.png</Link>
  <CopyToOutputDirectory>Always</CopyToOutputDirectory>
</Content>

This xml links in the appropriate file based on the $(Configuration) parameter. Save and reload the project. Now as you switch build configurations you’ll see that the appropriate live tile image is included. You can check this by either deploying the application to a device/emulator, or by checking the output folder where you’ll see the appropriate file appear after the build has completed.

App Generators: Windows Phone App Studio and Project Siena

With all the recent interest in app generators by Microsoft, I’m wondering whether there is going to be a run on app-kiddies (kick back to “script kiddies” who plagued the internet a decade or so ago): Application builders who don’t have a clue how to write an application but seem to be able to coble together a number of applications, that all look surprisingly similar, using generators.

The two app generators I’m referring to are:

Windows Phone App Studio

“Take your app from idea to Windows Phone in record time”

Microsoft Project Siena (Beta)

“Unleash your expertise and imagination”

Having checked out the capabilities of these generators I don’t feel that my job as a Windows platform developer is in jeopardy. In fact, I think these generators allow would-be app creators to get started with the basics. Once they hit the limitations of the tools, that’s when they can come to us to fill out the gaps. This is a great way to test a concept, or two, before over-investing in any particular idea.

Windows and Windows Phone app convergence

One of the things that is becoming apparent is that the convergence between Windows and Windows Phone applications it a hot topic. Developers often ask why we have two development platforms to target, where as iOS and Android only have the one. For example iOS you can build a single package which includes both iPad and iPhone versions of an application. This argument is of course completely flawed since we’re comparing apples and oranges. If you widen the scope to include Mac development then those in the Apple world also have to target two platforms. This argument doesn’t really apply to Android since it doesn’t really feature in the desktop space.

What we are seeing is that we can increasingly share resources between our Windows and Windows Phone applications. The continual evolution of Portable Class Libraries mean that we can build reusable libraries that will work without recompilation across both Windows and Windows Phone applications. In fact you can even use these libraries in your iOS and Android projects, assuming you’re using Xamarin as your cross platform approach.

Unfortunately all this discussion of convergence at an dev platform layer completely ignores what’s going on at the user experience level. The reality is that you don’t need technology convergence in order to build a consistent user experience across both platforms. What’s been interesting to watch is how Microsoft tries to converge the look of Windows and Windows Phone first party applications. Whilst  both interfaces are laced with the essence of Metro Modern UI, there are some significant differences between them.

Take for example the Hub/Panorama experience – Windows 8 didn’t have a control for this, where as Windows Phone has the Panorama control; Windows 8.1 now has the Hub control which makes it easier for developers to build a hub style experience. The Hub and Panorama controls aren’t the same eg the hub control typically has a hero pane, where as the panorama has a background image which has parallax scrolling.

If you look at some of the Microsoft applications, such as Bing News, you’ll see that they’ve taken UX convergence to the next level, attempting to minimize any difference between the platforms. Below you can see the Windows Phone Bing News app, followed by the Windows version.

1 of 6 2 of 6 3 of 6

 

Screen shot 1

The question you should be asking (and Microsoft should be answering) is whether you should be sticking to the standard Panorama look and feel, or should you be trying to match what Bing News is doing and aligning with the Windows Hub control?

3D Motion, a Bogus iOS7 Feature, implemented in 50 lines of code on Windows Phone 8

After playing with iOS7 for a little, I was curious about the new 3D effect they have going on the home screen. For those familiar with Windows Phone you’ll already be familiar with the parallax effect that is used within the Panorama control to give the idea of motion. So, I’m thinking it can’t be that hard to produce the same sort of effect using the gyroscope capability coupled with a simple render transform or two.

A few minutes later I’ve got the following code which produces a similar effect to what you’d see on iOS7:

Motion sensor = new Motion();
public MainPage()
{
    InitializeComponent();
 
    sensor.CurrentValueChanged += sensor_CurrentValueChanged;
    sensor.Start();
}
 
private ManualResetEvent waiter=new ManualResetEvent(false);
void sensor_CurrentValueChanged(object sender, 
     SensorReadingEventArgs<MotionReading> e)
{
    try
    {
        var pitch = e.SensorReading.Attitude.Pitch;
        var roll = e.SensorReading.Attitude.Roll;
 
        Dispatcher.BeginInvoke(() =>
            {
                var transform = B_Background.RenderTransform as CompositeTransform;
                var contentTransform = GD_Content.RenderTransform as CompositeTransform;
                    var newTrans =  24*roll*2/Math.PI;
                    var contentShift = 18 * roll * 2 / Math.PI;
                transform.TranslateX = 
                -Math.Max(Math.Min(newTrans, 50),-50);
                contentTransform.TranslateX = 
                Math.Max(Math.Min(contentShift, 12), -12); 
 
                newTrans = 48*pitch*2/Math.PI;
                contentShift = 36 * pitch * 2 / Math.PI;
                transform.TranslateY = 
                -Math.Max(Math.Min(newTrans, 50), -50);
                contentTransform.TranslateY = 
                Math.Max(Math.Min(contentShift, 12), -12); 
                waiter.Set();
            });
        waiter.WaitOne();
    }
    catch (Exception ex)
    {
        Debug.WriteLine(ex.Message);
    }
}

 

It’s not that easy to demonstrate this via a blog but in the following images you can see the slight displacement of the background and the foreground icons as the screen is rotated through different pitch and yaw values.

image image image

Full source:

TTF Font with Windows Phone 8

This is the story of a stubborn font (.ttf) that refused to work in a Windows Phone 8 application…. It all starts with a simple Windows Phone 7 application where the font works fine. Let’s just recall on how you can include a custom font within your application:

Option 1 – Build action = Content

- Add the TTF file (in this case Colonna.TTF, which is the Colonna MT Regular font) to your project by right-clicking the project in solution explorer and select Add > Existing Item. Select the TTF file and click OK

- Select the TTF file you just added and make sure the Build Action is set to Content (you can optionally set the Copy to Output Directory if you want but this actually isn’t required as the file will be copied regardless if it’s set to Content for a Windows Phone project)

image

Next, we just need to add a bit of XAML to display the font within our application:

<TextBlock Text="Test Text with Custom Font" 
                   FontFamily="Colonna.ttf#Colonna MT" />

 

It’s worth breaking the FontFamily attribute value into its parts. Before the # is the path to the TTF file. If you put the TTF file in a folder or in a different assembly you’ll need to adjust the path accordingly. After the # is the name of the font. This can be found by opening the TTF file from Windows Explorer using the default Windows Font Viewer:

image

 

Option 2 – Blend Embedded Font

An alternative is to get Blend to do the hard work for you. Switch to Blend (if you’re not already designing your application in Blend then you should be!) and select the TextBlock where you want to use the custom font. In the Properties window locate the Text property group (you can type “font” in the search box to reduce the list of properties). From the FontFamily dropdown, click on the Font Manager button:

image 

Select the font that you want to embed in your application, in this case Bradley Hand ITC, and click OK

image

You will see that this font has been added to a Fonts folder in the Projects window:

image

Now from the FontFamily dropdown you can select the font and you’ll notice that it has an icon next to it indicating that the Font has been added to the project.

image

An alternative is to select the font and then check the “Embed” checkbox in the Text group:

image

What’s interesting is that the syntax for using this font in the application is slightly different

<TextBlock Text="Test Text with Embedded Custom Font" 
                   FontFamily="/TestFont;component/Fonts/Fonts.zip#Bradley Hand ITC" />

By default Blend specifies the font family using an absolutely path. A relatively path will work just as well, for example:

<TextBlock Text="Test Text with Embedded Custom Font" 
           FontFamily="Fonts/Fonts.zip#Bradley Hand ITC" />

 

If you switch across to Visual Studio you’ll see that the TTF file has been included with a Build Action set to BlendEmbeddedFont.

image

Warning: it’s not enough to simply add a TTF file into your application and set the build action to BlendEmbeddedFont. In this scenario, where we embedded the font via Blend, some additional attributes were also set that you don’t see in the Properties window (these are not set when you simply change the Build Action to BlendEmbeddedFont and are required for the font to be correctly embedded).

<BlendEmbeddedFont Include="Fonts\BRADHITC.TTF">
      <IsSystemFont>True</IsSystemFont>
      <All>True</All>
      <AutoFill>True</AutoFill>
      <Uppercase>True</Uppercase>
      <Lowercase>True</Lowercase>
      <Numbers>True</Numbers>
      <Punctuation>True</Punctuation>
    </BlendEmbeddedFont>

 

 

Windows Phone 8 and the Stubborn Font

Both of the options presented in the previous section worked brilliant for my font in a Windows Phone 7 project. Unfortunately when I upgraded my application to Windows Phone 8 the font stopped rendering – the TextBlock elements would revert to using the default font.

 

Attempt 1: Adjusting legal rights for embedding

After talking with a few people about what the cause of the issue could be (ie not following options 1 or 2 above) it was suggested (thanks Vaughan from Bitrave) that it was font licensing issue. Apparently, which I didn’t realise there is a flag in the TTF file which indicates whether the font can be embedded or not. There are a couple of rudimentary tools out there that will allow you to tweak this (and yes, I have permissions from the font designer to do this!). The one I used was TTFEdit.

http://sourceforge.net/projects/ttfedit/

What astounded me was that this was a Java application…. which meant I needed to install the JRE… ummm, where do I get that again, oh, right, Java.com of course:

http://java.com/en/download/index.jsp

 

 

 

 

 

 

 

 

 

 

 

Do you think installing this is enough… no, because it doesn’t add itself to the path. I then had to add c:\Program Files (x86)\Java\jre7\bin to my path so it was accessible from my command prompt:

image

 

Ok, now we’re ready to run TTFEdit: Open a command prompt, navigate to the directory where you extracted TTFEdit (it comes as a zip file, so don’t forget to unblock it before extracting it), and execute “Run.cmd” – this will launch the UI:

- File > Open > Select your TTF file

- View > Show Advanced

image

- Select the OS/2 tab and look for the “Legal rights for embedding” field. Hover over the text box and you’ll see the tooltip that indicates possible values. You’ll notice that the Colonna MT has been set to 8 which means it can be embedded.

image

I’ve tried setting this attribute to all sorts of different values and it appears that Visual Studio, Blend and Windows Phone completely ignores them (ie with the Colonna font I couldn’t get it to not show the font). I’ve also tried adjusting my rogue font (default value was 0 which should afaik allow embedding anyhow) but couldn’t get it to render. Looks like this isn’t the answer!

 

Attempt 2: Issue with file format

Whilst it appears that Windows can open my rogue font and install it correctly, the font did originate from a Mac. A couple of the tools I tried for attempt 1 indicated that they could access or read one of the tables in the TTF file – this made me wonder whether there was something slightly screwy in the file which was causing Windows Phone not to handle the file correctly.

I found a GUI tool called BirdFont (http://birdfont.org/) which can be used to edit TTF files. Interestingly it’s also a Java application (I can’t recall the last time I used a Java application and now to have two in a day….).

I simply opened my TTF file, switched to the Menu tab, gave it a new name  and clicked Export.

image

This generated a new TTF which worked perfectly in my Windows Phone 8 application. I’m yet to work out exactly what the differences are but if we open both fonts in TTFEdit the OS/2 table version is different (and if you recall from earlier the OS/2 table version of the Colonna font was 1). I’d be interested to know exactly what the limitations of TTF font support on Windows Phone is but at least I have a work around for when I do come across a font that doesn’t want to play ball.

For reference, here’s the link to what I could find on MSDN that talks about font support for Windows Phone ( http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh202920(v=vs.105).aspx#BKMK_FontEncoding)

Downloading data using a Portable Class Library for Windows Phone and Windows 8

We’re going to take a bit of a side trip before we return to the data binding series. In this post we’re going to look at how to download data from a remote service. We’ll be using a json feed but this post should give you enough background to be able to download content from any service. There are two aspects to this post that I want to highlight:

1) We’ll be writing all the downloading and deserialization logic in a portable class library, which means it can be used across any number of target platforms.

2) We’ll be using the async-await pattern, which will greatly improve the readability of our code. I’ll illustrate the old way of downloading data for a point of reference only. I’d highly recommend getting on the asynchronous bandwagon “why await when you can async!”

We’ll be accessing a sample OData feed which is available via odata.org (http://services.odata.org/V3/OData/OData.svc/Products), which lists a number of products. You can either use the OData API Explorer (http://services.odata.org/ODataAPIExplorer/ODataAPIExplorer.html) or other tools such as Fiddler which will allow you to send http requests. The following image illustrates the formatted json response from a call to the Products url.

image

Since we want to run this across both Windows Phone and Windows I’ve got a solution with both a Windows Phone and a Windows 8 application. To this solution we’ll add a new Portable Class Library.

image 

When prompted I tweak the target frameworks – I’m not particularly interested in being limited by previous frameworks so I uncheck support for Silverlight and for Windows Phone 7.x.

image

 

Now to write some code – we’ll start with the old school way of downloading data. The following method creates a WebRequest. In order to get json data back from the OData site we need to specify the application/json Accept header. Calling BeginGetResponse invokes the GET request to retrieve data. The argument to this method is an anonymous method which is invoked when the request returns. After decoding the response, the callback passed into the DownloadJsonTheOldWay method is invoked.

public static void DownloadJsonTheOldWay<TData>
        (string url,Action<TData> callback)
{
        var req = WebRequest.CreateHttp(url);
        req.Accept = "application/json";
        req.BeginGetResponse(cb =>
        {
            var cbreq = cb.AsyncState as WebRequest;
            var resp = cbreq.EndGetResponse(cb);
            var serializer = new DataContractJsonSerializer(typeof(TData));
            using (var strm = resp.GetResponseStream())
            {
                var result = (TData)serializer.ReadObject(strm);
                callback(result);
            }
                    
        }, req);
}

 

Invoking this from our applications looks like:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    base.OnNavigatedTo(e);
    Helper.DownloadJsonTheOldWay<ProductData>
       ("http://services.odata.org/V3/OData/OData.svc/Products",DataFound);
}
 
private void DataFound(ProductData data)
{
    Debug.WriteLine(data!=null);
}

This is less than ideal as it means our application code is jumping around – easy to see in this isolated example but once our application grows in complexity it’ll be much harder to follow the flow of execution. Let’s try to improve this so that our code doesn’t jump around so much:

public static Task<TData> DownloadJsonTheOldWay<TData>(string url)
{
        var req = WebRequest.CreateHttp(url);
        req.Accept = "application/json";
        TData result = default(TData);
        var waiter = new ManualResetEvent(false);
        req.BeginGetResponse(cb =>
        {
            var cbreq = cb.AsyncState as WebRequest;
            var resp = cbreq.EndGetResponse(cb);
            var serializer = new DataContractJsonSerializer(typeof(TData));
            using (var strm = resp.GetResponseStream())
            {
                result = (TData)serializer.ReadObject(strm);
            }
            waiter.Set();
        }, req);
        waiter.WaitOne();
        return result;
}

 

In this code we’re using a ManualResetEvent to block the method until the request returns. Unfortunately if this method is invoked from the UI thread it will block that thread until the request returns – this is fine for Windows 8 but Windows Phone uses the UI thread as part of invoking web requests. The net effect is that this code will block indefinitely on Windows Phone.

Right, so we need to find a way to prevent the UI thread from being blocked. This can be done by invoking the previous attempt on a different thread. In fact we can leverage the async-await pattern:

public async static Task<TData> DownloadJsonTheOldWay<TData>(string url)
{
    return await Task.Run(() =>
        {
            var req = WebRequest.CreateHttp(url);
            req.Accept = "application/json";
            TData result = default(TData);
            var waiter = new ManualResetEvent(false);
            req.BeginGetResponse(cb =>
                {
                    var cbreq = cb.AsyncState as WebRequest;
                    var resp = cbreq.EndGetResponse(cb);
                    var serializer = new DataContractJsonSerializer(typeof(TData));
                    using (var strm = resp.GetResponseStream())
                    {
                        result = (TData)serializer.ReadObject(strm);
                    }
                    waiter.Set();
                }, req);
            waiter.WaitOne();
            return result;
        });
}

Now, the code in our application looks much cleaner:

protected async override void OnNavigatedTo(NavigationEventArgs e)
{
    base.OnNavigatedTo(e);
 
        var data = await Helper.DownloadJsonTheOldWay<ProductData>
                        ("http://services.odata.org/V3/OData/OData.svc/Products");
        Debug.WriteLine(data != null);
}

 

In fact, the pattern of BeginXXX, EndXXX is quite common amongst traditional .NET apis. So much so that as part of the asynchronous programming library there is a Factory method which can be used to simplify this code somewhat:

public async static Task<TData> DownloadJson<TData>(string url)
{
    var req = WebRequest.CreateHttp(url);
    req.Accept = "application/json";
    var resp = await Task.Factory.FromAsync<WebResponse>
                    (req.BeginGetResponse, req.EndGetResponse, null);
    var serializer = new DataContractJsonSerializer(typeof(TData));
    using (var strm = resp.GetResponseStream())
    {
        var data = (TData)serializer.ReadObject(strm);
        return data;
    }
}

 

The Factory.FromAsync brings together the BeginGetResponse and EndGetResponse into a single line to return the response of the request. This works well on Windows 8. However, on Windows Phone an exception is thrown as read stream buffering needs to be enabled. This is done by adding “req.AllowReadStreamBuffering = true;” before invoking the request. Unfortunately whilst adding this means the code works for Windows Phone, it then breaks for Windows 8.

The solution, and the last piece to our code, is some conditional logic to determine if the code is being invoked on Windows RT (ie Windows 8) or not. If it is, then read stream buffering is not enabled.

private static bool IsWinRT { get; set; }
static Helper ()
{
    var wrt = Type.GetType("Windows.ApplicationModel.DesignMode, Windows, ContentType=WindowsRuntime");
    if (wrt != null)
    {
        IsWinRT = true;
    }
 
}
public async static Task<TData> DownloadJson<TData>(string url)
{
    var req = WebRequest.CreateHttp(url);
    if (!IsWinRT)
    {
        req.AllowReadStreamBuffering = true;
    }
    req.Accept = "application/json";
    var resp = await Task.Factory.FromAsync<WebResponse>
              (req.BeginGetResponse, req.EndGetResponse, null);
    var serializer = new DataContractJsonSerializer(typeof(TData));
    using (var strm = resp.GetResponseStream())
    {
        var data = (TData)serializer.ReadObject(strm);
        return data;
    }
}

We can invoke this method from either Windows Phone or Windows 8, giving us a single line way to download and decode json from any remote uri.

image

Introduction To Data Binding for Windows and Windows Phone (part 2)

<< Introduction To Data Binding for Windows and Windows Phone (part 1)

In the first part of this series we introduced the concept of data binding and how it can be used to associated an attribute on a visual element with a property on a data entity. The question we left unanswered is “why should we use data binding?”. There are countless answers to this question and rather than bore you with them I want to illustrate some of neat things you can do with a combination of data binding and the designer experience in both Visual Studio and Blend.

Example Requirements: Display a simple list of people; each person is represented by a Name and an Age; the list should display both Name and Age; when the user selects an item in the list, a MessageBox should be displayed indicating which person was selected.

We’re going to need a Person class:

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
}

and an array of people:

var people = new[]
    {
        new Person {Name = "Fred", Age = 29},
        new Person {Name = "Matilda", Age = 13},
        new Person {Name = "Jane", Age = 33}
    };

We’ll create a ListBox on our page (we’ve added the SelectionChanged event handler at this point too so we don’t need to come back later…)

<Grid>
    <ListBox x:Name="PeopleList"
                SelectionChanged="PersonSelectionChanged" />
</Grid>

Let’s start off doing this the hard way, without data binding. We need to add each person in the people array into the ListBox:

foreach (var person in people)
{
    PeopleList.Items.Add(person);
}

Which displays as the following – we have the right number of rows in the ListBox but not the desired look.

image

A quick and dirty solution is to add DisplayMemberPath="Name" to the ListBox declaration. This yields a minor improvement where we can at least see the person’s name.

 image

In order to style the list any further for each person we need to create a ListBoxItem and child elements to represent the visual layout we want.

var textStyle = Application.Current.Resources["PhoneTextNormalStyle"] as Style;
foreach (var person in people)
{
    var lbi = new ListBoxItem();
    var sp = new StackPanel { 
          Orientation = System.Windows.Controls.Orientation.Horizontal };
    sp.Children.Add(new TextBlock { 
                      Text = person.Age.ToString(), 
                      Style = textStyle });
    sp.Children.Add(new TextBlock { 
                      Text = person.Name, 
                      Style = textStyle });
    lbi.Content = sp;
    PeopleList.Items.Add(lbi);
}

The structure for each person in the list is a horizontal StackPanel containing two TextBlock elements, displaying the Age and Name of the person. We’ve used one of the built in styles, PhoneTextNormalStyle, to try to improve the appearance of the TextBlocks.

image

Now, lets complete the example by writing the event handler which is going to display the name of the person that the user has selected in the list:

private void PersonSelectionChanged(object sender, 
                   SelectionChangedEventArgs e) {
            var lst = sender as ListBox;
            var lbi = lst.SelectedItem as ListBoxItem;
            .... some nasty code to get the Name out....

At this point we figure we have a problem – we can get the Name and Age values by looking for the appropriate TextBlocks and extracting the Text property. However, this doesn’t give us a reference to the Person object…. in fact the original person objects are now out of scope and no longer exist. We need a way to pass the Person object along for the ride. Let’s simply set the Tag property on the ListBoxItem (ie lbi.Tag = person; ). Completing the code we have:

private void PersonSelectionChanged(object sender, 
                   SelectionChangedEventArgs e)
{
    var lst = sender as ListBox;
    var lbi = lst.SelectedItem as ListBoxItem;
    var person = lbi.Tag as Person;
    MessageBox.Show(person.Name);
}

 

This is an incredibly simple, contrived, example and yet we’ve had to write quite a lot of code and do some hacky things in order to pass data around. Now imagine the scenario that the requirements change and that the order of the Age and Name should be reversed, or a vertical StackPanel should be used, or another property is added to the Person class which needs to be displayed. In this example it wouldn’t be that hard to find the line(s) of code to change but you can imagine that in a large complex system it would be a nightmare to find the write code, visualise what the item will look like and make the appropriate change. Wouldn’t it be nice if there was a design tool to help?

The good news is that by using data binding you:

a) get to reduce and simplify the code you write

b) get a design experience for constructing the user experience

At this point I’m going to step into Blend as I prefer its design experience over the limited designer in Visual Studio. Whilst most of the tool windows and the design surface are now shared between the products, there are still some design aspects that Blend has which Visual Studio doesn’t (such as being able to design Visual States). I also find that by switching tools I’m making a mental shift from developer mode to designer mode.

Open your solution in Blend.

The first thing we’re going to do is to create some sample data with the same shape as the data we need to display. When I say shape I’m referring to the object hierarchy and the properties on the classes. In this example we have an array of Person objects, each one with an Age (Number) and Name (String). So, we need to create design time data which has a collection of entities, each with an attribute called Age which is a Number, and an attribute called Name which is a String.

From the Data windows, select New Sample Data

image

Give your sample data a name, and hit OK (we’ll come back to the “enable sample data” option a little later).

image

In the Data window you can now adjust the names of the properties: Change Collection to PersonCollection, Property1 to Name and Property 2 to Age, and change the Type of Age to Number.

image

Drag the PersonCollection node from the Data window across onto the PeopleList node on the Obejcts and Timeline window (note the help prompt that appears indicating what’s about to happen).

image

When you let the mouse go, you’ll see a new ListBox appear on the screen full of the sample data you just created.

image

Now all you need to do is to change the layout according to the requirements. Right-click the PeopleList node in the Objects and Timeline window and select Edit Additional Template; Edit Generated Items (ItemTemplate); Edit Current.

image

You’re now in template editing mode where you can modify the layout of each item in the list (you can think of the ItemTemplate being a cookie cutter or a mould for each item that will appear in the list).

Select the StackPanel and change the orientation to Horizontal via the Properties window.

image

Right-click on each TextBlock in turn and select Edit Style; Apply Resource; PhoneTextNormalStyle

image

Your layout, at design time, should look very similar to the desired output.

image

You can run the application to verify how it appears but you’ll notice that it is still displaying the design time data. We need to firstly disable design time data, at runtime, and secondly we need to actually wire up the real data.

To disable design time data at runtime, from the Data window, click the icon alongside the PeopleDataSource and uncheck the Enable When Running Application. Now when you run the application you won’t see the design time data.

image

In order to wire up data we need to take a closer look at what Blend did for us when we dragged across the design time data. Looking at the XAML you’ll see that the ItemTemplate and ItemsSource attributes have been specified. In actual fact, what you may not have realised is that you have just been adjusting the ItemTemplate attribute value when modifying the layout for each item. 

<Grid>
    <ListBox x:Name="PeopleList"
                SelectionChanged="PersonSelectionChanged"
                ItemTemplate="{StaticResource PersonCollectionItemTemplate}"
                ItemsSource="{Binding PersonCollection}" />
</Grid>

It’s the ItemsSource property that we’re particularly interested in – this is what determines where the items in the ListBox are going to be sourced from. This has been data bound to the PersonCollection property on the current DataContext (recall this from my previous post).

There is no DataContext explicitly set on the ListBox. So, the simplest solution to wiring up real data is to set the DataContext on the ListBox to be an entity that has a PersonCollection property which returns the Person entities which should be added to the ListBox. For this we’ll create a MainPageData class (this is kind of the prelude to a ViewModel which we’ll discuss in the context of the MVVM design pattern).

public class MainPageData
{
    public Person[] PersonCollection { get; set; }
}

 

Now all we need to do is to create an instance of our MainPageData and set it as the DataContext on the ListBox.

PeopleList.DataContext = new MainPageData 
                          {PersonCollection = people};

 

Furthermore, our event handler code can be simplified because the SelectedItem property now returns the actual data item (ie a Person) instead of a generic ListBoxItem.

private void PersonSelectionChanged
          (object sender, SelectionChangedEventArgs e)
{
    var lst = sender as ListBox;
    var person = lst.SelectedItem as Person;
    MessageBox.Show(person.Name);
}

 

You might be thinking “how is our data being wired up to the layout we defined in the designer for each item in the list?” The answer is in the ItemTemplate attribute of the ListBox. This references a static resource, PersonCollectionItemTemplate, which is defined elsewhere on the same page:

<phone:PhoneApplicationPage.Resources>
    <DataTemplate x:Key="PersonCollectionItemTemplate">
        <StackPanel Orientation="Horizontal">
            <TextBlock Text="{Binding Age}"
                        Style="{StaticResource PhoneTextNormalStyle}" />
            <TextBlock Text="{Binding Name}"
                        Style="{StaticResource PhoneTextNormalStyle}" />
        </StackPanel>
    </DataTemplate>
</phone:PhoneApplicationPage.Resources>

Here we can again see that the structure of each item in the list is a horizontal StackPanel with two TextBlock elements with Style set to PhoneTextNormalStyle. You’ll also notice that the Text attribute for each TextBlock has been data bound to the Age and Name properties respectively. Whilst no DataContext is explicitly defined for either TextBlock, nor the StackPanel, the DataContext is implicitly set to be the item in the list that is being rendered. In other words, when a Person object is being displayed in the list, this template is used to stamp out the appropriate visual elements. The DataContext for each element in the template is set to the Person object, and the data binding expression establishes an association between the Text attributes and the Age and Name properties on the Person object.

The upshot is that we have significant less C# code for wiring up the ListBox data and, other than setting the DataContext on the ListBox, it doesn’t manipulate the user interface. We also have a design time experience which will allow us to easily go back and tweak the layout of the ListBox items at any time in the future.

Hopefully you’ve started to see the power of data binding. This is just the tip of the iceberg and we’ll go into more detail in coming posts.

Introduction To Data Binding for Windows and Windows Phone (part 1)

Introduction To Data Binding for Windows and Windows Phone (part 2) >>

Given how long Microsoft has been using XAML in one shape or another across a range of technologies (WPF, Silverlight, Windows Phone, XBox, Windows 8) it still surprises me how often I get asked about data binding. In this series we’re going to go back to basics and take a look at how to use data binding within you Window 8 and Windows Phone application. For the most part I’ll focus on Windows Phone but data binding across these platforms is relatively similar, so a lot of the concepts will carry across without me having to give multiple examples. Additionally, most of these concepts will apply equally well to data binding in Silverlight or WPF.

There are a couple of questions that we need to address:

- What is data binding?

- Why do we need data binding?

Let’s address the first question in this post by walking through an example. On our page we have two TextBlock elements that display the application title and the page name. These are illustrated with static placeholder text values (we’ll discuss design time data in a later post), which will be replaced with the actual values when the application is run.

image 

<StackPanel x:Name="TitlePanel">
    <TextBlock x:Name="ApplicationTitle" Text="MY APPLICATION" />    
    <TextBlock x:Name="PageTitle" Text="page name" />
</StackPanel>

Without data binding in order to update the Text property on the TextBlock elements you would have see code like this:

ApplicationTitle.Text = "DATA BINDING ROCKS!";
PageTitle.Text = "simple data binding";

Now, let’s do the same thing with data binding. Firstly, the XAML:

<StackPanel x:Name="TitlePanel" >
    <TextBlock x:Name="ApplicationTitle" Text="{Binding}" />
    <TextBlock x:Name="PageTitle" Text="{Binding}" />
</StackPanel>
 

Next, the code:

ApplicationTitle.DataContext = "DATA BINDING ROCKS!";
PageTitle.DataContext = "simple data binding";

If you look at the XAML instead of setting the Text property on the TextBlock elements to an explicit value, the attribute value is wrapped in { } – this essentially means that the value needs to be calculated some how (another typical usage of the { } value is for referencing a static resource). In this case the calculation is to create the data binding relationship between the Text property on the TextBlock and whatever is set as the current DataContext on the TextBlock. When we then set the DataContext on the TextBlock element it flows down into the Text property.

image

Where data binding starts to get more interesting is when you set the DataContext to be a more complex object. For example we might have a PageInfo class which contains the application title and page name:

var pi = new PageInfo
    {
        ApplicationTitle = "DATA BINDING ROCKS!",
        PageTitle = "simple data binding"
    };
 
ApplicationTitle.DataContext = pi;
PageTitle.DataContext = pi;

In this case we’re setting the DataContext on both TextBlock elements to be the PageInfo instance. When we run this what we see is that the data binding framework has literally just called “ToString()” on the object, which by default returns the type name as we can see in this image.

image

This isn’t what we want! What we want is that the first TextBlock should show the ApplicationTitle property and the second should show the PageTitle property. To do this we use the Path attribute on the data binding expression:

<StackPanel x:Name="TitlePanel" >
    <TextBlock x:Name="ApplicationTitle"
                Text="{Binding Path=ApplicationTitle}" />
    <TextBlock x:Name="PageTitle"
                Text="{Binding PageTitle}" />
</StackPanel>

In the second TextBlock the  “Path=” has been omitted to illustrate the shorthand way to specify the Path attribute. In both cases the binding expression is setting up a data binding relationship between the Text property on the TextBlock with the ApplicationTitle (or PageTitle) property on the current DataContext, which in this case is an instance of the PageInfo class.

An interesting aspect of the DataContext property on a UIElement is that by default it is inherited from its parent element. So for example in our scenario both TextBlock elements are situated within a StackPanel (ie the TitlePanel). By default (ie if the DataContext isn’t explicitly set on the TextBlock) they will both inherit the DataContext of the StackPanel. This means we could reduce our code to:

var pi = new PageInfo
    {
        ApplicationTitle = "DATA BINDING ROCKS!",
        PageTitle = "simple data binding"
    };
 
TitlePanel.DataContext = pi;

(At this point we can also remove the x:Name attribute on both TextBlock elements as they are no longer required)

Let’s just confirm our understanding of this:

- The  “{Binding ApplicationTitle}” expression is shorthand for  “{Binding Path=ApplicationTitle}”

- Text=“{Binding ApplicationTitle” sets up a binding relationship between the Text property on the TextBlock with the ApplicationTitle on the current DataContext

- The DataContext of the TextBlock is inherited from its parent element, the TitlePanel StackPanel.

- We’re explicitly setting the DataContext on the TitlePanel, allowing it to be inherited by the TextBlock elements.

An alternative would be to set the DataContext on the entire page:

var pi = new PageInfo
    {
        ApplicationTitle = "DATA BINDING ROCKS!",
        PageTitle = "simple data binding"
    };
 
this.DataContext = pi;

 

In this case our code is being executed in the context of the page, so the “this” is the page and so we’re setting the DataContext on the page and allowing it to flow down to every element on the page.

The answer to the first question, “what is data binding?”, is that it’s about establishing an association between an attribute on a visual element with a data entity, or a property on a data entity. As we’ll see over the coming posts, data binding allows to separate the logic of our application from the way it is presented on the screen. This not only allows for cleaner and more manageable code, it also allows developers and designers to work independently on the same application.

In the next post we’ll look at why you should be using data binding and the saving it offers to application developers.

Some great SQLite for Windows Phone posts

SQLite WinRT

SQLite WinRT wrapper for Windows Phone

http://sqlwinrt.codeplex.com/

SQLite-WinRT: Database programming on Windows Phone and Windows 8

A new SQLite wrapper for Windows Phone 8 and Windows 8 – The basics

A new SQLite wrapper for Windows Phone 8 and Windows 8 – Relationships

 

SQLite-net

Working with SQLite in Windows Phone 8: a sqlite-net version for mobile

How to use SQLite in Windows Phone

Using the SQLite database engine with Windows Phone 8 apps

---- warning: self promption ----

Windows (RT and Phone) and Sqlite (Part 1)
Windows (RT and Phone) and Sqlite (Part 2)
Windows (RT and Phone) and Sqlite (Part 3)
Windows (RT and Phone) and Sqlite (Part 4)

Windows Azure Mobile Service to SQLite Data Sync for Windows Phone and Windows RT with Portable Class Libraries

Windows Azure Mobile Service to SQLite Data Sync for Windows Phone and Windows RT with Portable Class Libraries - Conflicts

Windows Azure Mobile Service to SQLite Data Sync for Windows Phone and Windows RT with Portable Class Libraries - Conflicts

In my previous post, Windows Azure Mobile Service to SQLite Data Sync…, I covered a simple framework for synchronising entities between Windows Azure Mobile Service (WAMS) and SQLite. Anyone familiar with synchronisation logic will of course have scoffed at this framework concluding that I haven’t dealt with cases where there are synchronisation conflicts, and they’d be correct. Well in actual fact I have: I assumed an optimistic resolution policy which states that the last update is the correct one to take. In this post I’ll cover a better approach to conflict resolution.

For the benefit of those who haven’t had to deal with synchronisation logic in the past, one of the common conflict scenarios is as follows:

- Users A and B both synchronise the same set of data so they both have local copies of the data, including a Person record: Person {Name = Jane, Age = 25}

- User A makes a change to the record: Person {Name = Jane, Age = 32}

- User B makes a change to the record:  Person {Name = Jane, Age = 30}

- User A synchronises with WAMS first, updating the server record to Person {Name = Jane, Age = 30}

- User B attempts to synchronise with WAMS

Current Scenario:

Under the current scenario the server record gets pulled down, effectively overwriting the record User B has updated

This assumes that User A’s update is correct, even though it was done before that of User B, just because User A synchronised before User B.

Alternate Scenario:

When User B attempts to synchronise, WAMS should reject the change, indicating that the record has changed since the last time User B synchronised. It should also return the current record, allowing User B to determine what the correct record is.

The question now becomes how do we extend the synchronisation logic presented in the previous post, to deal with this scenario.

WAMS 

The first step is to adjust WAMS to prevent updates to records where the data has changed since the last synchronisation. Note, we don’t need to handle inserts, since they are by definition unique (although it is possible that both User A and User B entered the same new record, they are unique and its up to the individual application to allow for duplicate records to be combined somehow).

When updated records are sent to WAMS the LastUpdated property is the same as when that record was last retrieved from WAMS (the LocalLastUpdated field is used to track records that have changed locally). As such, in the update script in WAMS it is possible to detect whether the record has been updated since the LastUpdated time. If it has we’ll return a 409 Conflict error, as per the following script.

function update(item, user, request) {
        console.log('Find existing entity with Id '+ item.id);
        var personTable = tables.getTable('Person');
    
        personTable.where({
            id: item.id
        }).read({
            success: checkLastUpdated,
            error: checkFailed
        });
 
    function checkLastUpdated(results) {
        if (results.length > 0) {
            console.log('Entity Id ' + results[0].id);
            if(results[0].LastUpdated>item.LastUpdated){
                console.log('Conflict found, not updating record');
                request.respond(statusCodes.CONFLICT,
                   "Entity has changed since last synchronisation");
            }
            else {
                console.log('No conflict, updating record');
                item.LastUpdated=new Date();
                request.execute();
            }
        }
        else {
            console.log('Entity search found no records');
            request.respond(statusCodes.NOT_FOUND,"Entity not found");
        }
    }
 
    function checkFailed()
    {
        console.log('Entity search failed');
        request.respond(statusCodes.NOT_FOUND,"Entity not found");
    }
}

 

If we run the application on two devices we can generate this conflict by synchronising both application instances. Changing the same record on both devices, synchronising one, and then synchronising the second. Note: The client side logic in part caters for this already by downloading changes from the server before uploading the client changes. If you jump over this in the debugger on the second client, you can see the 404 error that is raised when the conflict is detected:

image

If you check out the logs on WAMS you’ll see the output from the console.log statements that were in the update script:

image

 

Synchronisation Logic

There are two parts where we need to add conflict resolution:

- When server changes are downloaded – currently the updates from User A would be synchronised to the device, overwriting the changes from User B

- When local changes are uploaded – any conflicts with server records will result in a 409 failure.

 

Server Changes

To handle server changes we’ll add logic which will detect whether any of the downloaded changes conflict with any of the pending local changes. If there is a conflict, we need to store the downloaded record, alongside the local record, so that the user can choose which is the correct record. In this case we’re assigning the downloaded record a negative Id starting at –1000 (ie ConflictMarkerValue = –1). Whilst this limits us to 1000 new records (remember we assign new records a negative Id starting at –1) it means that we can effectively use the same table to store new, existing and conflict records.

// Check for update conflicts
var conflict = (from delta in updatedentities
                where delta.Id == entity.Id
                select delta).FirstOrDefault();
if (conflict != null)
{
    conflictsFound = true;
    var id = ConflictMarkerValue - entity.Id;
    var existing = await (from x in con.Table<TEntity>()
                    where x.Id == id
                    select x).FirstOrDefaultAsync();
    entity.Id = id;
    if (existing != null)
    {
                        
        await con.UpdateAsync(entity);
    }
    else
    {
        await con.InsertAsync(entity);
    }
    continue;
}

 

You’ll also note that we set the conflictsFound flag to true. After iterating through all the downloaded records, if conflictsFound is true, the Sync method exits, returning a completed value of false – this is because we don’t want to upload any local records until the downloaded conflicts have been resolved. This will actually cover us with the second part where a 409 error gets returned but we’ll come to that in a minute.

If synchronisation doesn’t complete correctly we’ll need a mechanism for the user to iterate through the records that are in conflict and determine which record is correct.

public async Task<List<Conflict<TEntity>>> RetrieveConflicts<TEntity>()
    where TEntity : class, ISyncableEntity, new()
{
    var con = await Connect();
    // Retrieve the list of conflicted local entities
    var updatedentities = await (from remote in con.Table<TEntity>()
                                    where remote.Id <ConflictMarkerValue
                                    select remote).ToListAsync();
    var list = new List<Conflict<TEntity>>();
    foreach (var remote in updatedentities)
    {
        var id = -(remote.Id - ConflictMarkerValue);
        var pair = await (from local in con.Table<TEntity>()
                            where local.Id == id && 
                                      local.Id>ConflictMarkerValue
                            select local).FirstOrDefaultAsync();
        list.Add(new Conflict<TEntity>{Local = pair, Remote = remote});
    }
    return list;
}

 

The list of conflicts can then be presented to the user, allowing them to make a decision as to which record they wish to keep:

image

When the user clicks the Accept Local or Accept Remote (clearly not a production-ready UX!) the ResolveConflict method is called:

public async Task ResolveConflict<TEntity>(Conflict<TEntity> conflict)
    where TEntity : class, ISyncableEntity, new()
{
    if(!conflict.ResolveLocal.HasValue)
         throw new Exception("Conflict not resolved");
 
    var con = await Connect();
            
    // Make sure we delete the conflicted record
    await con.DeleteAsync(conflict.Remote);
 
    if (conflict.ResolveLocal.Value)
    {
        conflict.Local.LastUpdated = conflict.Remote.LastUpdated;
        await con.UpdateAsync(conflict.Local);
    }
    else
    {
        conflict.Remote.LocalLastUpdated = DateTime.MaxValue;
        conflict.Remote.Id = conflict.Local.Id;
        await con.UpdateAsync(conflict.Remote);
    }
}

If the user selects the local record to keep, then we simply update the LastUpdated value to when the records was last retrieved (ie when the conflict was discovered). If the user selects to keep the remote record, we simply overwrite the existing record with the remote record. Either way the changes are currently local only, which means we still need to force a Sync in order for those changes to propagate back to the server.

 

Local Changes

If there is a failure whilst uploading local changes to do with a conflict then the server will have returned a 409 Conflict. This error needs to be detected and the conflict resolved. However, when the server returns a 409 it doesn’t return the current server value. As such, we actually need to force another synchronisation in order to download the conflicting records (see previous section). To do this, we simply need to call Sync again!

catch (MobileServiceInvalidOperationException ex)
{
    if(ex.Response.StatusCode == HttpStatusCode.Conflict)
    {
        syncAgain = true;
    }
}
 
// Try sync again - this should retrieve conflicts
if (syncAgain)
{
    return await Sync<TEntity>();
}

These additions will help reduce any issues with conflicts. There are still some areas of weakness, for example the server validation isn’t carried out in a transaction, allowing for a write in between the read and write logic.

Windows Azure Mobile Service to SQLite Data Sync for Windows Phone and Windows RT with Portable Class Libraries

Following my 4 part series on using two different forms of SQLite across Windows Phone and Windows RT I thought I’d take a couple of hours to see how hard it would be to build a generic synchronisation framework that would allow me to synchronise data between SQLite and a Windows Azure Mobile Service (WAMS). Of course as I want it to work across both Windows Phone and Windows RT I want to make sure all my logic is contained within a Portable Class Library (PCL) – this is initially made possible by the awesome support the WAMS has for PCL. If you haven’t already read my previous posts on SQLite, here a summary list:

Windows (RT and Phone) and Sqlite (Part 1)
Windows (RT and Phone) and Sqlite (Part 2)
Windows (RT and Phone) and Sqlite (Part 3)
Windows (RT and Phone) and Sqlite (Part 4)

Now I apologise in advance, synchronisation is not simple, which may make this post long and hard to follow. I’m also certain that since I wrote this logic in the space of a couple of hours, I’m sure there are bugs I haven’t polished out – the idea here is to give you a heads up on how easily you can write this logic yourself.

We’ll start with some basics:

INotifyPropertyChanged

Since I want my entities to be bindable, and be able to update the UI, all my entities will need to implement INotifiyPropertyChanged. Rather than code this into each entity I, like many others, have a base class that implements this interface and exposes a helper method OnPropertyChanged which can be called when a property is changed.

public class NotifyBase : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler PropertyChanged;
    protected virtual void OnPropertyChanged
                    ([CallerMemberName] string propertyName = null)
    {
        PropertyChangedEventHandler handler = PropertyChanged;
        if (handler != null) 
            handler(this, new PropertyChangedEventArgs(propertyName));
    }
}

 

ISyncableEntity

Let’s start with what this interface looks like:

public interface ISyncableEntity
{
    int Id { get; set; }
    bool IsDeleted { get; set; }
    DateTime LastUpdated { get; set; }
 
    DateTime LocalLastUpdated { get; set; }
}

All our entities are going to need to implement this interface because it exposes the minimal set of properties we need in order to do bi-directional synchronisation. By this I mean be able to push all local changes (insert, update, delete) up to WAMS, as well as receive updates back from WAMS (insert, update and delete).

WAMS uses an int as the primary key for all entities. This makes change tracking a little hard as you need to use negative ids to track new entities.

If you’re doing bi-directional synchronisation across any number of clients you need to do logical, not real deletes. This means that all entities will need an IsDeleted flag so that you can a) track local deletes and push them to WAMS before actually removing the local entity and b) so that you can pull a list of deleted entities from WAMS so that they can be removed locally.

The LastUpdated field is used to track when the entity was last updated server-side. Golden rule of synchronisation is never trust the client apps. The LocalLastUpdated field is used to track local updates (ie which entities have been modified) and is not synchronised to WAMS

 

BaseEntity

Rather than having to implement all those properties on each entity I added a BaseEntity which has these properties.

[DataContract]
public class BaseEntity : NotifyBase, ISyncableEntity
{
    [PrimaryKey,DataMember]
    public int Id { get; set; }
 
    [DataMember]
    public bool IsDeleted { get; set; }
 
    [DataMember]
    public DateTime LastUpdated { get; set; }
 
    [IgnoreDataMember]
    public DateTime LocalLastUpdated { get; set; }
}

You’ll notice that we’ve added the PrimaryKey attribute to the Id field and have marked the LocalLastUpdated field with the Ignore attribute. The Ignore attribute will prevent that field from being sent to WAMS.

 

Person

This is going to be the entity that I’m going to be synchronising. As you can image it’s going to inherit from BaseEntity. It also has the DataContract and DataMember attributes to aid with synchronisation.

[DataContract]
public class Person : BaseEntity
{
    private string name;
    [DataMember]
    public string Name
    {
        get { return name; }
        set
        {
            if (Name == value) return;
            name = value;
            OnPropertyChanged();
        }
    }
 
    private int age;
    [DataMember]
    public int Age
    {
        get { return age; }
        set
        {
            if (Age == value) return;
            age = value;
            OnPropertyChanged();
        }
    }
}

 

At this point it’s worth creating the corresponding table in WAMS. When you create it, you’ll see it appear with a single int Id column – don’t worry, the other columns will get created automatically as you start to synchronise data. Of course, when you go to production you’ll want to disable the dynamic schema capability of WAMS but for the timebeing it makes life easier.

 

MainViewModel

For my single page application I have MainPage.xaml with a corresponding view model, MainViewModel (as per code below). This also inherits from NotifyBase so that it can raise property change events to update the UI when values change. MainViewModel also exposes a StateChanged event which is raised when the view model wants the page to change visual state – I’m not a big fan of having string literals lying around so I use an enumeration to determine which state to go between. Essentially there are two states representing the list of people (Normal) and editing a person (EditPerson).

The MainViewModel has two properties that are exposed for data binding: People, an ObservableCollection of our Person entity, and CurrentPerson. CurrentPerson is used by the EditPerson state to allow the user to add or edit a person record.

The bulk of the heavy lifting has been abstracted away into the DataService class, which we’ll talk about in a minute. The DataService class needs to be initiated with an instance of the ISQLiteConnectionFactory, a path to where the database will be stored, and the endpoint and application key for the mobile service. It also requires a list of entity types that it needs to track and sync. With this information, it’s able to expose very simple methods for loading, saving, deleting and synchronising entities.

public class MainViewModel:NotifyBase
{
    #region ---------------------- Visual States ----------------------
 
    private enum States
    {
        Base,
        EditPerson,
        Normal
    }
    public event EventHandler<StateChangedEventArgs> StateChanged;
 
    #endregion  ---------------------- ----------------------
 
 
 
 
    #region  ---------------------- Data binding properties ----------------------
 
    private Person currentPerson;
    public Person CurrentPerson
    {
        get { return currentPerson; }
        set
        {
            if (CurrentPerson == value) return;
            currentPerson = value;
            OnPropertyChanged();
        }
    }
 
    private readonly ObservableCollection<Person> people = new ObservableCollection<Person>();
    public ObservableCollection<Person> People
    {
        get { return people; }
    }
 
    #endregion  ---------------------- ----------------------
 
 
 
 
    #region ---------------------- Configure Data Service ----------------------
 
    private readonly DataService data = new DataService();
    public DataService Data
    {
        get
        {
            return data;
        }
    }
 
    public void Initialise(string databasePath, ISQLiteConnectionFactory sqLiteConnectionFactory)
    {
        Data.ConfigureDatabase(sqLiteConnectionFactory, databasePath, typeof(Person));
        Data.ConfigureMobileService("https://xxxx.azure-mobile.net/", "--not a real key--");
    }
 
    #endregion  ---------------------- ----------------------
 
 
 
    #region ---------------------- Local Operations ----------------------
 
    /// <summary>
    /// Load data into the people collection (which
    /// will automatically populate the UI)
    /// </summary>
    /// <returns></returns>
    public async Task Load()
    {
        var list = await Data.Load<Person>();
        People.Clear();
        foreach (var person in list)
        {
            People.Add(person);
        }
    }
 
    /// <summary>
    /// Save a new or existing person
    /// </summary>
    public async void SavePerson()
    {
        if (CurrentPerson == null) return;
 
        await Data.Save(CurrentPerson);
 
        if (!People.Contains(CurrentPerson))
        {
            People.Add(CurrentPerson);
        }
 
        CurrentPerson = null;
        StateChanged(this, States.Normal.ToString());
            
    }
 
    /// <summary>
    /// Delete the current person
    /// </summary>
    public async void DeletePerson()
    {
        await Data.Delete(CurrentPerson);
 
        if (People.Contains(CurrentPerson))
        {
            People.Remove(CurrentPerson);
        }
 
        CurrentPerson = null;
        StateChanged(this, States.Normal.ToString());
    }
 
    #endregion ---------------------- ----------------------
 
 
    #region ---------------------- Synchronisation (and reload) ----------------------
        
    /// <summary>
    /// Synchronise local data with WAMS
    /// </summary>
    public async void Sync()
    {
        await Data.Sync<Person>();
 
        await Load();
    }
 
    #endregion ---------------------- ----------------------
 
 
    /// <summary>
    /// Enter edit mode for a new person
    /// </summary>
    public void BeginAddPerson()
    {
        CurrentPerson = new Person();
        StateChanged(this, States.EditPerson.ToString());
    }
 
    /// <summary>
    /// Enter edit mode for an existing person
    /// </summary>
    /// <param name="p"></param>
    public void BeginEditPerson(Person p)
    {
        CurrentPerson = p;
        StateChanged(this, States.EditPerson.ToString());
    }
 
    /// <summary>
    /// Cancel the current edit
    /// </summary>
    public void CancelPersonEdit()
    {
        CurrentPerson = null;
        StateChanged(this, States.Normal.ToString());
 
    }
}

 

DataService

Now onto the good stuff… In this post I’m not going to go through the details of this class but it’s all here (and in the attached sample solution) for you to browse:

public class DataService
{
    private class SyncMarker
    {
        [PrimaryKey]
        public string TypeName { get; set; }
        public DateTime LastSynced { get; set; }
    }
 
 
    private MobileServiceClient MobileService { get; set; }
 
    private ISQLiteConnectionFactory Factory { get; set; }
    private string DatabasePath { get; set; }
    private string MobileServiceEndpoint { get; set; }
    private string MobileServiceApplicationKey { get;  set; }
 
    private Type[] Tables { get; set; }
 
    public void ConfigureDatabase
        (ISQLiteConnectionFactory factory, string path, params Type[] tables)
    {
        Factory = factory;
        DatabasePath = path;
        tables = tables ?? new Type[] {};
        Tables =  tables.Union(new[] {typeof (SyncMarker)}).ToArray();
    }
 
    public void ConfigureMobileService(string endpoint, string applicationKey)
    {
        MobileServiceEndpoint = endpoint;
        MobileServiceApplicationKey = applicationKey;
        MobileService = new MobileServiceClient(MobileServiceEndpoint, 
                                                MobileServiceApplicationKey);
    }
 
    private ISQLiteAsyncConnection connection;
    private async Task<ISQLiteAsyncConnection> Connect()
    {
        if (connection == null)
        {
            connection = Factory.CreateAsync(DatabasePath, true);
            await connection.CreateTablesAsync(Tables);
        }
        return connection;
    }
 
    public async Task<List<TEntity>> Load<TEntity>() 
        where TEntity : class, ISyncableEntity, new()
    {
                    var con = await Connect();
                    var list = await (from p in con.Table<TEntity>()
                                where p.IsDeleted!=true
                                select p).ToListAsync();
        return list;
    }
 
    public async Task Save<TEntity>(TEntity entity) 
        where TEntity : class, ISyncableEntity, new()
    {
        if (entity == null) return ;
 
        var con = await Connect();
        entity.LocalLastUpdated = DateTime.MaxValue;
        if (entity.Id != 0)
        {
            await con.UpdateAsync(entity);
        }
        else
        {
            var minentityId = await (from p in con.Table<TEntity>()
                                    where p.Id < 0
                                    orderby p.Id
                                    select p).FirstOrDefaultAsync();
            var minId = (minentityId != null ? minentityId.Id : 0) - 1;
            entity.Id = minId;
            entity.LastUpdated = DateTime.MinValue;
 
            await con.InsertAsync(entity);
        }
    }
 
    public async Task Delete<TEntity>(TEntity entity) 
        where TEntity : class, ISyncableEntity, new()
    {
        if (entity == null) return;
 
 
        var con = await Connect();
        entity.LocalLastUpdated = DateTime.MaxValue;
        entity.IsDeleted = true;
        if (entity.Id == 0)
        {
            // entity hasn't been saved locally, so simply return
            // nothing more to do (it's like cancel!)
        }
        else if (entity.Id > 0)
        {
            await con.UpdateAsync(entity);
        }
        else
        {
            // Id<0 indicates new entity which hasn't been sync'd
            // so can simply remove out of local db
            await con.DeleteAsync(entity);
        }
    }
 
    public async Task<DateTime?> LastSynced<TEntity>()
    {
        var con = await Connect();
        var typeName = typeof(TEntity).Name;
        var lastSynced = await (from marker in con.Table<SyncMarker>()
                                where marker.TypeName == typeName
                                select marker).FirstOrDefaultAsync();
        return lastSynced != null ? lastSynced.LastSynced : default(DateTime?);
    }
 
    public async Task UpdateLastSynced<TEntity>(DateTime lastUpdated)
    {
        var con = await Connect();
        var typeName = typeof(TEntity).Name;
        var lastSynced = await (from marker in con.Table<SyncMarker>()
                                where marker.TypeName == typeName
                                select marker).FirstOrDefaultAsync();
        if (lastSynced == null)
        {
            lastSynced = new SyncMarker 
            { TypeName = typeName, LastSynced = lastUpdated };
            await con.InsertAsync(lastSynced);
        }
        else
        {
            lastSynced.LastSynced = lastUpdated;
            await con.UpdateAsync(lastSynced);
        }
    }
 
 
    public async Task Sync<TEntity>() 
        where TEntity : class, ISyncableEntity, new()
    {
        var con = await Connect();
        var remoteTable = MobileService.GetTable<TEntity>();
 
        // Need to download existing entities
        var marker = await LastSynced<TEntity>();
        var dateTimeStamp = marker ?? DateTime.MinValue;
        var newTimeStamp = dateTimeStamp;
        var remoteentities = await(from p in remoteTable
                                    where p.LastUpdated > dateTimeStamp
                                    select p).ToListAsync();
        foreach (var entity in remoteentities)
        {
            var local = await (from p in con.Table<TEntity>()
                                where p.Id == entity.Id
                                select p).FirstOrDefaultAsync();
            entity.LocalLastUpdated = entity.LastUpdated;
            if (local != null)
            {
                if (!entity.IsDeleted)
                {
                    await con.UpdateAsync(entity);
                }
                else
                {
                    await con.DeleteAsync(local);
                }
            }
            else
            {
                if (!entity.IsDeleted)
                {
                    await con.InsertAsync(entity);
                }
            }
 
            newTimeStamp = newTimeStamp < entity.LastUpdated ? 
                entity.LastUpdated : newTimeStamp;
        }
 
        // Upload changed entities
        var updatedentities = await (from p in con.Table<TEntity>()
                                    where p.Id > 0 && 
                                    p.LocalLastUpdated > newTimeStamp
                                    select p).ToListAsync();
        foreach (var entity in updatedentities)
        {
 
            await remoteTable.UpdateAsync(entity);
            entity.LocalLastUpdated = entity.LastUpdated;
 
            if (!entity.IsDeleted)
            {
                await con.UpdateAsync(entity);
            }
            else
            {
                await con.DeleteAsync(entity);
            }
 
            newTimeStamp = newTimeStamp < entity.LastUpdated ? 
                entity.LastUpdated : newTimeStamp;
        }
 
        // Upload new entities
        var newentities = await (from p in con.Table<TEntity>()
                                where p.Id < 0
                                select p).ToListAsync();
        foreach (var entity in newentities)
        {
            await con.DeleteAsync(entity);
            entity.Id = 0;
            await remoteTable.InsertAsync(entity);
 
            entity.LocalLastUpdated = entity.LastUpdated;
            await con.InsertAsync(entity);
 
            newTimeStamp = newTimeStamp < entity.LastUpdated ? 
                entity.LastUpdated : newTimeStamp;
        }
 
        await UpdateLastSynced<TEntity>(newTimeStamp);
    }
}

 

Hopefully this gives you a foundation and you can work through the basics of doing data sync to the cloud…. Well, almost…. There is one thing that you may be wondering after trawling through this code. How does the LastUpdated property every get updated? As I mentioned before, with synchronisation you never trust the client. As such it’s the responsibility of the WAMS to update the LastUpdated property as part of both insert and update:

function insert(item, user, request) {
    item.LastUpdated= new Date();
    request.execute();
}
 
function update(item, user, request) {
    item.LastUpdated=new Date();
    request.execute();
}

 

You’ll need to amend the scripts for all entities you wish to sync.

Now, the final thing we haven’t looked at is what you do for conflicts. We’ve been overly optimistic and have assumed that last in wins. Not great if you have multiple users all writing data to the same records. We’ll leave this for a future post.