08 April 2011

Bing Maps control with MVVMLight on Windows Phone 7

This article appeared originally in the March 2011 issue of .Net Magazine – in Dutch. By popular request I wrote this English translation. Regular readers of this blog may recognize parts of it ;-)

A POWERFUL CONTROL WITH A ROBUST ARCHITECTURE

Not everyone is aware of it yet, but MVVM is becoming the de facto standard for all XAML driven environments – WPF, Silverlight, Microsoft Surface and Windows Phone 7. This article shows how this pattern can be applied and how it can make complex tasks like tombstoning easier. A quite unusual approach is used – driving the Bing Maps control

MVVM – theory

MVVM stands for Model-View-Viewmodel. Model (business classes) and View (XAML) are connected by a ViewModel – which was dubbed ‘basically a value convertor on steroids’ by Josh Smith. The ViewModel is a class that provides properties from the Model in such a way that the contents can be displayed using data binding.

Since data binding can work two-way, a change in the ViewModel is automatically displayed in the View, and a change in the View (on user input) is automatically populated to the model. The View can also bind to commands: these are methods in the ViewModel called as a result of an event in the View (for example, a button is pressed), and that in some way manipulate the underlying Model. In theory the companion ‘code behind’ files to the XAML are completely empty. This approach has two distinct advantages:

  1. The ViewModel can be unit-tested, something that’s next to impossible when the logic is put in the code behind in the traditional way.
  2. The View itself – the XAML – is totally devoid of code. Therefore a designer, who is not interested in code, can happily style the and adapt the View without breaking functionality.

MVVM – in practice, on Windows Phone 7

Windows Phone 7 – based on Silverlight 3 – poses some challenges. Property binding is a breeze, but command binding is not – for the simple reason that the classes supporting command binding are missing. Another challenge is the fact that Windows Phone 7 applications can be interrupted at any moment – because the user hits the ‘Start’ button, for instance. When this occurs, the application state must be preserved – ‘tombstoned’.

CodePlex host various frameworks that enable MVVM support in Silverlight and Windows Phone 7. Two of the most well-known are (in no particular order) MVVMLight by Laurent Bugnion and Caliburn Micro by Rob Eisenberg. Both have their distinct advantages and disadvantages, both have their ardent advocates. In this article MVVMLight is used.

In the next sample all classes are put together in one project – in practice certain classes will get their own assemblies. But the purpose of this article is to show the idea behind using MVVM.

Base application

designedappThe way Bing Maps and MVVMLight can act together will be demonstrated using a simple “MapBindingDemo” app. This consists of a Bing Maps control, two buttons to select map types, and a TextBlock to display the name of the selected map. Map manipulation by using pinch zoom, pan and double tap are all included for free, courtesy of the Bing Maps control. The easiest way to get started is to create an empty “Windows Phone Application” in Visual Studio 2010. Then open this application in Blend, enter “Map” in the Assets box and drag the map on the design pane. Add controls until the result looks like displayed on the the right.

 

 

In XAML, the result should look like this:

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0"/>
<Grid Grid.Row="1">
  <Grid.ColumnDefinitions>
    <ColumnDefinition Width="0.167*"/>
    <ColumnDefinition Width="0.667*"/>
    <ColumnDefinition Width="0.167*"/>
  </Grid.ColumnDefinitions>
  <Grid.RowDefinitions>
    <RowDefinition Height="0.13*"/>
    <RowDefinition Height="0.87*"/>
  </Grid.RowDefinitions>
  <Microsoft_Phone_Controls_Maps:Map Grid.Row="1" Grid.ColumnSpan="3"/>
  <Button Content="<"/>
  <Button Content=">" Grid.Column="2"/>
  <TextBlock Grid.Column="1" TextWrapping="Wrap" Text="TextBlock" 
    Margin="0,23,0,0" HorizontalAlignment="Center"/>
</Grid>

Those who are stubborn enough to venture here without using Blend: the project should have a reference to Windows.Controls.Phone.Maps and the namespace declarations of the PhoneApplicationPage should include the following declarations:

xmlns:Microsoft_Phone_Controls_Maps=
   "clr-namespace:Microsoft.Phone.Controls.Maps;assembly=Microsoft.Phone.Controls.Maps"

Another thing to take into consideration is the fact that Bing Maps Control usages requires credentials. These can be created using this website.The credentials should be included in the Map Control’s CredentialsProvider property. The Uri the site asks for does not matter – that’s only important when the Bing Maps control is used in a web site context, which is obviously not the case in a Windows Phone 7 app.

Bing Maps Control and TileSource

The Bing Maps Control is pretty flexible and powerful, and can show both vector and raster maps. This example concentrates on the latter. It’s important to know the control has three major settings as far as raster maps are concerned: “Road”,  “Aerial” and the least known – “Mercator”. When Mercator is set, the control won’t download any map data by itself – the developer should supply the logic in a class implementing Microsoft.Phone.Controls.Maps.TileSource. Only the GetUri method needs to be overridden. The Bing Maps controls supplies mapclassesthree parameters to this method: x, y and zoomlevel. At level 1, the world is a square of 2x2=4 tiles of 256x256 pixels each. On level 2, there are 16 tiles, on level 3 there are 64, etc. The method GetUri should convert these three numbers into an Uri leading to a suitable image. For geo nuts like me a piece of cake, for the rest of the world possible a load of gobbledygook. This is by no means a problem when trying to understand MVVM - the TileSource code is all included in this article. The application sports a folder "Maps" which will include this code.

In this article, the code for the various TileSources is showed in a single code file to give an easier overview. In real-world development, only code generators put multiple classes in one file, eh?

using System;
using Microsoft.Phone.Controls.Maps;

namespace MapBindingDemo.Maps
{
  public abstract class BaseTileSource : TileSource, 
    IEquatable<BaseTileSource>
  {
    public string Name { get; set; }


    public bool Equals(BaseTileSource other)
    {
      return other != null && other.Name.Equals(Name);
    }

    public override bool Equals(object obj)
    {
      return Equals(obj as BaseTileSource);
    }
  }

//------------------------

  public abstract class BaseBingSource : BaseTileSource
  {
    private static string TileXYToQuadKey(int tileX, int tileY, int levelOfDetail)
    {
      var quadKey = new StringBuilder();
      for (var i = levelOfDetail; i > 0; i--)
      {
        char digit = '0';
        int mask = 1 << (i - 1);
        if ((tileX & mask) != 0) digit++;
        if ((tileY & mask) != 0)
        {
          digit++;
          digit++;
        }
        quadKey.Append(digit);
      }
      return quadKey.ToString();
    }

    public override Uri GetUri(int x, int y, int zoomLevel)
    {
      if (zoomLevel > 0)
      {
        string quadKey = TileXYToQuadKey(x, y, zoomLevel);
        string veLink = string.Format(UriFormat,
           new object[] { quadKey[quadKey.Length - 1], quadKey });
        return new Uri(veLink);
      }
      return null;
    }
  }
  
//------------------------  
  
  public class BingRoad : BaseBingSource
  {
    public BingRoad()
    {
      UriFormat = "http://r{0}.ortho.tiles.virtualearth.net/tiles/r{1}.png?g=203";
    }
  }
  
//------------------------  

  public class BingAerial : BaseBingSource
  {
    public BingAerial()
    {
      UriFormat = "http://h{0}.ortho.tiles.virtualearth.net/tiles/h{1}.jpeg?g=203";
    }
  }

//------------------------

  public class OsmaRender : BaseTileSource
  {
    public OsmaRender()
    {
      UriFormat = "http://{0}.tah.openstreetmap.org/Tiles/tile/{1}/{2}/{3}.png";
    }

    private readonly static string[] TilePathPrefixes = 
      new[] { "a", "b", "c", "d", "e", "f" };

