Cimbalino Toolkit, step by step!

One of the biggest complaints I always had about Cimbalino Toolkit is the lack of documentation and samples!

Granted, some awesome developers like Sara Silva and Scott Lovegrove have done a lot more than I have to promote the toolkit and write some really good code using it, but I think it’s time I take on some of that work!

As such, I’m now making an effort to regularly write articles on Universal Apps development with Cimbalino Toolkit step by step, and here is the first one…

Adding the Cimbalino Toolkit NuGet to a Universal App

Open Visual Studio 2013, click File -> New -> Project, on the Templates on the left select Store Apps -> Universal Apps, on the right select Blank App (Universal Apps), pick a name and hit Ok to save the solution!

Creating a blank Universal App project

Click Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution….

On the top right of the Manage NuGet Packages window you will see a search box; type “Cimbalino” on it and press Enter. You should now be seeing two packages: “Cimbalino Toolkit Core” (compatible with background agents) and “Cimbalino Toolkit” (main component)

Installing Cimbalino Toolkit with NuGet Package Manager

Select “Cimbalino Toolkit” and click on the Install button. You will now see the Select Project window.

Select Projects to install package

Leave all projects of the solution selected and click Ok. You will now see the License Acceptance window, showing the licenses for all packages that will be installed.

License Acceptance

Please review the data and then click I accept to continue with the installation.

After this step, you should now have returned to the Manage NuGet Packages window, and a green checkmark should now be shown on the side of each of the toolkit components.

Packages successfuly installed

Congratulations: you have now successfully installed the Cimbalino Toolkit in your project! :)

Bye MixRadio!

Today was my last day as a MixRadio employee.

After Microsoft completed the acquisition of the Nokia Devices & Services business, MixRadio and all of it’s employees became part of Microsoft.

However, a couple of weeks after that Microsoft started a full reorganization and decisions were quickly made to ensure MixRadio would become a separate entity.

So the only visible changes resulting from the acquisition are actually the company signs around the office, the “blue badges”, and the new email addresses… no other real integration ever happened for MixRadio, so I can’t actually say I felt like a Microsoft employee during this short period!

As a result of all this, plans have been made for the future of MixRadio as a new company that made me believe this is the right time for our paths to come apart.

During my time with the company, I was involved in almost every aspect of the MixRadio Windows Phone client development; every time I open the MixRadio 4.x client in my phone, I can’t help but to feel proud of what this team accomplished.

I wish the very best to MixRadio and all my colleagues in the upcoming future, and I’m sure to keep using MixRadio service as it is by far one of the best streaming music services available!

As for me, I will keep doing what I love, always related with development under Microsoft Technologies, but more to come on this over the next weeks…

Upgrading from the IsolatedStorageSettings to ApplicationData.LocalSettings

When Windows Phone 7 came out, the SDK provided a really easy class to maintain the app settings: the IsolatedStorageSettings.

Basically, the class is an IDictionary<string, object> with a Save() method that will take the instance and serialize it to a file called ”__ApplicationSettings” in the root of the app’s isolated storage.

Now if you upgraded your app from Windows Phone Silverlight 8.0 to the Windows Runtime model, you’ll probably want to migrate the settings from the old format to the new one, right?

Problem is that though the class exists in Windows Phone Silverlight apps, it does not in the new Windows Runtime apps, being replaced with ApplicationData.LocalSettings and ApplicationData.RoamingSettings instead.

So the only solution will be doing it ourselves, by reading and deserializing the “old” settings file!

Here’s a sample of the content of an ”__ApplicationSettings” file from one of my tests:

PhoneApp1.Address, PhoneApp1, Version=, Culture=neutral, PublicKeyToken=null
<ArrayOfKeyValueOfstringanyType xmlns:i="" xmlns=""><KeyValueOfstringanyType><Key>Name</Key><Value xmlns:d3p1="" i:type="d3p1:string">John Doe</Value></KeyValueOfstringanyType><KeyValueOfstringanyType><Key>Age</Key><Value xmlns:d3p1="" i:type="d3p1:int">20</Value></KeyValueOfstringanyType><KeyValueOfstringanyType><Key>Country</Key><Value xmlns:d3p1="" i:type="d3p1:Address"><d3p1:Code>UK</d3p1:Code><d3p1:Name>United Kingdom</d3p1:Name></Value></KeyValueOfstringanyType></ArrayOfKeyValueOfstringanyType>

