Caliburn Micro Part 1: Getting Started

A few days ago I blogged about our new Dashboard sample included in WPF Elements. The sample demonstrates how to create a sales dashboard using a few of our WPF controls like the Data Grid, Time Explorer and Charts. It was built with the help of the Caliburn Micro framework to give it a robust MVVM architecture. In this blog post I’ll walk you through a simple tutorial for getting started with using Caliburn Micro in a WPF application. This is just part 1 in a series I will be writing so I hope you’ll subscribe and follow along with me as we build up to a useful application.

Step 1: Getting Started

Caliburn Micro targets .NET framework 4.0, so you’ll need Visual Studio 2010 to create the application. Start by creating a new WPF Application and add a reference to Caliburn.Micro.dll and System.Windows.Interactivity.dll which come with the Caliburn Micro download. Since Caliburn Micro is going to take care of creating the window for you, delete MainWindow.xaml and remove the StartupUri attribute from App.xaml. App.xaml will now look like this:

<Application x:Class="CaliburnMicroApp.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <Application.Resources>
 
  </Application.Resources>
</Application>

Step 2: The View Model

Caliburn Micro promotes a View-Model-First approach, so the next step is to add a class to represent the view model. Large applications can have many view models, each of which provides the logic for a different view. Below is a code example of an empty view model. Since this tutorial is focused on simply getting started with incorporating Caliburn Micro into a WPF application, we are not going to make the view model do anything for now.

using Caliburn.Micro;
 
namespace CaliburnMicroApp
{
  public class AppViewModel : PropertyChangedBase
  {
 
  }
}

The first thing to notice here is the name of the class. Caliburn Micro expects a particular naming convention so it can hook up the view model to the appropriate view. The class name of a view model should end with “ViewModel”. What you put in front of “ViewModel” is up to you. The other thing to notice here is that this class extends the PropertyChangedBase. This is provided by Caliburn Micro and makes it easy to raise property change notifications without needing to implement INotifyPropertyChanged in all your view models. Although this example view model doesn’t do anything, I’ve included the PropertyChangedBase as good practice. When adding properties to the view model, it will come in handy.

Step 3: The View

In order to display something in the window, you’ll need to create a view for the view model created in the previous step. This is as simple as adding a new UserControl to the project as seen below. I should point out again that Caliburn Micro expects a particular naming convention so it can hook up the view to the appropriate view model. View names should end with “View” and start with the same name you used for the view model. So for my example here, “AppView” is the view for rendering the “AppViewModel”. In the code below I have also set the width, height and background of the grid so that when you run this application you can see that it is working correctly.

<UserControl x:Class="CaliburnMicroApp.AppView"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">
  <Grid Width="300" Height="300" Background="LightBlue">
 
  </Grid>
</UserControl>

Step 4: The Bootstrapper

The bootstrapper is the mechanism used to incorporate Caliburn Micro into your application. It is also a place where you can configure the framework for the needs of your application. For the purposes of this tutorial, I have used a very simple bootstrapper implementation seen here:

using Caliburn.Micro;
 
namespace CaliburnMicroApp
{
  public class AppBootstrapper : Bootstrapper<AppViewModel>
  {
  }
}

Caliburn Micro has 2 different bootstrappers available. The one used above lets you set the generic type to be the view model that you want to be used at startup. The last step is to tell the application to use the bootstrapper. This is done by adding your bootstrapper to a resource dictionary in App.xaml. After doing this, App.xaml will now look something like this:

<Application x:Class="CaliburnMicroApp.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:local="clr-namespace:CaliburnMicroApp"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <Application.Resources>
    <ResourceDictionary>
      <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary>
          <local:AppBootstrapper x:Key="bootstrapper" />
        </ResourceDictionary>
      </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
  </Application.Resources>
</Application>

And that’s it

Stay tuned for Part 2 to see something with a little more substance

Now when you run up the application, you’ll see a small window with a light blue background. Your application is now primed and ready to take advantage of all the great support provided by Caliburn Micro. It’s easy to get help for using this framework due to its growing community. You can also look through the documentation on CodePlex.

You can grab the full Visual Studio 2010 solution I made for this tutorial here.

In the next part of this blog series we will look at adding some interactivity using events and data binding with the help of Caliburn Micro.