    public override Uri GetUri(int x, int y, int zoomLevel)
    {
      if (zoomLevel > 0)
      {       
        var url = string.Format(UriFormat, 
          TilePathPrefixes[(y%3) + (3*(x%2))], zoomLevel, x, y);
        return new Uri(url);
      }
      return null;
    }
  }
  
//------------------------  

  public class Mapnik : BaseTileSource
  {
    public Mapnik()
    {
      UriFormat = "http://{0}.tile.openstreetmap.org/{1}/{2}/{3}.png";
    }

    private readonly static string[] TilePathPrefixes = new[] { "a", "b", "c" };

    public override Uri GetUri(int x, int y, int zoomLevel)
    {
      if (zoomLevel > 0)
      {
        var url = string.Format(UriFormat, TilePathPrefixes[y%3], zoomLevel, x, y);
        return new Uri(url);
      }
      return null;
    }
  }
  
//------------------------  

  public enum GoogleType
  {
    Street     ='m',
    Hybrid     ='y',
    Satellite    ='s',
    Physical     ='t',
    PhysicalHybrid ='p',
    StreetOverlay  ='h',
    WaterOverlay   ='r'
  }

//------------------------  
  
  public class Google : BaseTileSource
  {
    public Google()
    {
      MapType = GoogleType.PhysicalHybrid;
      UriFormat = @"http://mt{0}.google.com/vt/lyrs={1}&z={2}&x={3}&y={4}";
    }

    public GoogleType MapType { get; set; }

    public override Uri GetUri(int x, int y, int zoomLevel)
    {
      return new Uri( 
        string.Format(UriFormat, (x % 2) + (2 * (y % 2)),
        (char)MapType, zoomLevel, x, y) );
    }
  } 
}

The starting point is a base class “BaseTileSource” which only adds a Name property and an Equals method that compares by name – a quite naïve implementation, but sufficient for this purpose. A subclass “BaseBingSource” contains most of the heavy lifting for the Bing Maps calculations, so two pretty simple subclasses “BingAerial” and “BingRoad” are all that’s needed to implement Bing Aerial and Bing Road. So far the net result is a quite complicated way to get exactly the same result as the standard Bing Maps Control, but the fun starts when two well-known open source OpenStreetMap mapservers are added – OsmaRender and Mapnik. And of course my personal favorite ‘nag the competition’ option: Google Maps.

As stated before, the Bing Maps Control should operate in Mercator mode. The way to do this is described below:

<Microsoft_Phone_Controls_Maps:Map                 
    CredentialsProvider="your_credentials_here">               
    <Microsoft_Phone_Controls_Maps:Map.Mode>
        <MSPCMCore:MercatorMode/>
    </Microsoft_Phone_Controls_Maps:Map.Mode>
</Microsoft_Phone_Controls_Maps:Map>

The namespace “MSPCMCore” is declared in the PhoneApplicationPage tag like this:

"clr-namespace:Microsoft.Phone.Controls.Maps.Core;assembly=Microsoft.Phone.Controls.Maps"

Setup MVVMLight

Solution1The framework itself contains of two assemblies: GalaSoft.MvvmLight.WP7.dll andGalaSoft.MvvmLight.Extras.WP7.dll. These can be downloaded from CodePlex. Apart from those, the assembly System.Windows.Interactivity.dll is necessary as well – this can be found in the Expression Blend SDK and is locaties either in
<drive>:\Program Files\Microsoft SDKs\Expression\Blend\Windows Phone\v7.0\Libraries
or in
<drive>:\Program Files (x86)\Microsoft SDKs\Expression\Blend\Windows Phone\v7.0\Libraries
when you have a 64 bit OS, which is becoming ever more commonplace these days. It’s good practice to put these assemblies in a solution folder to make sure they remain associated with the solution – it makes working with multiple developers on a single Windows Phone 7 project utilizing a source control mechanism a lot easier. In this sample a folder “Binaries” is used to that effect. The project needs to have a reference to the three assemblies mentioned above, and the solution now should look like displayed to the right.

Map app ViewModel

An MVVMLight ViewModel is a child class of the most originally named “ViewModelBase” class. A number of properties are defined within this application’s ViewModel: ZoomLevel, MapCenter, AvailableMaps and CurrentMap. In addition, it has a number of commands: one for moving a map definition ahead, and one for moving back. The ViewModel looks like this:

using System.Collections.Generic;
using System.Device.Location;
using System.Windows.Input;
using GalaSoft.MvvmLight;
using GalaSoft.MvvmLight.Command;
using MapBindingDemo.Maps;
using MapBindingDemo.Serialization;

namespace MapBindingDemo.ViewModel
{
  public class MvvmMap : ViewModelBase
  {
    public MvvmMap()
    {
      _availableMapSources = new List<BaseTileSource> 
      {
        new BingAerial{ Name = "Bing Aerial"},
        new BingRoad {Name = "Bing Road"},
        new Mapnik {Name = "OSM Mapnik"},
        new OsmaRender {Name = "OsmaRender"},
        new Google {Name = "Google Hybrid", MapType = GoogleType.Hybrid},
        new Google {Name = "Google Street", MapType = GoogleType.Street},
      };
    }

    private GeoCoordinate _mapCenter;
    public GeoCoordinate MapCenter
    {
      get { return _mapCenter; }
      set
      {
        if (_mapCenter == value) return;
        _mapCenter = value;
        RaisePropertyChanged("MapCenter");
      }
    }

    private double _zoomLevel;
    public double ZoomLevel
    {
      get
      {
        return _zoomLevel;
      }
      set
      {
        if (value == _zoomLevel) return;
        if (value >= 1)
        {
          _zoomLevel = value;
        }
        RaisePropertyChanged("ZoomLevel");
      }
    }

    private BaseTileSource _currentMap;
    public  BaseTileSource CurrentMap
    {
      get
      {
        if (_currentMap == null && 
          _availableMapSources != null && 
          _availableMapSources.Count > 0)
        {
          _currentMap = _availableMapSources[0];
        }
        return _currentMap;
      }
      set
      {
        if (value.Equals(CurrentMap)) return;
        {
          _currentMap = value;
        }
        RaisePropertyChanged("CurrentMap");
      }
    }

    private List<BaseTileSource> _availableMapSources;
    [DoNotSerialize]
    public List<BaseTileSource> AvailableMapSources
    {
      get
      {
        return _availableMapSources;
      }
      set
      {
        _availableMapSources = value;
        RaisePropertyChanged("AvailableMapSources");
      }
    }

    public ICommand NextMap
    {
      get
      {
        return new RelayCommand(() =>
        {
          var newIdx = AvailableMapSources.IndexOf(CurrentMap) + 1 ;
          CurrentMap = 
            AvailableMapSources[newIdx > AvailableMapSources.Count - 1? 0 : newIdx];
        });
      }
    }

    public ICommand PreviousMap
    {
      get
      {
        return new RelayCommand(() =>
        {
          var newIdx = AvailableMapSources.IndexOf(CurrentMap) -1;
          CurrentMap = 
            AvailableMapSources[newIdx < 0 ? 
             AvailableMapSources.Count - 1 : newIdx];
        });
      }
    }
     
    private static MvvmMap _instance;
    public static MvvmMap Instance
    {
      get { return _instance; }
      set { _instance = value; }
    }

    public static void CreateNew()
    {
      _instance = new MvvmMap();
    }
  }
}

Hooking up ViewModel and user interface using Blend