By looking at the contents of some samples of settings file like the one above, here’s what we can learn:

  • the file has always two lines (second line in the above sample is auto-wrapped to fit the post!)
  • the first line has the known types full names that should be loaded and passed on to the DataContractSerializer constructor, each properly separated by a null char
  • if only basic types are used, the first line will be empty
  • the second line is the serialized xml data

So I wrote the following code snippet to read and deserialize the values from ”__ApplicationSetting” to an IEnumerable<KeyValuePair<string, object>>:

public async Task<IEnumerable<KeyValuePair<string, object>>> GetValuesAsync()
using (var fileStream = await ApplicationData.Current.LocalFolder.OpenStreamForReadAsync("__ApplicationSettings"))
using (var streamReader = new StreamReader(fileStream))
var line = streamReader.ReadLine() ?? string.Empty;
var knownTypes = line.Split('')
.Where(x => !string.IsNullOrEmpty(x))
fileStream.Position = line.Length + Environment.NewLine.Length;
var serializer = new DataContractSerializer(typeof(Dictionary<string, object>), knownTypes);
return (Dictionary<string, object>)serializer.ReadObject(fileStream);
return new Dictionary<string, object>();

So all you now have to do is call the GetValuesAsync() method above and load those values to one of the new Settings repositories!

The Cimbalino Toolkit way

Starting in Cimbalino Toolkit 1.2.0, you’ll be able to use the new IApplicationSettingsService to access Local, Roaming, and Legacy app settings.

In case that wasn’t clear from the names, the Legacy settings will allow you to get the values on the ”__ApplicationSettings” file (do note that only the Values property is implemented, so it’s read-only).

Here are the platform rules for the ISettingsService:

  • Local
    • Supported in all platforms
  • Roaming
    • Supported in all platforms except Windows Phone Silverlight 8.0
  • Legacy
    • Only supported in Windows Phone

One last suggestion: after migrating the legacy settings remember to delete the ”__ApplicationSettings” file as it won’t be needed again! ;)

Cimbalino Toolkit 1.0.0

In case you missed it, there is a new and improved Cimbalino Toolkit now available, supporting the following platforms:

  • Windows Phone Silverlight 8.0 and 8.1 apps (WP8)
  • Windows Phone 8.1 apps (WPA81)
  • Windows Store 8.1 apps (Win81)

The long story

About 3 years ago, the first version of Cimbalino Windows Phone Toolkit was released as a NuGet package with full source code hosted in GitHub to help every on the development of Windows Phone apps!

Back then, Windows Phone 7.0 was the only version available, and that meant that some technical decisions had to be made that influenced the toolkit architecture!

The main one was that WP7 apps Marketplace ingestion would automatically detect every component used in a particular app, and add the required Capabilities for them; so if the toolkit was a single assembly, you’d get your app with the full Capabilities list in the requirements, even if your app didn’t actually use them…

There was also some limitations on the available API’s for Background Agents and once again, the Marketplace ingestion of an app would basically fail if it detected one of those forbidden API‘s.

So the toolkit ended up divided like so:

Cimbalino Windows Phone Toolkit

In light blue are the components that may be used with Background Agents. The rest of the components are divided by Capabilities or 3rd party components requirements.

Then came Windows 8.0 and Windows Phone 8.0, and Microsoft removed the Marketplace Capabilities auto-detection feature (the developer has to declare them manually in the app manifest), so we can now have drop that specific component division requirement! :)

This small change allowed to reduce the create a new Cimbalino Toolkit with just 2 NuGet packages!

There is still a lot of work to be done to port everything from the old toolkit to the new one, but here’s some of the things already working:

  • ApplicationBarBehavior, MultiApplicationBarBehavior, MultiBindingBehavior
  • StorageService, EmailComposeService, MessageBoxService, NavigationService, and others…
  • Most of the extension methods have already been ported, including the PNG support ones
  • Most of the value converters

Also, there is the need to write some new samples and documentation, so if you can I could surely use the help!!! ;)

Here are the new Cimbalino Toolkit NuGet packages:

Please check back soon to read about what’s new and what changed! :)