Until next time, Happy Coding!

Tagged as General, WPF

22 Responses to “Caliburn Micro Part 1: Getting Started”

  • Nice intro and well written. Looking forward to your take on the other conventions.

  • Thank you for the simple introduction. I’m looking forward to the rest of the series.

  • [...] 1: Getting Started Part 2: Data Binding and Events Part 3: More About Events and Parameters Part 4: The Event [...]

  • Nice tutorial.
    Can you please put here the links from the other parts ?

  • Hello terroare

    I have now included a link to the next part near the end of each blog post so you can follow them more easily.

  • This tutorial helped me. Thank you!

    Just wanted to mention in case it helps someone else, that Visual Studio 2012 Intellisense complains about this:

    saying an assembly or reference is not found, until you build the solution and then it is fine.

  • Looks like the Comments page stripped my XML. The part Intelliense complains about, until you build, is this:

    local:AppBootstrapper x:Key=”bootstrapper”

  • Cool,Tanks. I would have flattr you if you had an Account :)

  • You can flattr us by purchasing WPF Elements! :-)

  • Really good, quick article. I couldn’t find anything like this on the actual Caliburn codeplex site. Really appreciated this.

  • [...] to write a lot of boiler plate code for plumbing their applications together. You can read a more in depth tutorial series about Caliburn Micro on our [...]

  • very well written ..

  • Sir,

    Big Problem
    —————–

    i have 4 views

    mainview , 1st view ,2nd view and 3rd view

    mainview contain conductor—>for displaying 1st,2nd and 3rd view…..

    my question is How to call 2nd view from 1st view…using mainviewmodel…urgent reply needed

  • Hello Abdul

    The views themselves shouldn’t call other views, but their view models can communicate with each other to update data. One of the ways to send messages between view-models is by using the event aggregator: http://www.mindscapehq.com/blog/index.php/2012/2/1/caliburn-micro-part-4-the-event-aggregator/

  • This is a nice way to get comfortable with Caliburn.Micro. Thank you for all the effort you have put into these tutorials.

  • Good tutorial. Thank you.

  • Hello. First I want to thank you for getting this out and made very simple. Next I would like to ask: Normal practices tell me to create layers in my app for the ViewModels, Views, and Models. Doing this in the sample gives me an error stating that the Bootstrapper cannot locate my view(named as explained above). To serve as an example: View name is MainView; ViewModel name is MainViewModel.

    So to my question: Do the views and viewmodels need to be in the same base folder in order for this to correctly work?

    Thanks!

  • Hello Mike

    I don’t think they need to be in the same base folder. I usually put the views and the view-models in separate folders somewhere in the project. Did you remove the Class=”…” property from the user control xaml code? Doing so can cause this kind of exception. If you still see this exception, you can send the project to jason@mindscape.co.nz and I’ll see if I can find the solution.

  • Hello Jason,
    I really thank you for providing this great tutorial and making the caliburn framework so easy to understand. It was really hard for me to understand this framework as there we no much tutorials. But thumps up for this tutorial. Hope to get such kind of tutorials from you even in future.

  • Thanks Nomesh

    I’m glad the tutorial has helped you work with Caliburn Micro! I hope our other tutorials in the Caliburn Micro tutorial series will help you too.

  • Hello Jason,
    I would like to en-light a point in the earlier comments by Mike which which states
    “Do the views and viewmodels need to be in the same base folder in order for this to correctly work?”.

    I too made the seperate directory for view and viewmodel and it does not works for me too. I get the error as Bootstrapper cannot locate view.
    Can you please explain what might be the problem and how to fix it.

  • Hello Nomesh

    If you added the view and view-models directly into the different folders (as opposed to dragging them from a common folder), then your view and view-model are probably in different namespaces. I think they need to be in the same namespace in order for Caliburn Micro to match them up. Try setting their namespaces to be the same to see if that solves the problem. If not, try add the view and view-model to the same folder to see if there is some other problem involved. If your project is simple so far (or if you can build a simple repro project) fell free to send it to jason@mindscape.co.nz and I’ll take a quick look.

  • Leave a Reply

Archives

Join our mailer

You should join our newsletter! Sent monthly:

Back to Top