dataUsing databinding, ZoomLevel and MapCenter can be hooked up without any special measures to a Bing Maps control, while the TextBlock “TextBlock” should display the map name. The easiest way to accomplish this is using Expression Blend. A free version for Windows Phone is included with the Windows Phone 7 tools. When Blend has finished loading your projects, notice the three tabs to the upper right: "Properties", "Resources" and "Data". Click the encircled symbol and a menu appears, which contains the option “Create Object Data Source. When this is selected, a popup appears with all the objects in the solution. Click MapBindingDemo, then MapBindingDemo.ViewModel, and finally MvvmMap. To the right, the properties of MvvmMap are displayed. Drag the “Instance” property to the Grid “LayoutRoot” in the “Objects and Timeline” panel at the left side. Blend shows the text “Data bind LayoutRoot.DataContext to Instance”. Release the mouse button and – done. Data binding.

At the right bottom, a panel “Data context” has appeared. Drag property “Name” from “CurrentMap” on top of the TextBlock. The contents of the TextBlock immediately changes to “Bing Aerial”. And that’s correct, since the ViewModel code shows that when no map is selected, the first map in “AvailableMaps” should be selected, which is indeed Bing Aerial.

ObjectsAndTimeLineGo back to the “Objects and Timeline” panel, and select the object “Map”. To get there, you will first need to expand “Layoutroot” and “Grid”. Data bind the “MapCenter” property of the ViewModel to the “Center” property of the map by dragging MapCenter on top of the Bing Maps controls – a popup appears, in which you can select the “Center” property.

For some strange reason I could not get Blend to databind “ZoomLevel” this way – it only wants to bind to “Content”. To work around this: select advancedoptionstab “Properties”. Then expand “Miscellaneous”. All the way down you will see the “ZoomLevel” property. Right next to it is a little square: click this, and this will yield and menu which contains the option “Data Binding”. Select this, and then select property “ZoomLevel” of the model in the popup that follows.

Now switch to the XAML view, and notice that in the Bing Maps Control Center and Zoomlevel properties are bound: Center="{Binding MapCenter}" ZoomLevel="{Binding ZoomLevel}". To make the binding function properly, change this to Center="{Binding MapCenter, Mode=TwoWay}" ZoomLevel="{Binding ZoomLevel, Mode=TwoWay}”. This can be done from Blend as well, but this way is quicker.

Databinding command utilizes the MVVMLight EventToCommand behavior. Type “Event” in the “Search” box top left and the EventToCommand behavior appears. Drag this on both the “<” and the “>” button. Then drag “PreviousCommand” from the ViewModel on top of the EventToCommand below the “<” button (inthe Objects and Timeline panel). “NextCommand” is databound in the same way to the “>” button. Hit F5 in Blend, the emulator appears and when “>” and “<” the text in the TextBlock should change. But the map does not play along – even more, there is absolutely no map visible. That’s because there’s no TileSource associated with it.

Attached Dependency Properties – plumbing holes in data binding

Binding a TileSource to a Bing Maps control is not possible, because there’s no fitting property. Fortunately XAML includes attached dependency properties – these can be regarded as the property equivalent of extension methods. Back to Visual Studio, where an attached dependency property will be created in the folder “ViewModel”

using System.Windows;
using MapBindingDemo.Maps;
using Microsoft.Phone.Controls.Maps;

namespace MapBindingDemo.ViewModel
{
  public static class BindingHelpers
  {
    //Used for binding a single TileSource object to a Bing Maps control
    #region TileSourceProperty

    public static readonly DependencyProperty TileSourceProperty =
      DependencyProperty.RegisterAttached("TileSource", typeof(TileSource),
      typeof(BindingHelpers), new PropertyMetadata(SetTileSourceCallback));

    // Called when TileSource is retrieved
    public static TileSource GetTileSource(DependencyObject obj)
    {
      return obj.GetValue(TileSourceProperty) as TileSource;
    }

    // Called when TileSource is set
    public static void SetTileSource(DependencyObject obj, TileSource value)
    {
      obj.SetValue(TileSourceProperty, value);
    }

    //Called when TileSource is set
    private static void SetTileSourceCallback(object sender, 
      DependencyPropertyChangedEventArgs args)
    {
      var map = sender as Map;
      var newSource = args.NewValue as TileSource;
      if (newSource == null || map == null) return;

      // Remove existing layer(s)
      for (var i = map.Children.Count - 1; i >= 0; i--)
      {
        var tileLayer = map.Children[i] as MapTileLayer;
        if (tileLayer != null)
        {
          map.Children.RemoveAt(i);
        }
      }
      
      var newLayer = new MapTileLayer();
      newLayer.TileSources.Add(newSource);
      map.Children.Add(newLayer);
    }
    #endregion
  }
}

This quite adequately shows why an attached dependency property is necessary: a Bing Maps controls has Children that can contain (among others) MapTileLayer objects – and only that contains a TileSource. So when the displayed map is changed, first all current MapTileLayer objects need to be deleted, before a new MapTileLayer containing the new Tilesource is created, that can be added to the Children of the map. With this in place, the whole ViewModel can be databound to the Bing Maps Control. Unfortunately not with Blend, so this will have to go manually, in XAML. Add the namespace in which the BindingHelper class is situated to the namespace declarations at the top of the PhoneApplicationPage:

xmlns:MapBindingDemo_ViewModel="clr-namespace:MapBindingDemo.ViewModel"

Now the actual binding to the map needs to take place. On the same spot where ZoomLevel and MapCenter were bound the attached dependency property is bound:

<Microsoft_Phone_Controls_Maps:Map x:Name="Map" Grid.Row="1" Grid.ColumnSpan="3"             
  CredentialsProvider="your_credentials_here" 
  Center="{Binding MapCenter, Mode=TwoWay}" 
  ZoomLevel="{Binding ZoomLevel, Mode=TwoWay}" 
  MapBindingDemo_ViewModel:BindingHelpers.TileSource ="{Binding CurrentMap}">

Now the application is fully functional, even in design mode it shows the default map (Bing Aerial). The buttons left and right of the map name change the map that’s displayed – with not a single line of code in the code behind. Granted, the user experience and look and feel could benefit from some more attention, but nevertheless – mission accomplished. Well, almost. Zoom in a little, select a map that not the default, hit the start button and then hit back. Alas – the default map again, with full world view. The application’s last state is not preserved,  or to put things differently – it does not support tombstoning.

Tombstoning an MVVMLight application

Mike Talbot has written a brilliant post in which he describes a helper object called “SilverlightSerializer”. This object can serialize virtually every Silverlight and Windows Phone 7 object as a binary. The fun part is that it even serializes non-serializable objects – like MVVMLight’s ViewModelBase. The blog post is called “Silverlight Binary Serialization” and includes the source code.

SilverlightSerializer is added to a folder “Serialization” in the project. In the same folder (and namespace) a file “ApplicationExtensions.cs” is added that implements two extension methods on the Application class: one for writing the entire ViewModel to Isolated Storage, and one for reading it back from IS.

using System;
using System.IO;
using System.IO.IsolatedStorage;
using System.Windows;
using GalaSoft.MvvmLight;

namespace MapBindingDemo.Serialization
{
  /// <summary>
  /// Some extensions method that allow serializing and deserializing
  /// a model to isolated storage
  /// </summary>
  public static class ApplicationExtensions
  {
    private static string GetDataFileName( Type t)
    {
      return string.Concat(t.Name, ".dat");
    }

    public static T RetrieveFromIsolatedStorage<T>(this Application app) 
      where T : class
    {
      using (var appStorage = IsolatedStorageFile.GetUserStoreForApplication())
      {
        var dataFileName = GetDataFileName(typeof(T));
        if (appStorage.FileExists(dataFileName))
        {
          using (var iss = appStorage.OpenFile(dataFileName, FileMode.Open))
          {
            try
            {
              return SilverlightSerializer.Deserialize(iss) as T;
            }
            catch (Exception e)
            {
              System.Diagnostics.Debug.WriteLine(e);
            }
          }
        }
      }
      return null;
    }

