Using Caliburn Micro with Universal App projects

Posted on Apr 17, 2014 | Categories: app, caliburnmicro, universal


In this blogpost I’ll discuss how to set up a Universal Windows Store app using the Caliburn.Micro framework. This blogpost is based on the sample code provided with the Caliburn Micro framework.

You can find the sample code which is provided with the Caliburn Micro framework here: https://github.com/BlueSpire/Caliburn.Micro/tree/master/samples/CM.HelloUniversal. The goal of this all is to reuse as much as possible code in both our Windows Phone 8.1 as well as your Windows 8.1 application. (As is the goal of the Universal App template.)

Preparing your project

Probably one of the most important things in this part of the project is to add the Caliburn.Micro framework to your project. At the time of writing you have to use version 2.0.0-beta2. The easiest way to get the latest version is to use the following NuGet command in the NuGet Command line:

PM> Install-Package Caliburn.Micro –Pre

Also, please don’t forget to add this package to the Windows project as wel as the Windows Phone project.

Let’s start

Now, we can begin with the real work with the Caliburn Micro framework. Whatsoever, as experienced Caliburn Micro developers already know, Caliburn Micro requires a custom application setup. Because the Windows Phone 8.1 platform is closely aligned with Windows 8.1 (95% core reuse) here we are going to merge programing the Caliburn Micro programming principles from Windows and Windows Phone platform. As already mentioned here (http://compiledexperience.com/blog/posts/caliburn-micro-universal) most of the programming tutorials about using Caliburn Micro on Windows 8 will apply. Well, sorry for the delay, let’s start with some real coding!

To start, happily we have just one App.xaml file in our solution which you can find in the [ProjectName].Shared project. Let’s remove all content from the App.xaml.cs and replace it with this code:

private WinRTContainer container;
public App()
{
    InitializeComponent();
}

protected override void Configure()
{
    container = new WinRTContainer();
    container.RegisterWinRTServices();
}

protected override void OnLaunched(LaunchActivatedEventArgs args)
{

}

protected override object GetInstance(Type service, string key)
{
    return container.GetInstance(service, key);
}

protected override IEnumerable <object> GetAllInstances(Type service)
{
    return container.GetAllInstances(service);
}

protected override void BuildUp(object instance)
{
    container.BuildUp(instance);
}

But, we’re not done with this yet. To make this code work we have to edit our App.xaml file so it becomes a caliburn.CaliburnApplication instead of just an Application. To achieve this you can simply replace all the code in your App.xaml file with this (Where you replace [AppName] with the name of your app:

<micro:CaliburnApplication
    x:class="[AppName].App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:micro="using:Caliburn.Micro">
</micro:CaliburnApplication>

The above codes are almost the same as shown here on the Caliburn Micro codeplex website. (http://caliburnmicro.codeplex.com/wikipage?title=Working%20with%20WinRT) If you need more information I recommend you to check out the documentation on the Caliburn Micro codeplex page.

View First or (View)Model First

Caliburn Micro supports two common approaches on page navigation. The first one is View First and the second one is (View)Model First. By myself I prefer to use the Model First approach because that’s where my cheese is.

For people not familiar with these concepts, by using the View First method you navigate to your views (Views/MainPage.xaml). With the Model First approach you navigate to your Models (ViewModels/MainPageViewModel.cs). Notice you can use both methods beside each other.

When setting up your project using View First

You have to add an additional method to enable the View First approach. You can copy/paste this code in your App.xaml.cs file.

protected override void PrepareViewFirst(Frame rootFrame)
{
    container.RegisterNavigationService(rootFrame);
}

Once this is done you can navigate to the landing page in your application by executing the next code in your OnLaunched event.

DisplayRootView<MenuView>();

When setting up your project using (View)Model First

Using The View Model approach there is much less to initialize in your App.xaml.cs file. This way you can simple execute the following code in the OnLaunched event to navigate to your landing page’s View Model which handles all other stuff like showing the View itself.

DisplayRootViewFor<MenuViewModel>();

Setting up the Views and the ViewModels

Right now we’ve set up the basics for using Caliburn Micro in an Universal App solution. What’s next; we need to set up some stuff in both Windows Platform projects. If I haven’t told you, Caliburn Micro makes heavy use of naming conventions. This is why we have to add some folders to our projects.

Add a folder named “Views” to all three projects in your solution. Add a folder named “ViewModels” to your [SolutionName].Shared project. As you may or may not already know, we’re going to store our Views and ViewModels in these folders.

Adding Views

Adding Views is as simple as adding an new page to your application. Nothing more nothing less. In these Views whatsoever I may recommend you to make use of your ViewModel, but more on that later. Oh, as on naming conventions, don’t forget you should add ‘View’ behind the name of your View. (eg, MainView, CharacterView, DetailView etc)

Adding ViewModels

Adding ViewModels is a little bit more complicated. Start by adding an class file which, is also naming convention, carries the name of the View on which it is (or has to be) connected. Also it has to end with ‘ViewModel’. (eg, MainViewModel, CharacterViewModel, DetailViewModel etc)

Also, when you actually want to use your ViewModels (ViewModels for Screens, a principe in Caliburn Micro on which you can read more than you want here: http://caliburnmicro.codeplex.com/wikipage?title=Screens%2c%20Conductors%20and%20Composition&referringTitle=Documentation) you have to register them in the Configure event in your App.xaml.cs file. For example, if you want to register the MainViewModel you can do it this way:

container.PerRequest<MainViewModel>();

Here comes a warning: DON’T FORGET, I REPEAT, DON’T FORGET TO MAKE YOUR VIEW MODEL CLASS PUBLIC!!! This prevents your application from crashing and you searching for hours for that strange bug.

In these ViewModels you can do whatever you want. For a guide on how to use event handlers, or also known as actions, I’m happy to redirect you to the excellent articles from Matteo Pagani (@qmatteoq on Twitter) about Caliburn Micro actions which you can find here: http://wp.qmatteoq.com/first-steps-with-caliburn-micro-in-windows-phone-8-actions/.

Navigation in Caliburn Micro isn’t that difficult. The only thing you have to remind yourself off is that you are navigating to ViewModels instead of Views. (If you follow the ViewModel First methodology) Because the default navigation navigates to the views we have to set Caliburn Micro’s custom navigation service. And we do it this way:

private INavigationService navigationService;
public MainViewModel(INavigationService navigationService)
{
    this.navigationService = navigationService;
}

Here we declare the navigation service which we later use to navigate to our ViewModels, and we do that this way:

navigationService.UriFor<CharacterViewModel>().Navigate();

Practically the only thing you have to do is declare the ViewModel you want to navigate to and then you fire the Navigate event to actually navigate to there. That’s it all! You’re ready to go! :)

If you want to see a working example of the Universal App template combined with Caliburn Micro you can get the source here: https://github.com/BlueSpire/Caliburn.Micro/tree/master/samples/CM.HelloUniversal. For more guides on how to use Caliburn Micro I can heavily recommend these guides from Matteo Pagani: http://wp.qmatteoq.com/first-steps-with-caliburn-micro-in-windows-phone-8-the-theory/

If you have further questions, don’t hesitate to contact me! (@CorstianBoerman on Twitter)