Bye Nokia... Hello Microsoft!

The deal to transfer substantially all of the Nokia Devices & Services business to Microsoft has now officially been closed.

With it, I proudly become a Microsoft employee! :)

I will always cherish the moment I decided in moving to the UK to work for Nokia (even if that stopped any chance of receiving the Microsoft MVP award, but that’s another story!).

Nokia made me feel that I could actually make a difference with my work, and I truly appreciate the company for the opportunity!

I’ve been working with Microsoft technologies for more time than I can remember, both as a user and also as an IT professional, and I consider getting the “blue badge” as a giant career step for me!

In the present moment this doesn’t bring any significant changes: I’ll carry on working in the MixRadio apps here in Bristol, as I did until today!

Thank you Nokia, it’s been really fun… Hello Microsoft! :)

Cimbalino Windows Phone Toolkit Updated to v3.2.3

Version 3.2.3 of Cimbalino Windows Phone Toolkit is now available!

As previously indicated, this will probably be the last version still supporting Windows Phone 7…

Here’s the change log starting from version 3.2.0 to the current 3.2.3:

  • v3.2.1
    • New WebRequestExtensions
    • Ensured that MarketplaceInformationService doesn’t cache the results
  • v3.2.2
    • New EventHandlerExtensions
    • Improved the MultiBindingBehavior by adding the missing Mode property
    • Improved the ShellTileServiceTile to enable tiles update with XML data
    • Fixed a couple of issues on MarketplaceInformationService related to “beta apps”
  • v3.2.3
    • New SaveRingtoneService
    • New ScreenCaptureBehavior
    • New FrameworkElementExtensions
    • DeviceInfo, Location, and UserInfo components can now be used inside Background Agents
    • Improved ShellToastService to add the custom sound support

There are other improvements and bug fixes not stated here, but also quite important too! :)

WrapPanel is great, so please, stop using it!

The WrapPanel control (part of the Windows Phone Toolkit) is a really useful control container.

Having said that, you should definitely avoid using it in your apps if you are planing to use in ListBox.ItemsPanel for large lists items presented with fixed size!!

To demonstrate my point, let’s say we have a list of 10 items:

{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}

Now say we want to list 3 items per row and them wrap to the next row, we can use a WrapPanel container control, like so:

<ListBox x:Name="ItemsListBox"
ItemTemplate="{StaticResource ItemDataTemplate}">
<toolkit:WrapPanel />

The resulting items layout will look something like the following picture:

WrapPanel layout

This will work fine with 10 items, but what about 100? Or 1.000? Or even 10.000?

Using a WrapPanel with a large number of items will cause the control loading time and memory usage to increase, and if you make it large enough, you’ll probably start seeing your app crash with “out of memory” errors…

Now lets say we first group the items in groups of 3, making the source list look like this:

{ {0, 1, 2}, {3, 4, 5}, {6, 7, 8}, {9} }

All we now need is another ItemsControl inside our main ListBox to iterate the each group, something like this:

<ListBox x:Name="ItemsListBox">
<ItemsControl ItemTemplate="{StaticResource ItemDataTemplate}" ItemsSource="{Binding}">
<VirtualizingStackPanel Orientation="Horizontal" />

Here’s the resulting layout schematic:

Smart Wrapping layout

Major advantages with this approach is the obvious performance improvement and memory consumption reduction. Why? Because we maintained the VirtualizingStackPanel in our main ListBox.ItemsPanel!

To prove my point, I’ve created a small demonstration app showing the result of using these two approaches with a list of 400 items.

Download the code, deploy it on a phone or emulator, then run each approach separately and exit the app after each run in order to check the peak memory usage.

You’ll notice a huge difference in loading times, but I can tell you that memory wise, it’s the difference between using 120MB or just 20MB! :)

Poll: What are your plans for #wp7dev

As I am about to start adding Windows Phone “Blue” support to Cimbalino Windows Phone Toolkit, I’m planning to stopping the WP7 support on the 3.x!

The upcoming 4.x would have WP8 and WP Blue support, allowing for a more future prune implementation and dropping the NuGet packages from 9 to just 2 (the Background package as it stands today and a main one with all the rest).

To actually understand the position of the Windows Phone developers about WP7 development, I started a poll that I now invite you to answer! :)