    public static void SaveToIsolatedStorage(this Application app, 
      ViewModelBase model)
    {
      var dataFileName = GetDataFileName((model.GetType()));
      using (var appStorage = IsolatedStorageFile.GetUserStoreForApplication())
      {
        if (appStorage.FileExists(dataFileName))
        {
          appStorage.DeleteFile(dataFileName);
        }
        using (var iss = appStorage.CreateFile(dataFileName))
        {
           SilverlightSerializer.Serialize(model,iss);          
        }
      }
    }
  }
}

These methods are used from App.Xaml’s code behind. This may look like a deviation from the MVVM paradigm, but it’s not as bad as it looks. This file has some default code anyway (the Application_* methods), for this is the place that sports the methods that are called when the application (re)starts or stops. This last step just adds a little code. First, add two usings:

using MapBindingDemo.Serialization;
using MapBindingDemo.ViewModel;

Then, adapt the existing code till it looks like this:

// Code to execute when the application is launching (eg, from Start)
// This code will not execute when the application is reactivated
private void Application_Launching(object sender, LaunchingEventArgs e)
{  
  LoadModelFromIsolatedStorage();
}

// Code to execute when the application is activated (brought to foreground)
// This code will not execute when the application is first launched
private void Application_Activated(object sender, ActivatedEventArgs e)
{
  LoadModelFromIsolatedStorage();
}

/// 
/// Loads the model from isolated storage
/// 
private void LoadModelFromIsolatedStorage()
{
  MvvmMap.Instance = this.RetrieveFromIsolatedStorage();
  if (MvvmMap.Instance == null) MvvmMap.CreateNew();
}

// Code to execute when the application is deactivated (sent to background)
// This code will not execute when the application is closing
private void Application_Deactivated(object sender, DeactivatedEventArgs e)
{
  this.SaveToIsolatedStorage(MvvmMap.Instance);
}

// Code to execute when the application is closing (eg, user hit Back)
// This code will not execute when the application is deactivated
private void Application_Closing(object sender, ClosingEventArgs e)
{
   this.SaveToIsolatedStorage(MvvmMap.Instance);
}

Notice both deactivation and closing call the same code: the data is always written to Isolated Storage. Similarly, launching and deactivation always call RetrieveFromIsolatedStorage. It’s perfectly possible to store the ViewModel in the PhoneApplicationService but then the stored model won’t be available when the application is started again from the start menu (in stead of using the “back” button). This is “works as designed” behavior as far as Windows Phone 7 is concerned but if it’s used in as described above, both the back button and a restart give the same result – the last application state is preserved.

A drawback of saving the entire ViewModel as a binary is that deserializing fails when major changes are implemented in the ViewModel. This is why it always is surrounded by try/catch statements. Attentive readers also may have noticed that property “AvailableMapSources” is serialized in vain, since it’s always initialized from the constructor. SilverlightSerializer’s default behavior is to serialize everything, but if something needs to be skipped it can be marked with the [DoNotSerialize] attribute defined by SilverlightSerializer itself.

Concluding remarks

For all but the most trivial Windows Phone 7 applications MVVM simply is the way to go, if only because SilverlightSerializer makes a quite complex thing like tombstoning a breeze. For complex application with multiple models things get a lit more challenging, but it’s clear MVVMLight and SilverlightSerializer are a winning team.

Thanks to Jarno Peshier and Dennis Vroegop for their suggestions on the original article.

Code can be downloaded here.

08 March 2011

Simple Windows Phone 7 / Silverlight drag/flick behavior

In this post I describe a behavior that will essentially make anything draggable and ‘flickable’, that is, you can drag a GUI element along with your finger and it seems to have a little inertia when you let it go. The behavior mimics part of the Microsoft Surface’s ScatterView functionality and will feature in the small children’s game for Windows Phone 7 game I am currently developing. As a bonus, you will see some generally applicable extension methods for creating storyboards and translation GUI elements too.

I have not tried this in Silverlight but I am not doing anything Windows Phone 7 specific as far as I am aware, so I guess it should work in plain Silverlight too.

Setting the stage

I created a simple solution containing three assemblies: a Windows Phone application, a class library “LocalJoost” holding my utilities including this behavior, and one containing Phone.Fx.Preview, not for the BindableApplicationBar this time, but because I make extensive use of its VisualTreeHelperExtensions. You will also need System.Windows.Interactivity.dll, which I nicked from the MVVMLight toolkit.

Extensions for FrameworkElement

First of all, I created a set of extension methods on FrameworkElement that allow me to easily find and manipulate an attached CompositeTransform from code. A CompositeTransform is only one of the many possibilities to manipulate a GUI element, but it basically is just a descriptor of how far from its original place the GUI element should be drawn, if it should be rotated, scaled, etc. I only use the translation attributes – to move it around.

To be able to translated and animated, the object must have a CompositeTransform. Well, at least it must for the solution I have chosen. You will see later that the behavior checks for this transform and if it’s not present, it simply makes it. But you can also create it in XAML, of course.

using System;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Media;
using System.Linq;
using Phone7.Fx.Preview;

namespace LocalJoost.Utilities
{
  /// <summary>
  /// Class to help animations from code using the CompositeTransform
  /// </summary>
  public static class FrameworkElementExtensions
  {
    /// <summary>
    /// Finds the composite transform either direct
    /// or as part of a TransformGroup
    public static CompositeTransform GetCompositeTransform(
       this FrameworkElement fe)
    {
      if (fe.RenderTransform != null)
      {
        var tt = fe.RenderTransform as CompositeTransform;
        if( tt != null) return tt;

        var tg = fe.RenderTransform as TransformGroup;
        if (tg != null)
        {
          return tg.Children.OfType<CompositeTransform>().FirstOrDefault();
        }
      }
      return null;
    }

    /// <summary>
    /// Gets the point to where FrameworkElement is translated
    /// </summary>
    public static Point GetTranslatePoint(this FrameworkElement fe)
    {
      var translate = fe.GetCompositeTransform();
      if (translate == null) 
         throw new ArgumentNullException("CompositeTransform");

      return new Point(
        (double) translate.GetValue(CompositeTransform.TranslateXProperty),
        (double) translate.GetValue(CompositeTransform.TranslateYProperty));

    }

    /// <summary>
    /// Translates a FrameworkElement to a new location
    /// </summary>
    public static void SetTranslatePoint(this FrameworkElement fe, Point p)
    {
      var translate = fe.GetCompositeTransform();
      if (translate == null) 
         throw new ArgumentNullException("CompositeTransform");

      translate.SetValue(CompositeTransform.TranslateXProperty, p.X);
      translate.SetValue(CompositeTransform.TranslateYProperty, p.Y);
    }

    /// <summary>
    /// Translates a FrameworkElement to a new location
    /// </summary>
    public static void SetTranslatePoint(
       this FrameworkElement fe, double x, double y )
    {
      fe.SetTranslatePoint(new Point(x, y));
    }

    public static FrameworkElement GetElementToAnimate( 
      this FrameworkElement fe)
    {
      var parent = fe.GetVisualParent();
      return parent is ContentPresenter ? parent : fe;
    }
  }
}

Note in the last method that the element to animated is either the element itself or a ContentPresenter that is its parent. I noticed that stuff created by databinding is always surrounded by a ContentPresenter, and that animating an object within its ContentPresenter does not work – logically. So then then the ContentPresenter is animated in stead – dragging its contents with it.

Extensions for StoryBoard

Next up, a set of extension methods to easily create translation animations, and add them to storyboard:

using System;
using System.Windows;
using System.Windows.Media;
using System.Windows.Media.Animation;

