A Comprehensive Guide to Creating a Xamarin.Forms App with MvvmCross (Part 1 of 5)

June 15, 2015 // By Brent Edwards

Xamarin.Forms is a cool addition to the Xamarin offering. Xamarin.Forms is a layer built on top of Xamarin that allows developers to create apps for Android, iOS, and Windows Phone using a single codebase. This lowers the barrier of entry significantly for .NET developers to write mobile apps. Xamarin.Forms offers a suite of controls and layouts that can be used to build up applications that will look like native applications on each of the supported platforms. These controls allow developers to add a mobile user interface to their applications which will interact with their .NET code under the hood. Being able to work in the familiar .NET environment and leverage existing .NET code is a huge plus for .NET developers.

Xamarin.Forms provides two different ways to build up the mobile UI: using C# code and using XAML. If you are comfortable working with XAML from other technologies, such as Windows Presentation Foundation, Silverlight, Windows Phone, or Windows Store apps, I highly recommend taking the time to learn how to work with XAML in Xamarin.Forms. The XAML is different in Xamarin.Forms, but it will be familiar while still providing the power of data binding and templating that you have (hopefully) come to know and love. Along with the other XAML technologies came the concept of Model-View-ViewModel (MVVM) and Xamarin.Forms is no different. In fact, Xamarin.Forms has its own MVVM functionality built-in.

If you are planning to only write a Xamarin.Forms app, without any additional apps on different platforms, the built-in MVVM functionality may suit your needs just fine. However, if you’re interested in also creating, say, Universal Windows apps alongside your Xamarin.Forms apps, you’ll need to look outside of the Xamarin.Forms MVVM functionality in order to write view models that are useful for all your apps. That’s where something like MvvmCross comes into play. MvvmCross is an MVVM framework that is designed to be as cross-platform as possible. With support for Xamarin and Windows platforms, MvvmCross provides a lot of reusability for your view model layer.

Unfortunately, it’s not necessarily a straight-forward process to get your Xamarin.Forms app up and running with MvvmCross. There are resources scattered around the web that help, but nothing comprehensive that gets you up and running after starting from scratch. After having to do it several times on my own the hard way, I decided to write down the steps and make a comprehensive guide. As I mentioned, this is not a straight-forward process, which means there are a lot of steps to go from zero to hero with Xamarin.Forms and MvvmCross. I’ve broken the steps into 5 logical parts, with this being the first.

This guide assumes that you will be targeting all of the platforms supported by Xamarin.Forms (Android, iOS, and Windows Phone) and have the proper tools installed (Visual studio 2013 or later and Xamarin). Having multiple projects in the solution is unavoidable, so most of the steps will call out which project it is targeted for.

There are two important things to be aware of before starting to follow this guide. The first thing is that the guide works for both portable class libraries (PCLs) and universal shared projects. Many of the examples you will find online for working with Xamarin.Forms or MvvmCross will use PCLs and that may be the way to go for your application as well. However, there is one big gotcha that you may end up finding out the hard way: PCLs only let you reference other PCLs. That means you may run into problems as you start to bring in your favorite libraries because they may not be compiled as PCLs. Two notable libraries I’ve found in the apps I’ve written that don’t support PCL are CSLA and Azure Mobile Services (particularly the Microsoft.WindowsAzure.Mobile.Ext assembly that adds the nice UI integration). So, if you plan to go the PCL route, do a little research before you begin to make sure you won’t run into any issues with libraries you plan to use. No such limitation exists for universal shared projects.

The next big gotcha to be aware of before beginning with this guide will become obvious when you start to include your view model layer in other apps, such as Universal Windows apps. While the view model layer is able to be shared, the view layer is not (because it’s built with Xamarin.Forms). The way I deal with this is to put the view models and shared code into one project, which contains no references to Xamarin.Forms. Then I put the views and Xamarin.Forms-specific code into another project, adding a reference to the view model project. You can then reference the view model project in your other non-Xamarin.Forms projects.

This guide will contain a lot of code samples necessary to thread the application foundation together. You can see working app samples for both portable class library and shared project references are out on github: https://github.com/brentedwards/XFormsCrossTemplate.

Let’s begin.

1. Create a Xamarin.Forms Project. Either Portable or Shared. (I’ve called mine XFormsCrossTemplate.Portable and XFormsCrossTemplate.Shared)
1. Note: I took it a step further and added a solution folder called UI for all of the UI projects. I can then add additional solution folders for other layers as I build the application. This is an optional step, but the namespaces in this guide will reflect this additional step I took.

In the Android project:

2. Change the Assembly name to remove '.' characters. In my example, the result is: XFormsCrossTemplateUI.
1. To do this, right-click on project, select Properties, then select Application from the list on the left.

3. Change the default namespace to remove Droid or Android reference. In my example, the result is: XFormsCrossTemplate.UI.

4. Add an ANDROID compiler directive for all build configurations. This is for future Android-specific stuff.
   1. In the project properties page, select Build from the list on the left.
   2. Add the compiler directive to each of the configurations in the Configuration drop-down list at the top.

In the iOS project:

5. Change the Assembly name to remove iOS. In my example, the result is: XFormsCrossTemplateUI.
1. To do this, right-click on project, select Properties, then select Application from the list on the left.

6. Change the default namespace to remove iOS reference. In my example, the result is: XFormsCrossTemplate.UI.

7. Add an IOS compiler directive for all build configurations. This is for future iOS-specific stuff.
1. In the project properties page, select Build from the list on the left.
2. Add the compiler directive to each of the configurations in the Configuration drop-down list at the top.

In the WinPhone project:

8. This step is only if using a Universal Shared Project and not a PCL. Change the Assembly name to remove WinPhone. For my example, the result is: XFormsCrossTemplate.UI.
1. Note: With a PCL project, an actual assembly is already created. Removing WinPhone from the name will cause a conflict.

9. Change the default namespace to remove WinPhone reference. For my example, the result is: XFormsCrossTemplate.UI
1. To do this, right-click on project, select Properties, then select Application from the list on the left.

That takes us to the end of Part 1. So far, we’ve created a Xamarin.Forms app for Android, Windows Phone, and iOS, and set it up for future integration with MvvmCross. We now have the foundation in place that we are going to continue to build on over the next four posts in the series. In the next post, we will incorporate MvvmCross into our solution. Stay tuned…

You’ve just read part 1 of the “Comprehensive Guide to Creating a Xamarin.Forms App with MvvmCross” blog series. To read part 2, click here. If you’d like to contact Magenic, email us or call us at 877-277-1044.

Categories // Mobile
Tags // Xamarin, Xamarin.Forms, MvvmCross, MVVM, Android, iOS, WindowsPhone