namespace LocalJoost.Utilities
{
  public static class StoryboardExtensions
  {
    /// <summary>
    /// Create a animation with a default easing function
    /// </summary>
    public static Timeline CreateDoubleAnimation(this Storyboard storyboard,
      Duration duration, double from, double to)
    {
      return storyboard.CreateDoubleAnimation(duration, from, to,
        new SineEase
        {
          EasingMode = EasingMode.EaseInOut
        });
    }

    /// <summary>
    /// Create a animation with a custom easing function
    /// </summary>
    public static Timeline CreateDoubleAnimation(this Storyboard storyboard, 
      Duration duration, double from, double to, IEasingFunction easingFunction)
    {
      var animation = new DoubleAnimation
      {
        From = from,
        To = to,
        Duration = duration,
        EasingFunction = easingFunction
      };
      return animation;
    }

    /// <summary>
    /// Add an animation to an existing storyboard
    /// </summary>
    public static void AddAnimation(this Storyboard storyboard, 
      DependencyObject item, Timeline t, DependencyProperty p)
    {
      if (p == null) throw new ArgumentNullException("p");
      Storyboard.SetTarget(t, item);
      Storyboard.SetTargetProperty(t, new PropertyPath(p));
      storyboard.Children.Add(t);
    }

    /// <summary>
    /// Add a translation animation to an existing storyboard with a 
    /// default easing function
    /// </summary>
    public static void AddTranslationAnimation(this Storyboard storyboard, 
      FrameworkElement fe, Point from, Point to, Duration duration)
    {
      storyboard.AddTranslationAnimation(fe, from, to, duration, null);
    }

    /// <summary>
    /// Add a translation animation to an existing storyboard with a 
    /// custom easing function
    /// </summary>
    public static void AddTranslationAnimation(this Storyboard storyboard, 
      FrameworkElement fe, Point from, Point to, Duration duration,
      IEasingFunction easingFunction)
    {
      storyboard.AddAnimation(fe.RenderTransform,
             storyboard.CreateDoubleAnimation(duration, from.X, to.X, 
                                              easingFunction),
              CompositeTransform.TranslateXProperty);
      storyboard.AddAnimation(fe.RenderTransform,
            storyboard.CreateDoubleAnimation(duration, from.Y, to.Y, 
                                             easingFunction),
              CompositeTransform.TranslateYProperty);
    }
  }
}

You will probably only use the last two methods. Create an empty StoryBoard, pop in a FrameworkElement, the “from” and “to” point, the time it should take and optionally an easing function, then start your StoryBoard and off your GUI element goes.

An easing function, by the way, describes a bit about the way an objects starts, stops and moves. No easing function means the object moves from start to end with a constant speed. If you take a SineEase with an EaseInOut mode, it will first move slowly, than increase speed, and at the end it more or less slowly comes to a halt. This makes for a more fluid behavior. There are about a gazillion easing functions, and I encourage you to explore them with Expression Blend.

The DragFlickBehavior itself

Then finally the behavior itself, which is surprisingly simple now all the groundwork has been laid by the extension methods:

using System;
using System.Windows;
using System.Windows.Input;
using System.Windows.Interactivity;
using System.Windows.Media;
using System.Windows.Media.Animation;
using LocalJoost.Utilities;

namespace LocalJoost.Behaviors
{
  public class DragFlickBehavior: Behavior<FrameworkElement>
  {
    private FrameworkElement _elementToAnimate;
    
    protected override void OnAttached()
    {
      base.OnAttached();
      AssociatedObject.Loaded += AssociatedObjectLoaded;
      AssociatedObject.ManipulationDelta += 
         AssociatedObjectManipulationDelta;
      AssociatedObject.ManipulationCompleted += 
         AssociatedObjectManipulationCompleted;
    }
    
    void AssociatedObjectLoaded(object sender, RoutedEventArgs e)
    {
      _elementToAnimate = AssociatedObject.GetElementToAnimate();
      if (! (_elementToAnimate.RenderTransform is CompositeTransform))
      {
        _elementToAnimate.RenderTransform = new CompositeTransform();
        _elementToAnimate.RenderTransformOrigin = new Point(0.5, 0.5);
      }
    }

    void AssociatedObjectManipulationDelta(object sender, 
        ManipulationDeltaEventArgs e)
    {
      var dx = e.DeltaManipulation.Translation.X;
      var dy = e.DeltaManipulation.Translation.Y;
      var currentPosition = _elementToAnimate.GetTranslatePoint();
      _elementToAnimate.SetTranslatePoint(currentPosition.X + dx, 
         currentPosition.Y + dy);
    }

    private void AssociatedObjectManipulationCompleted(object sender, 
      ManipulationCompletedEventArgs e)
    {
      // Create a storyboard that will emulate a 'flick'
      var currentPosition = _elementToAnimate.GetTranslatePoint();
      var velocity = e.FinalVelocities.LinearVelocity;
      var storyboard = new Storyboard { FillBehavior = FillBehavior.HoldEnd };

      var to = new Point(currentPosition.X + (velocity.X / BrakeSpeed),
        currentPosition.Y + (velocity.Y / BrakeSpeed));
      storyboard.AddTranslationAnimation(
        _elementToAnimate, currentPosition, to, 
        new Duration(TimeSpan.FromMilliseconds(500)), 
        new CubicEase {EasingMode = EasingMode.EaseOut});
      storyboard.Begin();
    }


    protected override void OnDetaching()
    {
      AssociatedObject.Loaded -= AssociatedObjectLoaded;
      AssociatedObject.ManipulationCompleted -= 
          AssociatedObjectManipulationCompleted;
      AssociatedObject.ManipulationDelta-= 
          AssociatedObjectManipulationDelta;

      base.OnDetaching();
    }

    #region BrakeSpeed
    public const string BrakeSpeedPropertyName = "BrakeSpeed";

    /// <summary>
    /// Describes how fast the element should brake, i.e. come to rest,
    /// after a flick. Higher = apply more brake ;-)
    /// </summary>
    public int BrakeSpeed
    {
      get { return (int)GetValue(BrakeSpeedProperty); }
      set { SetValue(BrakeSpeedProperty, value); }
    }

    public static readonly DependencyProperty BrakeSpeedProperty = 
      DependencyProperty.Register(
      BrakeSpeedPropertyName,
      typeof(int),
      typeof(DragFlickBehavior),
      new PropertyMetadata(10));

    #endregion
  }
}

And half of it is a dependency property, too ;-). What this behavior does, is:

  • When attached, it checks which element to animate, checks for an CompositeTransform to be present and if not, simply create it.
  • While the element is being manipulated, change the translate point by the delta x and y of the drag event, therefore the element will follow your finger – and causing the element apparently to be ‘dragged’
  • When you stop dragging, it creates a simple storyboard that will move the element a bit further in the direction you last dragged it, seemingly causing a bit on inertia. It does that by looking at the FinalVelocities’s LinearVelocity property values. If you move it fast enough, it will move right out of the screen, never to return ;-). That’s more or less what I mean by ‘flick’. The BrakeSpeed property of the behavior determines how fast the element comes to a half. I find the default value 10 to have quite a natural feeling to it – on my phone, that is.

Demo

For the sample solution I fired up Expression Blend, dragged some elements on a Windows Phone 7 page and attached the behavior to everything - up to the page name and application name, as you can see in the demo video. That is not particularly useful in itself, but it drives home the point. Your designer can now have fun with this behavior ;-), and I hope I have showed you some little things on how to manipulate storyboard and elements from code in the process.

The DragFlickBehavior in action

05 March 2011

Easy access to WMAppManifest.xml App properties like version and title

Every Windows Phone 7 application must have an Application Manifest file called WMAppManifest.xml. In this you must state title, author, version and some other things. A quote from the link above:

“The primary purpose of this file is the following:

  • The Windows Phone Marketplace application submission process uses information from the manifest file. The manifest file supports the submission of applications to the Windows Phone Marketplace (including certification), device marketplace filtering, marketplace-to-device deployment, and device execution.
  • The information from the manifest file is used as the application metadata that will be stored in the application database.”

For some reason it’s not common knowledge that information in this file can accessed runtime as well. This can come in very handy, for example for showing a consistent app title and even more important, it’s version number. There are some examples of this to be found on the web but they are not very clear or pretty limited, so I cobbled together this little helper class to make retrieving attributes from the App tag a little easier:

using System.Collections.Generic;
using System.Xml.Linq;

namespace LocalJoost.Utilities
{
  /// <summary>
  /// A helper class to easily retrieve data from the WMAppManifest.xml
  /// App tag
  /// </summary>
  public class ManifestAppInfo
  {
    public ManifestAppInfo()
    {
    }

    static Dictionary<string, string> _properties;

    static Dictionary<string, string> Properties
    {
      get
      {
        if (null == _properties)
        {
          _properties = new Dictionary<string, string>();
          var appManifestXml = XDocument.Load("WMAppManifest.xml");
          using (var rdr = appManifestXml.CreateReader(ReaderOptions.None))
          {
            rdr.ReadToDescendant("App");
            if (!rdr.IsStartElement())
            {
              throw new System.FormatException(
                 "App tag not found in WMAppManifest.xml ");
            }
            rdr.MoveToFirstAttribute();
            while (rdr.MoveToNextAttribute())
            {
              _properties.Add(rdr.Name, rdr.Value);
            }
          }
        }
        return _properties;
      }
    }

    public string Version
    {
      get { return Properties["Version"]; }
    }

    public string ProductId
    {
      get { return Properties["ProductID"]; }
    }

    public string Title
    {
      get { return Properties["Title"]; }
    }

    public string TitleUc
    {
      get { return !string.IsNullOrEmpty(Title) ? 
                     Title.ToUpperInvariant() : null; }
    }

    public string Genre
    {
      get { return Properties["Genre"]; }
    }

    public string Description
    {
      get { return Properties["Description"]; }
    }

    public string Publisher
    {
      get { return Properties["Publisher"]; }
    }
  }
}

I got some feedback from Matthijs Hoekstra  on the Standard About Page that it actually showed the version number of the dll in which the AboutViewModel is stored, and not that of the app. This is because Assembly.GetExecutingAssembly() is used. There is also Assembly.GetCallingAssembly() but that shows the version of System.Windows.dll. What we need is Assembly.GetEntryAssembly() but that’s not available in the current version of the Windows Phone 7 framework. But we can now adapt the first part of the AboutViewModel as follows:

public class AboutViewModelBase : ViewModelBase
{
  private ManifestAppInfo _manifestAppInfo;
  public void LoadValuesFromResource<T>()
  {
    _manifestAppInfo = new ManifestAppInfo();
    var targetType = GetType();
    var sourceType = typeof(T);
    foreach (var targetProperty in targetType.GetProperties())
    {
      var sourceProperty = sourceType.GetProperty(targetProperty.Name, 
	     BindingFlags.Static | BindingFlags.Public);
      if (sourceProperty != null)
      {
        if (targetProperty.CanWrite)
        {
          targetProperty.SetValue(this, 
		    sourceProperty.GetValue(null, null), null);
        }
      }
    }
  }
  /// <Summary>A string value for the AppTitle</Summary>
  public string AppTitle
  {
    get
    {
      if (DesignerProperties.IsInDesignTool)
      {
        return "APPLICATION TITLE";
      }
      return _manifestAppInfo.Title;
      
    }
  }
  
  public string ApplicationVersion
  {
    get
    {
      if (DesignerProperties.IsInDesignTool)
        return "version x.x.x";

      var version = _manifestAppInfo.Version;
      return version.Substring(0, version.LastIndexOf("."));
    }
  }
}

And have the ViewModel show the version from the Application Manifest file regardless of actual assembly versions - as well as the title. You can even binding directly to its properties.

Now you might not want to use all of its properties directly in text – if your App Title shows up differently in different languages you still might want to get that from a resource file. That is why the LoadValuesFromResource method now checks if a property is writable. If you omit that check, it will try to write to every property for which a key with the same name can be found in the resource file – and if that’s now read-only, it will crash.

01 March 2011

Sharepoint Client Object Model: sites, roles, lists, documents, AD users and permissions

Recently I had my very first encounter with Sharepoint, and I cannot say it was a pleasant meeting. I was doing a proof of concept for a customer to manipulate Sharepoint from code using the new Sharepoint 2010 Client Object Model. Not that this is a particular unpleasant job in itself and neither is the API particulary bad (although definitely odd), but the MSDN documentation about the Client Object Model is far from self-explanatory, and lacks the – for me, at last –  most crucial part of educational material: simple how-to examples.

Most examples found elsewhere are either based on older API’s, incomplete and sometimes completely wrong. And you have to roam about half the internet to get pieces of code together. So I thought it would be a good idea to cobble together pieces from the POC into a comprehensive blog post with what I’ve learned, hoping to save other people the same quest.

Be aware that I learned this all just in the past few days so things are pretty crude at times. I am by no means a Sharepoint wizard - nor am I planning on becoming one :-).  The idea is just to show how it’s done. I think there are a lot of people out there who know how to do things better and more efficient than me: it just they don’t blog about it ;-)

This code was used to talk to a Sharepoint foundation on a domain controller outside the domain on which I actually ran the code.

Things covered in this post

  • Create a site
  • Retrieve a site by title
  • Retrieve a role by Role type
  • Retrieve a Sharepoint principal by Active Directory user or group name
  • Retrieve a document library by name
  • Retrieve a document library template by name
  • Create a document library and set permissions
  • Create a folder in a document library
  • Upload a file to a document library
  • Download a file from a document library
  • List all folders or files in a document library

Setting the stage

It started out making a “Sharepointhelper” class. The basics of this thing is a follows:

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Reflection;
using System.Security.Principal;
using System.Text;
using Microsoft.SharePoint.Client;
using Microsoft.SharePoint.Client.Utilities;
using File = Microsoft.SharePoint.Client.File;

namespace TestSharepoint
{
  public class SharepointHelper
  {
    private ClientContext clientContext;
    private Web rootWeb;

    public SharepointHelper(string url, string username, string password)
    {
      clientContext = new ClientContext(url);
      var credentials = new NetworkCredential(username, password, "domain");
      clientContext.Credentials = credentials;
      rootWeb = clientContext.Web;
      clientContext.Load(rootWeb);
    }
  }
}

Creating the object should go like this:

var sh = new SharepointHelper("http://yourserver", "aUser", "hisPassword");

aUser must be a user with enough rights to perform sharepoint administration. I used the domain admin username and password and I assure you – that works ;-)

Create a site

public void CreateSite(string siteDescription, string siteTitle, string siteUrl)
{
  rootWeb = rootWeb.Webs.Add(new WebCreationInformation
    {
      Description = siteDescription,
      Title = siteTitle,
      Url = siteUrl,
      UseSamePermissionsAsParentSite = false
    });
  clientContext.ExecuteQuery();
}
Usage sample: 
sh.Create("My site description", "MySite", "mysiteurl");

Retrieve a site by title

public Web GetWebByTitle(string siteTitle)
{
  var query = clientContext.LoadQuery(
    rootWeb.Webs.Where(p => p.Title == siteTitle));
  clientContext.ExecuteQuery();
  return query.FirstOrDefault();
}
Usage sample: 
var w = sh.GetWebByTitle("MySite");

Retrieve role by Role type

private RoleDefinition GetRole(string siteTitle, RoleType rType)
{
  var web = GetWebByTitle(siteTitle);
  if (web != null)
  {
    var roleDefs = web.RoleDefinitions;
    var query = clientContext.LoadQuery(
        roleDefs.Where(p => p.RoleTypeKind == rType));
    clientContext.ExecuteQuery();
    return query.FirstOrDefault();
  }
  return null;
}
Usage sample: 
var r = sh.GetRole("MySite", RoleType.Contributor);
will get you the contributor role.

Retrieve a Sharepoint principal by Active Directory user or group name

Now this one took me a very long time. For some reason there is a static Utility.SearchPrincipals method that gets you a PrincipalInfo object, but you can never get to get a Principal object that you can use for setting permissions. I spent a long time scratching my head how to get around this before I found there is another way:
public Principal GetPrincipal(string name)
{
  if (web != null)
  {
    try
    {
      var principal = web.EnsureUser(name);
      clientContext.Load(principal);
      clientContext.ExecuteQuery();
      if (principal != null)
      {
        return principal;
      }
    }
    catch (ServerException){}
  }
  return null;
}
Usage sample: 
var g = sh.GetPrincipal("MyUserGroup");
var u = sh.GetPrincipal("MyUser");

This will, as you can see, get you either a user group’s principal or a single user’s principal. Since I was looking for a group’s principal it never occurred to me to try the “EnsureUser” method. If you don’t know what a Principal is – neither do I (at least not exactly) but I of think it as a descriptor of a user’s or group's credentials.

Retrieve a document library by name

public List GetDocumentLibrary(string siteTitle, string libraryName)
{
  var web = GetWebByTitle(siteTitle);
  if (web != null)
  {
    var query = clientContext.LoadQuery(
         web.Lists.Where(p => p.Title == libraryName));
    clientContext.ExecuteQuery();
    return query.FirstOrDefault();
  }
  return null;
}
Usage sample: 
var g = GetDocumentLibrary("MySite", "myDocumentLibrary");

Retrieve a document library template by name

public ListTemplate GetDocumentLibraryTemplate(Web web, string name)
{
  ListTemplateCollection ltc = web.ListTemplates;
  var listTemplates = clientContext.LoadQuery(
    ltc.Where(p => p.InternalName == name));
  clientContext.Load(ltc);
  clientContext.ExecuteQuery();
  return listTemplates.FirstOrDefault();
}
Usage sample: 
var t = sh.GetDocumentLibraryTemplate(web, "doclib");
This will get you the template for the document library type.

Create a document library and set permissions

Now this was what I actually had to prove in the POC, and you can see this as it uses a lot of the previous samples:

public bool CreateDocumentLibrary(string siteTitle, string libraryName, 
                                  string libraryDescription, string userGroup)
{
  var web = GetWebByTitle(siteTitle);
  if (web != null)
  {
    // First load all the list
    var lists = web.Lists;
    clientContext.Load(lists);
    clientContext.ExecuteQuery();

    // Create new lib based upon the doclib template
    var newList = lists.Add(new ListCreationInformation
      {
        Title = libraryName,
        Description = libraryDescription,
        TemplateType = 
          GetDocumentLibraryTemplate(web, "doclib").ListTemplateTypeKind
      });
    clientContext.ExecuteQuery();

    // Override default permission inheritance
    newList.BreakRoleInheritance(true, false);
    // Get principal for usergroup and the contributor role
    var principal = GetPrincipal(userGroup);
    var role = GetRole(siteTitle, RoleType.Contributor);
    
    // Add the role to the collection.
    var collRdb = new RoleDefinitionBindingCollection(clientContext) {role};
    var collRoleAssign = newList.RoleAssignments;
    collRoleAssign.Add(principal, collRdb);

    clientContext.ExecuteQuery();
    
    return true;
  }
  return false;
}
Usage sample: 
var result = sh.CreateDocumentLibrary("MySite", "myDocumentLibrary",
                                      "A very nice library", "MyUserGroup");

Which will create a document library “myDocumentLibrary” in “MySite” with a contributor role for “MyUserGroup”. Like I said, it’s pretty crude still here and there, but you get the idea

Create a folder in a document library

public void CreateFolder( string siteTitle, string libraryName, string folder)
{
  var list = GetDocumentLibrary(siteTitle, libraryName);
  if (list != null)
  {
    var folders = list.RootFolder.Folders;
    clientContext.Load(folders);
    clientContext.ExecuteQuery();
    var newFolder = folders.Add(folder);
    clientContext.ExecuteQuery();
  }
}
I'll skip the usage sample here, as I suppose it's pretty self-explanatory now.

Upload a file to a document library

public void UploadDocument( string siteTitle, string libraryName, string fileName )
{
  var web = GetWebByTitle(siteTitle);
  var fInfo = new FileInfo(fileName);
  var targetLocation = string.Format("{0}/{1}/{2}", web.ServerRelativeUrl, 
     libraryName, fInfo.Name);
  
  using (var fs = new FileStream(fileName, FileMode.Open))
  {
    File.SaveBinaryDirect(clientContext, targetLocation, fs, true);
  }
}
Usage sample: 
var result = sh.UploadDocument("MySite", "myDocumentLibrary",
                              @"c:\temp\sample.png");
This will upload the file c:\temp\sample.png as "sample.png" in the "myDocumentLibrary" library.

Download a file from a document library

What goes up must come down, eh? This one is a bit odd, as it strips the directory name of the target file and tries to find the file in Sharepoint with it, but it works, so what:

public void DownloadDocument(string siteTitle, string libraryName, 
                             string fileName)
{
  var web = GetWebByTitle(siteTitle);
  var fInfo = new FileInfo(fileName);

  var source = string.Format("{0}/{1}/{2}", web.ServerRelativeUrl, 
                                            libraryName, fInfo.Name);
  var spFileInfo = File.OpenBinaryDirect(clientContext, source);
  using (var fs = new FileStream(fileName, FileMode.OpenOrCreate))
  {
    spFileInfo.Stream.CopyTo(fs);
  }
}
Usage sample: 
sh.DownloadDocument("MySite", "myDocumentLibrary",
                     @"c:\temp\sample.png");
will search for the file "sample.png" in "myDocumentLibrary" and try to download that to c:\temp

Listing files or folders in a document library

And finally:

public List<File> ListFiles(string siteTitle, string libraryName)
{
  var list = GetDocumentLibrary(siteTitle, libraryName);
  var files = list.RootFolder.Files;
  clientContext.Load(files);
  clientContext.ExecuteQuery();
  return files.ToList();
}

public List<Folder> ListFolders(string siteTitle, string libraryName)
{
  var list = GetDocumentLibrary(siteTitle, libraryName);
  var folders = list.RootFolder.Folders;
  clientContext.Load(folders);
  clientContext.ExecuteQuery();
  return folders.ToList();
}

and if you don’t mind, I’ll skip the usage samples here as well.

25 February 2011

Using attached dependency properties to toggle an Application Bar Icon from viewmodel

Application Bar Icon buttons are a look-and-feel-wise very consistent and easy to understand way for every Windows Phone 7 application to give it’s users access to the most important functions. The drawback of this thing is that it’s not a real FrameworkElement, thus you cannot bind commands and other stuff to it, but as I described earlier, this has been solved by the BindableApplicationBar.

But even the BindableApplicationBar has its issues. The IconUri attribute of a BindableApplicationBarIconButton cannot be bound to – for it is no Dependecy Property. Now you can fix that, since Nicolas Humann includes the source code of his excellent solution. But I prefer to threat someone else’s code as third party component, and solved the problem using a very powerful way of extending of Silverlight/Windows Phone 7: attached dependency properties.

The problem I wanted to solve is this: I have changed my MapMania App in such a way that it now tracks your location continually if you press the “Satellite” button. But I want the user to be able to stop tracking as well, using the same button. So what used to be a simple activation button, is now a toggle button. When the user is tracking his own phone, I want the button image to change from the image of of a satellite to an image of a satellite with a big cross through it, indicating “if you press me again, I will stop tracking”. And I wanted this, of course, to be steered from the viewmodel.

This is how I solved it, with three attached dependency properties:

using System;
using System.Windows;
using Phone7.Fx.Preview;

namespace LocalJoost.Utilities
{
  /// <summary>
  /// Supports toggle of a BindableApplicationBarIconButton's icon
  /// </summary>
  public static class AppBarIconFlipper
  {
    #region IconUri
    public static readonly DependencyProperty IconUriProperty =
     DependencyProperty.RegisterAttached("IconUri",
     typeof(Uri),
     typeof(AppBarIconFlipper),
     new PropertyMetadata(IconUriPropertyChanged));

    // Called when Property is retrieved
    public static Uri GetIconUri(DependencyObject obj)
    {
      return obj.GetValue(IconUriProperty) as Uri;
    }

    // Called when Property is set
    public static void SetIconUri(
      DependencyObject obj,
      Uri value)
    {
      obj.SetValue(IconUriProperty, value);
    }

    // Called when property is changed
    private static void IconUriPropertyChanged(
     object sender,
     DependencyPropertyChangedEventArgs args)
    {
      var attachedObject = sender as BindableApplicationBarIconButton;
      if (attachedObject == null) return;
      attachedObject.IconUri = (bool)attachedObject.GetValue(ShowAlernateIconUriProperty)
                     ? (Uri)attachedObject.GetValue(AlernateIconUriProperty)
                     : (Uri)args.NewValue;
    }
    #endregion

    #region AlernateIconUri
    public static readonly DependencyProperty AlernateIconUriProperty =
     DependencyProperty.RegisterAttached("AlernateIconUri",
     typeof(Uri),
     typeof(AppBarIconFlipper),
     new PropertyMetadata(AlernateIconUriPropertyChanged));

    // Called when Property is retrieved
    public static Uri GetAlernateIconUri(DependencyObject obj)
    {
      return obj.GetValue(AlernateIconUriProperty) as Uri;
    }

    public static void SetAlernateIconUri(
      DependencyObject obj,
      Uri value)
    {
      obj.SetValue(AlernateIconUriProperty, value);
    }

    private static void AlernateIconUriPropertyChanged(
     object sender,
     DependencyPropertyChangedEventArgs args)
    {
      var attachedObject = sender as BindableApplicationBarIconButton;
      if (attachedObject == null) return;
      attachedObject.IconUri = (bool)attachedObject.GetValue(ShowAlernateIconUriProperty)
                     ? (Uri)args.NewValue
                     : (Uri)attachedObject.GetValue(IconUriProperty);
    }
    #endregion

    #region ShowAlernateIconUri
    public static readonly DependencyProperty ShowAlernateIconUriProperty =
     DependencyProperty.RegisterAttached("ShowAlernateIconUri",
     typeof(bool),
     typeof(AppBarIconFlipper),
     new PropertyMetadata(ShowAlernateIconUriPropertyChanged));

    public static bool GetShowAlernateIconUri(DependencyObject obj)
    {
      return (bool)obj.GetValue(ShowAlernateIconUriProperty);
    }

    public static void SetShowAlernateIconUri(
      DependencyObject obj,
      bool value)
    {
      obj.SetValue(ShowAlernateIconUriProperty, value);
    }

    private static void ShowAlernateIconUriPropertyChanged(
     object sender,
     DependencyPropertyChangedEventArgs args)
    {
      var attachedObject = sender as BindableApplicationBarIconButton;
      if (attachedObject == null) return;
      var value = (bool)args.NewValue;
      attachedObject.IconUri = value
                     ? (Uri)attachedObject.GetValue(AlernateIconUriProperty)
                     : (Uri)attachedObject.GetValue(IconUriProperty);
    }
    #endregion
  }
}
The only interesting code is in the “***Changed” methods, the rest is just the necessary plumbing. Anyway, in stead of setting the IconUri of the BindableApplicationBarIconButton directly, you use the attached dependency properties like this:
<Phone7Fx:BindableApplicationBarIconButton 
 Command="{Binding ShowLocation}" Text="Track" 
 LocalJoostUtils:AppBarIconFlipper.IconUri="/icons/gps.png"
 LocalJoostUtils:AppBarIconFlipper.AlernateIconUri="/icons/gps_stop.png"
 LocalJoostUtils:AppBarIconFlipper.ShowAlernateIconUri="{Binding IsTracking, Mode=TwoWay}"/>

and depending on the value of the Viewmodel property IsTracking the icon will flip from gps.png (false) to gps_stop (true) – or back.

Once again it shows Microsoft’s XAML-based platforms are as flexible as a rubber band, and wherever are holes in binding, you can almost always plug them using attached dependency properties – the super glue of MVVM, IMHO.

20 February 2011

Marketplace monetization idea: gift items

I seem to be going off-topic a lot these days but I hope you will forgive me for that.

My wife has been eying my new HTC 7 Pro quite a lot, especially since I showed her some of her favorite XBox puzzle games on it. I see where this is going to end – sooner or later (and from the looks of it rather sooner than later) her old Nokia phone will be replaced by something that runs Windows Phone 7 as well. If only because I would like to retain control over my own phone, thank you very much ;-)

And then it started to dawn on me: it would be great to buy gifts for someone else in the Marketplace.

Suppose I am browsing the Marketplace and find a game or piece of music that I know my wife (or anyone else for what matters) would like very much. I would like to be able to buy the item as a gift, i.e. I pay with my live id, but instead of installing the item on my own device I would get the option to enter someone else’s live id, and a personal note. My wife for instance would then get an e-mail on her live account (“Hi luv look what I got you”) with a Zune link, she clicks on it, the Marketplace recognizes it’s already paid for, and she gets her beloved game. Or a romantic song, or whatever.

I have no idea if this is a possible or even a viable scenario, but the thought crossed my mind yesterday evening (when my wife was watching me play a puzzle game on my phone and all but ripped it from my hands) and I just wanted to share it.

What do you think? Sensible idea, or simply not viable (too complicated for the expected ROI).?

19 February 2011

Converter to convert a single item to a list to enable Bing Maps binding

Some things are so simple that I wonder if I am missing something. I tried to bind a single GeoPosition to Bing Maps’ MapItemsControl ItemsSource on Windows Phone 7 and it did not work. Apparently Bing Maps want a list. So I wrote the following converter:

using System;
using System.Collections.Generic;
using System.Globalization;
using System.Windows.Data;

namespace LocalJoost.Convertors
{
  public class ToListConverter : IValueConverter
  {
    public object Convert(object value, Type targetType, object parameter, 
                          CultureInfo culture)
    {
      var l = new List<object> ();
      if (value != null) l.Add(value);
      return l;
    }

    public object ConvertBack(object value, Type targetType, object parameter, 
                              CultureInfo culture)
    {
      return null;
    }
  }
}
A masterpiece of complicated coding, right :-/ ? Anyway, in stead of
<Microsoft_Phone_Controls_Maps:MapItemsControl 
  ItemsSource="{Binding GpsLocation}">
I used
<Microsoft_Phone_Controls_Maps:MapItemsControl 
  ItemsSource="{Binding GpsLocation, Converter={StaticResource ToListConverter}}">

and Lo and Behold – now I did get my single icon on the map.

I have no idea if this is a quirk of the Bing Maps control or that ItemsSource attributes in general only accept lists – but either way, this works.